HTTP

[Stable: 2 - Stable]

Stable: 2 Estabilidade: 2 - Estável

Código-fonte: lib/http.js

Este módulo, contendo um cliente e um servidor, pode ser importado via require('node:http') (CommonJS) ou import * as http from 'node:http' (módulo ES).

As interfaces HTTP no Node.js são projetadas para suportar muitos recursos do protocolo que tradicionalmente eram difíceis de usar. Em particular, mensagens grandes, possivelmente codificadas em partes. A interface tem o cuidado de nunca armazenar em buffer requisições ou respostas inteiras, para que o usuário possa transmitir dados.

Os cabeçalhos de mensagens HTTP são representados por um objeto como este:

{
  "content-length": "123",
  "content-type": "text/plain",
  "connection": "keep-alive",
  "host": "example.com",
  "accept": "*/*"
}

As chaves são convertidas para minúsculas. Os valores não são modificados.

Para dar suporte a todo o espectro de possíveis aplicações HTTP, a API HTTP do Node.js é de baixo nível. Ela lida apenas com o processamento de fluxos e análise de mensagens. Ela analisa uma mensagem em cabeçalhos e corpo, mas não analisa os cabeçalhos ou o corpo propriamente ditos.

Consulte message.headers para obter detalhes sobre como os cabeçalhos duplicados são tratados.

Os cabeçalhos brutos, conforme foram recebidos, são mantidos na propriedade rawHeaders, que é um array de [chave, valor, chave2, valor2, ...]. Por exemplo, o objeto de cabeçalho de mensagem anterior pode ter uma lista rawHeaders como a seguinte:

;[
  'ConTent-Length',
  '123456',
  'content-LENGTH',
  '123',
  'content-type',
  'text/plain',
  'CONNECTION',
  'keep-alive',
  'Host',
  'example.com',
  'accepT',
  '*/*',
]

Classe: http.Agent

Adicionado em: v0.3.4

Um Agent é responsável por gerenciar a persistência e reutilização da conexão para clientes HTTP. Ele mantém uma fila de requisições pendentes para um determinado host e porta, reutilizando uma única conexão de soquete para cada uma até que a fila esteja vazia, momento em que o soquete é destruído ou colocado em um pool onde é mantido para ser usado novamente para requisições para o mesmo host e porta. Se ele é destruído ou agrupado depende da opção keepAlive.

As conexões agrupadas têm o TCP Keep-Alive habilitado para elas, mas os servidores ainda podem fechar conexões ociosas, caso em que elas serão removidas do pool e uma nova conexão será feita quando uma nova requisição HTTP for feita para aquele host e porta. Os servidores também podem se recusar a permitir várias requisições pela mesma conexão, caso em que a conexão terá que ser refeita para cada requisição e não poderá ser agrupada. O Agent ainda fará as requisições para esse servidor, mas cada uma ocorrerá por uma nova conexão.

Quando uma conexão é fechada pelo cliente ou pelo servidor, ela é removida do pool. Quaisquer soquetes não utilizados no pool serão desreferenciados para não manter o processo Node.js em execução quando não houver requisições pendentes. (consulte socket.unref()).

É uma boa prática, destroy() uma instância Agent quando ela não estiver mais em uso, porque soquetes não utilizados consomem recursos do SO.

Os soquetes são removidos de um agente quando o soquete emite um evento 'close' ou um evento 'agentRemove'. Ao pretender manter uma requisição HTTP aberta por muito tempo sem mantê-la no agente, algo como o seguinte pode ser feito:

http
  .get(options, res => {
    // Faça algo
  })
  .on('socket', socket => {
    socket.emit('agentRemove')
  })

Um agente também pode ser usado para uma requisição individual. Ao fornecer {agent: false} como uma opção para as funções http.get() ou http.request(), um Agent de uso único com opções padrão será usado para a conexão do cliente.

agent:false:

http.get(
  {
    hostname: 'localhost',
    port: 80,
    path: '/',
    agent: false, // Crie um novo agente apenas para esta requisição
  },
  res => {
    // Faça algo com a resposta
  }
)

new Agent([options])

[Histórico]

Versão	Mudanças
v15.6.0, v14.17.0	Alteração do agendamento padrão de 'fifo' para 'lifo'.
v14.5.0, v12.20.0	Adição da opção scheduling para especificar a estratégia de agendamento de socket livre.
v14.5.0, v12.19.0	Adição da opção maxTotalSockets ao construtor do agente.
v0.3.4	Adicionado em: v0.3.4

• options <Objeto> Conjunto de opções configuráveis a serem definidas no agente. Pode ter os seguintes campos:
  • keepAlive <boolean> Mantém os sockets mesmo quando não há solicitações pendentes, para que possam ser usados para solicitações futuras sem precisar restabelecer uma conexão TCP. Não deve ser confundido com o valor keep-alive do cabeçalho Connection. O cabeçalho Connection: keep-alive é sempre enviado ao usar um agente, exceto quando o cabeçalho Connection é especificado explicitamente ou quando as opções keepAlive e maxSockets são definidas como false e Infinity, respectivamente, caso em que Connection: close será usado. Padrão: false.
  • keepAliveMsecs <number> Ao usar a opção keepAlive, especifica o atraso inicial para pacotes TCP Keep-Alive. Ignorado quando a opção keepAlive é false ou undefined. Padrão: 1000.
  • maxSockets <number> Número máximo de sockets a serem permitidos por host. Se o mesmo host abrir várias conexões simultâneas, cada solicitação usará um novo socket até que o valor de maxSockets seja atingido. Se o host tentar abrir mais conexões do que maxSockets, as solicitações adicionais entrarão em uma fila de solicitações pendentes e entrarão no estado de conexão ativa quando uma conexão existente for encerrada. Isso garante que haja no máximo maxSockets conexões ativas em qualquer momento, de um determinado host. Padrão: Infinity.
  • maxTotalSockets <number> Número máximo de sockets permitidos para todos os hosts no total. Cada solicitação usará um novo socket até que o máximo seja atingido. Padrão: Infinity.
  • maxFreeSockets <number> Número máximo de sockets por host para deixar abertos em um estado livre. Relevante apenas se keepAlive estiver definido como true. Padrão: 256.
  • scheduling <string> Estratégia de agendamento a ser aplicada ao escolher o próximo socket livre a ser usado. Pode ser 'fifo' ou 'lifo'. A principal diferença entre as duas estratégias de agendamento é que 'lifo' seleciona o socket usado mais recentemente, enquanto 'fifo' seleciona o socket usado menos recentemente. Em caso de baixa taxa de solicitações por segundo, o agendamento 'lifo' reduzirá o risco de escolher um socket que pode ter sido fechado pelo servidor devido à inatividade. Em caso de alta taxa de solicitações por segundo, o agendamento 'fifo' maximizará o número de sockets abertos, enquanto o agendamento 'lifo' o manterá o mais baixo possível. Padrão: 'lifo'.
  • timeout <number> Tempo limite do socket em milissegundos. Isso definirá o tempo limite quando o socket for criado.

options em socket.connect() também são suportados.

Para configurar qualquer um deles, uma instância personalizada de http.Agent deve ser criada.

ESM

import { Agent, request } from 'node:http'
const keepAliveAgent = new Agent({ keepAlive: true })
options.agent = keepAliveAgent
request(options, onResponseCallback)

CJS

const http = require('node:http')
const keepAliveAgent = new http.Agent({ keepAlive: true })
options.agent = keepAliveAgent
http.request(options, onResponseCallback)

agent.createConnection(options[, callback])

Adicionado em: v0.11.4

• options <Object> Opções contendo detalhes da conexão. Verifique net.createConnection() para o formato das opções
• callback <Function> Função de callback que recebe o socket criado
• Retorna: <stream.Duplex>

Produz um socket/stream para ser usado para requisições HTTP.

Por padrão, esta função é a mesma que net.createConnection(). No entanto, agentes personalizados podem substituir este método caso se deseje maior flexibilidade.

Um socket/stream pode ser fornecido de uma de duas maneiras: retornando o socket/stream desta função ou passando o socket/stream para callback.

Este método tem a garantia de retornar uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket>.

callback tem uma assinatura de (err, stream).

agent.keepSocketAlive(socket)

Adicionado em: v8.1.0

• socket <stream.Duplex>

Chamado quando socket é separado de uma requisição e pode ser persistido pelo Agent. O comportamento padrão é:

socket.setKeepAlive(true, this.keepAliveMsecs)
socket.unref()
return true

Este método pode ser substituído por uma subclasse Agent específica. Se este método retornar um valor falsy, o socket será destruído em vez de persistir para uso na próxima requisição.

O argumento socket pode ser uma instância de <net.Socket>, uma subclasse de <stream.Duplex>.

agent.reuseSocket(socket, request)

Adicionado em: v8.1.0

• socket <stream.Duplex>
• request <http.ClientRequest>

Chamado quando socket é anexado a request depois de ser persistido por causa das opções keep-alive. O comportamento padrão é:

socket.ref()

Este método pode ser substituído por uma subclasse Agent específica.

O argumento socket pode ser uma instância de <net.Socket>, uma subclasse de <stream.Duplex>.

agent.destroy()

Adicionado em: v0.11.4

Destrói qualquer socket que esteja em uso pelo agente.

Geralmente, não é necessário fazer isso. No entanto, se estiver usando um agente com keepAlive habilitado, é melhor desligar explicitamente o agente quando ele não for mais necessário. Caso contrário, os sockets podem permanecer abertos por um longo período antes que o servidor os finalize.

agent.freeSockets

[Histórico]

Versão	Mudanças
v16.0.0	A propriedade agora tem um protótipo null.
v0.11.4	Adicionado em: v0.11.4

• <Object>

Um objeto que contém arrays de sockets atualmente aguardando uso pelo agente quando keepAlive está habilitado. Não modifique.

Sockets na lista freeSockets serão automaticamente destruídos e removidos do array em 'timeout'.

agent.getName([options])

[Histórico]

Versão	Mudanças
v17.7.0, v16.15.0	O parâmetro options agora é opcional.
v0.11.4	Adicionado em: v0.11.4

• options <Object> Um conjunto de opções que fornecem informações para a geração de nomes

  • host <string> Um nome de domínio ou endereço IP do servidor para onde a solicitação será enviada
  • port <number> Porta do servidor remoto
  • localAddress <string> Interface local para vincular para conexões de rede ao emitir a solicitação
  • family <integer> Deve ser 4 ou 6 se não for igual a undefined.

• Retorna: <string>

Obtém um nome exclusivo para um conjunto de opções de solicitação, para determinar se uma conexão pode ser reutilizada. Para um agente HTTP, isso retorna host:port:localAddress ou host:port:localAddress:family. Para um agente HTTPS, o nome inclui o CA, cert, ciphers e outras opções específicas de HTTPS/TLS que determinam a reutilização de sockets.

agent.maxFreeSockets

Adicionado em: v0.11.7

• <number>

Por padrão, definido como 256. Para agentes com keepAlive habilitado, isso define o número máximo de sockets que serão deixados abertos no estado livre.

agent.maxSockets

Adicionado em: v0.3.6

• <number>

Por padrão, definido como Infinity. Determina quantos sockets simultâneos o agente pode ter abertos por origem. Origem é o valor retornado de agent.getName().

agent.maxTotalSockets

Adicionado em: v14.5.0, v12.19.0

• <number>

Por padrão, definido como Infinity. Determina quantos sockets simultâneos o agente pode ter abertos. Ao contrário de maxSockets, este parâmetro se aplica a todas as origens.

agent.requests

[Histórico]

Versão	Alterações
v16.0.0	A propriedade agora tem um protótipo null.
v0.5.9	Adicionado em: v0.5.9

• <Object>

Um objeto que contém filas de requisições que ainda não foram atribuídas a sockets. Não modifique.

agent.sockets

[Histórico]

Versão	Alterações
v16.0.0	A propriedade agora tem um protótipo null.
v0.3.6	Adicionado em: v0.3.6

• <Object>

Um objeto que contém arrays de sockets atualmente em uso pelo agente. Não modifique.

Classe: http.ClientRequest

Adicionado em: v0.1.17

• Estende: <http.OutgoingMessage>

Este objeto é criado internamente e retornado de http.request(). Ele representa uma requisição em andamento cujo cabeçalho já foi enfileirado. O cabeçalho ainda é mutável usando a API setHeader(name, value), getHeader(name), removeHeader(name). O cabeçalho real será enviado junto com o primeiro bloco de dados ou ao chamar request.end().

Para obter a resposta, adicione um listener para 'response' ao objeto de requisição. 'response' será emitido pelo objeto de requisição quando os cabeçalhos de resposta forem recebidos. O evento 'response' é executado com um argumento que é uma instância de http.IncomingMessage.

Durante o evento 'response', pode-se adicionar listeners ao objeto de resposta; particularmente para ouvir o evento 'data'.

Se nenhum manipulador 'response' for adicionado, a resposta será completamente descartada. No entanto, se um manipulador de evento 'response' for adicionado, os dados do objeto de resposta devem ser consumidos, seja chamando response.read() sempre que houver um evento 'readable', adicionando um manipulador 'data', ou chamando o método .resume(). Até que os dados sejam consumidos, o evento 'end' não será acionado. Além disso, até que os dados sejam lidos, eles consumirão memória que pode eventualmente levar a um erro de 'processo sem memória'.

Para compatibilidade com versões anteriores, res só emitirá 'error' se houver um listener 'error' registrado.

Defina o cabeçalho Content-Length para limitar o tamanho do corpo da resposta. Se response.strictContentLength for definido como true, a incompatibilidade com o valor do cabeçalho Content-Length resultará em um Error sendo lançado, identificado por code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

O valor de Content-Length deve estar em bytes, não em caracteres. Use Buffer.byteLength() para determinar o comprimento do corpo em bytes.

Evento: 'abort'

Adicionado em: v1.4.1

Obsoleto desde: v17.0.0, v16.12.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Ouça o evento 'close' em vez disso.

Emitido quando a solicitação foi abortada pelo cliente. Este evento é emitido apenas na primeira chamada a abort().

Evento: 'close'

Adicionado em: v0.5.4

Indica que a solicitação foi concluída ou que sua conexão subjacente foi encerrada prematuramente (antes da conclusão da resposta).

Evento: 'connect'

Adicionado em: v0.7.0

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

Emitido cada vez que um servidor responde a uma solicitação com um método CONNECT. Se este evento não estiver sendo ouvido, os clientes que receberem um método CONNECT terão suas conexões fechadas.

É garantido que este evento receberá uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket>.

Um par cliente e servidor demonstrando como ouvir o evento 'connect':

ESM

import { createServer, request } from 'node:http'
import { connect } from 'node:net'
import { URL } from 'node:url'

// Cria um proxy de túnel HTTP
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('ok')
})
proxy.on('connect', (req, clientSocket, head) => {
  // Conecta a um servidor de origem
  const { port, hostname } = new URL(`http://${req.url}`)
  const serverSocket = connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' + 'Proxy-agent: Node.js-Proxy\r\n' + '\r\n')
    serverSocket.write(head)
    serverSocket.pipe(clientSocket)
    clientSocket.pipe(serverSocket)
  })
})

// Agora que o proxy está em execução
proxy.listen(1337, '127.0.0.1', () => {
  // Faz uma solicitação para um proxy de túnel
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  }

  const req = request(options)
  req.end()

  req.on('connect', (res, socket, head) => {
    console.log('conectado!')

    // Faz uma solicitação por um túnel HTTP
    socket.write('GET / HTTP/1.1\r\n' + 'Host: www.google.com:80\r\n' + 'Connection: close\r\n' + '\r\n')
    socket.on('data', chunk => {
      console.log(chunk.toString())
    })
    socket.on('end', () => {
      proxy.close()
    })
  })
})

CJS

const http = require('node:http')
const net = require('node:net')
const { URL } = require('node:url')

// Cria um proxy de túnel HTTP
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('ok')
})
proxy.on('connect', (req, clientSocket, head) => {
  // Conecta a um servidor de origem
  const { port, hostname } = new URL(`http://${req.url}`)
  const serverSocket = net.connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' + 'Proxy-agent: Node.js-Proxy\r\n' + '\r\n')
    serverSocket.write(head)
    serverSocket.pipe(clientSocket)
    clientSocket.pipe(serverSocket)
  })
})

// Agora que o proxy está em execução
proxy.listen(1337, '127.0.0.1', () => {
  // Faz uma solicitação para um proxy de túnel
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  }

  const req = http.request(options)
  req.end()

  req.on('connect', (res, socket, head) => {
    console.log('conectado!')

    // Faz uma solicitação por um túnel HTTP
    socket.write('GET / HTTP/1.1\r\n' + 'Host: www.google.com:80\r\n' + 'Connection: close\r\n' + '\r\n')
    socket.on('data', chunk => {
      console.log(chunk.toString())
    })
    socket.on('end', () => {
      proxy.close()
    })
  })
})

Evento: 'continue'

Adicionado em: v0.3.2

Emitido quando o servidor envia uma resposta HTTP '100 Continue', geralmente porque a solicitação continha 'Expect: 100-continue'. Esta é uma instrução para que o cliente envie o corpo da solicitação.

Evento: 'finish'

Adicionado em: v0.3.6

Emitido quando a solicitação foi enviada. Mais especificamente, este evento é emitido quando o último segmento dos cabeçalhos e corpo da resposta foram entregues ao sistema operacional para transmissão pela rede. Isso não implica que o servidor já tenha recebido algo.

Evento: 'information'

Adicionado em: v10.0.0

• info <Object>
  • httpVersion <string>
  • httpVersionMajor <integer>
  • httpVersionMinor <integer>
  • statusCode <integer>
  • statusMessage <string>
  • headers <Object>
  • rawHeaders <string[]>

Emitido quando o servidor envia uma resposta intermediária 1xx (excluindo 101 Upgrade). Os listeners deste evento receberão um objeto contendo a versão HTTP, código de status, mensagem de status, objeto de cabeçalhos chave-valor e um array com os nomes de cabeçalho brutos seguidos por seus respectivos valores.

ESM

import { request } from 'node:http'

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
}

// Faz uma solicitação
const req = request(options)
req.end()

req.on('information', info => {
  console.log(`Obteve informações antes da resposta principal: ${info.statusCode}`)
})

CJS

const http = require('node:http')

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
}

// Faz uma solicitação
const req = http.request(options)
req.end()

req.on('information', info => {
  console.log(`Obteve informações antes da resposta principal: ${info.statusCode}`)
})

Os status 101 Upgrade não acionam este evento devido à sua quebra da cadeia tradicional de solicitação/resposta HTTP, como web sockets, upgrades TLS in-place ou HTTP 2.0. Para ser notificado sobre avisos de 101 Upgrade, escute o evento 'upgrade' em vez disso.

Evento: 'response'

Adicionado em: v0.1.0

• response <http.IncomingMessage>

Emitido quando uma resposta é recebida para esta solicitação. Este evento é emitido apenas uma vez.

Evento: 'socket'

Adicionado em: v0.5.3

• socket <stream.Duplex>

Este evento tem garantia de receber uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket>.

Evento: 'timeout'

Adicionado em: v0.7.8

Emitido quando o socket subjacente atinge o tempo limite por inatividade. Isso apenas notifica que o socket está ocioso. A solicitação deve ser destruída manualmente.

Veja também: request.setTimeout().

Evento: 'upgrade'

Adicionado em: v0.1.94

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

Emitido cada vez que um servidor responde a uma solicitação com um upgrade. Se este evento não estiver sendo monitorado e o código de status da resposta for 101 Switching Protocols, os clientes que receberem um cabeçalho de upgrade terão suas conexões fechadas.

Este evento tem garantia de receber uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket>.

Um par cliente-servidor demonstrando como monitorar o evento 'upgrade'.

ESM

import http from 'node:http'
import process from 'node:process'

// Cria um servidor HTTP
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('okay')
})
server.on('upgrade', (req, socket, head) => {
  socket.write(
    'HTTP/1.1 101 Web Socket Protocol Handshake\r\n' + 'Upgrade: WebSocket\r\n' + 'Connection: Upgrade\r\n' + '\r\n'
  )

  socket.pipe(socket) // ecoar de volta
})

// Agora que o servidor está em execução
server.listen(1337, '127.0.0.1', () => {
  // faz uma solicitação
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      Connection: 'Upgrade',
      Upgrade: 'websocket',
    },
  }

  const req = http.request(options)
  req.end()

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('got upgraded!')
    socket.end()
    process.exit(0)
  })
})

CJS

const http = require('node:http')

// Cria um servidor HTTP
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('okay')
})
server.on('upgrade', (req, socket, head) => {
  socket.write(
    'HTTP/1.1 101 Web Socket Protocol Handshake\r\n' + 'Upgrade: WebSocket\r\n' + 'Connection: Upgrade\r\n' + '\r\n'
  )

  socket.pipe(socket) // ecoar de volta
})

// Agora que o servidor está em execução
server.listen(1337, '127.0.0.1', () => {
  // faz uma solicitação
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      Connection: 'Upgrade',
      Upgrade: 'websocket',
    },
  }

  const req = http.request(options)
  req.end()

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('got upgraded!')
    socket.end()
    process.exit(0)
  })
})

request.abort()

Adicionado em: v0.3.8

Obsoleto desde: v14.1.0, v13.14.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use request.destroy() em vez disso.

Marca a requisição como sendo abortada. Chamar isso fará com que os dados restantes na resposta sejam descartados e o socket seja destruído.

request.aborted

[Histórico]

Versão	Mudanças
v17.0.0, v16.12.0	Obsoleto desde: v17.0.0, v16.12.0
v11.0.0	A propriedade aborted não é mais um número timestamp.
v0.11.14	Adicionado em: v0.11.14

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Verifique request.destroyed em vez disso.

• <boolean>

A propriedade request.aborted será true se a requisição tiver sido abortada.

request.connection

Adicionado em: v0.3.0

Obsoleto desde: v13.0.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Use request.socket.

• <stream.Duplex>

Veja request.socket.

request.cork()

Adicionado em: v13.2.0, v12.16.0

Veja writable.cork().

request.end([data[, encoding]][, callback])

[Histórico]

Versão	Mudanças
v15.0.0	O parâmetro data agora pode ser um Uint8Array.
v10.0.0	Este método agora retorna uma referência para ClientRequest.
v0.1.90	Adicionado em: v0.1.90

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Retorna: <this>

Finaliza o envio da requisição. Se alguma parte do corpo não tiver sido enviada, ela será enviada para o fluxo. Se a requisição for em chunks, isso enviará o terminador '0\r\n\r\n'.

Se data for especificado, é equivalente a chamar request.write(data, encoding) seguido por request.end(callback).

Se callback for especificado, ele será chamado quando o fluxo de requisição for finalizado.

request.destroy([error])

[Histórico]

Versão	Mudanças
v14.5.0	A função retorna this para consistência com outros streams Readable.
v0.3.0	Adicionado em: v0.3.0

• error <Error> Opcional, um erro a ser emitido com o evento 'error'.
• Retorna: <this>

Destrói a requisição. Opcionalmente, emite um evento 'error' e um evento 'close'. Chamar isso fará com que os dados restantes na resposta sejam descartados e o socket seja destruído.

Consulte writable.destroy() para mais detalhes.

request.destroyed

Adicionado em: v14.1.0, v13.14.0

• <boolean>

É true depois que request.destroy() foi chamado.

Consulte writable.destroyed para mais detalhes.

request.finished

Adicionado em: v0.0.1

Obsoleto desde: v13.4.0, v12.16.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Use request.writableEnded.

• <boolean>

A propriedade request.finished será true se request.end() tiver sido chamado. request.end() será chamado automaticamente se a requisição foi iniciada via http.get().

request.flushHeaders()

Adicionado em: v1.6.0

Descarrega os cabeçalhos da requisição.

Por motivos de eficiência, o Node.js normalmente armazena em buffer os cabeçalhos da requisição até que request.end() seja chamado ou o primeiro trecho de dados da requisição seja escrito. Em seguida, ele tenta compactar os cabeçalhos da requisição e os dados em um único pacote TCP.

Isso geralmente é desejado (economiza uma viagem de ida e volta TCP), mas não quando os primeiros dados não são enviados até possivelmente muito mais tarde. request.flushHeaders() ignora a otimização e inicia a requisição.

request.getHeader(name)

Adicionado em: v1.6.0

• name <string>
• Retorna: <any>

Lê um cabeçalho na requisição. O nome não diferencia maiúsculas de minúsculas. O tipo do valor de retorno depende dos argumentos fornecidos para request.setHeader().

request.setHeader('content-type', 'text/html')
request.setHeader('Content-Length', Buffer.byteLength(body))
request.setHeader('Cookie', ['type=ninja', 'language=javascript'])
const contentType = request.getHeader('Content-Type')
// 'contentType' é 'text/html'
const contentLength = request.getHeader('Content-Length')
// 'contentLength' é do tipo number
const cookie = request.getHeader('Cookie')
// 'cookie' é do tipo string[]

request.getHeaderNames()

Adicionado em: v7.7.0

• Retorna: <string[]>

Retorna um array contendo os nomes únicos dos cabeçalhos de saída atuais. Todos os nomes de cabeçalho são em minúsculas.

request.setHeader('Foo', 'bar')
request.setHeader('Cookie', ['foo=bar', 'bar=baz'])

const headerNames = request.getHeaderNames()
// headerNames === ['foo', 'cookie']

request.getHeaders()

Adicionado em: v7.7.0

• Retorna: <Object>

Retorna uma cópia superficial dos cabeçalhos de saída atuais. Como uma cópia superficial é usada, os valores do array podem ser mutados sem chamadas adicionais para vários métodos do módulo http relacionados a cabeçalhos. As chaves do objeto retornado são os nomes dos cabeçalhos e os valores são os respectivos valores dos cabeçalhos. Todos os nomes de cabeçalho são em minúsculas.

O objeto retornado pelo método request.getHeaders() não herda prototipicamente do Object JavaScript. Isso significa que métodos típicos de Object como obj.toString(), obj.hasOwnProperty() e outros não são definidos e não funcionarão.

request.setHeader('Foo', 'bar')
request.setHeader('Cookie', ['foo=bar', 'bar=baz'])

const headers = request.getHeaders()
// headers === { foo: 'bar', 'cookie': ['foo=bar', 'bar=baz'] }

request.getRawHeaderNames()

Adicionado em: v15.13.0, v14.17.0

• Retorna: <string[]>

Retorna um array contendo os nomes únicos dos cabeçalhos brutos de saída atuais. Os nomes dos cabeçalhos são retornados com a capitalização exata definida.

request.setHeader('Foo', 'bar')
request.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headerNames = request.getRawHeaderNames()
// headerNames === ['Foo', 'Set-Cookie']

request.hasHeader(name)

Adicionado em: v7.7.0

• name <string>
• Retorna: <boolean>

Retorna true se o cabeçalho identificado por name estiver atualmente definido nos cabeçalhos de saída. A correspondência do nome do cabeçalho não diferencia maiúsculas de minúsculas.

const hasContentType = request.hasHeader('content-type')

request.maxHeadersCount

• <number> Padrão: 2000

Limita o número máximo de cabeçalhos de resposta. Se definido como 0, nenhum limite será aplicado.

request.path

Adicionado em: v0.4.0

• <string> O caminho da requisição.

request.method

Adicionado em: v0.1.97

• <string> O método da requisição.

request.host

Adicionado em: v14.5.0, v12.19.0

• <string> O host da requisição.

request.protocol

Adicionado em: v14.5.0, v12.19.0

• <string> O protocolo da requisição.

request.removeHeader(name)

Adicionado em: v1.6.0

• name <string>

Remove um cabeçalho que já está definido no objeto de cabeçalhos.

request.removeHeader('Content-Type')

request.reusedSocket

Adicionado em: v13.0.0, v12.16.0

• <boolean> Indica se a solicitação foi enviada através de um socket reutilizado.

Ao enviar uma solicitação através de um agente com keep-alive habilitado, o socket subjacente pode ser reutilizado. Mas se o servidor fechar a conexão em um momento inoportuno, o cliente pode encontrar um erro 'ECONNRESET'.

ESM

import http from 'node:http'

// O servidor tem um tempo limite de keep-alive de 5 segundos por padrão
http
  .createServer((req, res) => {
    res.write('hello\n')
    res.end()
  })
  .listen(3000)

setInterval(() => {
  // Adaptando um agente keep-alive
  http.get('http://localhost:3000', { agent }, res => {
    res.on('data', data => {
      // Não fazer nada
    })
  })
}, 5000) // Enviar solicitação em intervalo de 5s para facilitar o acerto do tempo limite ocioso

CJS

const http = require('node:http')

// O servidor tem um tempo limite de keep-alive de 5 segundos por padrão
http
  .createServer((req, res) => {
    res.write('hello\n')
    res.end()
  })
  .listen(3000)

setInterval(() => {
  // Adaptando um agente keep-alive
  http.get('http://localhost:3000', { agent }, res => {
    res.on('data', data => {
      // Não fazer nada
    })
  })
}, 5000) // Enviar solicitação em intervalo de 5s para facilitar o acerto do tempo limite ocioso

Ao marcar uma solicitação se ela reutilizou o socket ou não, podemos fazer a nova tentativa automática de erro com base nisso.

ESM

import http from 'node:http'
const agent = new http.Agent({ keepAlive: true })

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, res => {
      // ...
    })
    .on('error', err => {
      // Verificar se a nova tentativa é necessária
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest()
      }
    })
}

retriableRequest()

CJS

const http = require('node:http')
const agent = new http.Agent({ keepAlive: true })

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, res => {
      // ...
    })
    .on('error', err => {
      // Verificar se a nova tentativa é necessária
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest()
      }
    })
}

retriableRequest()

request.setHeader(name, value)

Adicionado em: v1.6.0

• name <string>
• value <any>

Define um único valor de cabeçalho para o objeto de cabeçalhos. Se este cabeçalho já existir nos cabeçalhos a serem enviados, seu valor será substituído. Use um array de strings aqui para enviar vários cabeçalhos com o mesmo nome. Valores não string serão armazenados sem modificação. Portanto, request.getHeader() pode retornar valores não string. No entanto, os valores não string serão convertidos em strings para transmissão em rede.

request.setHeader('Content-Type', 'application/json')

ou

request.setHeader('Cookie', ['type=ninja', 'language=javascript'])

Quando o valor é uma string, uma exceção será lançada se contiver caracteres fora da codificação latin1.

Se você precisar passar caracteres UTF-8 no valor, codifique o valor usando o padrão RFC 8187.

const filename = 'Rock 🎵.txt'
request.setHeader('Content-Disposition', `attachment; filename*=utf-8''${encodeURIComponent(filename)}`)

request.setNoDelay([noDelay])

Adicionado em: v0.5.9

• noDelay <boolean>

Assim que um socket é atribuído a esta requisição e está conectado, socket.setNoDelay() será chamado.

request.setSocketKeepAlive([enable][, initialDelay])

Adicionado em: v0.5.9

• enable <boolean>
• initialDelay <number>

Assim que um socket é atribuído a esta requisição e está conectado, socket.setKeepAlive() será chamado.

request.setTimeout(timeout[, callback])

[Histórico]

Versão	Mudanças
v9.0.0	Defina consistentemente o tempo limite do socket somente quando o socket se conectar.
v0.5.9	Adicionado em: v0.5.9

• timeout <number> Milissegundos antes que uma solicitação expire.
• callback <Function> Função opcional a ser chamada quando ocorre um tempo limite. O mesmo que vincular ao evento 'timeout'.
• Retorna: <http.ClientRequest>

Assim que um socket é atribuído a esta solicitação e está conectado, socket.setTimeout() será chamado.

request.socket

Adicionado em: v0.3.0

• <stream.Duplex>

Referência ao socket subjacente. Normalmente, os usuários não desejam acessar esta propriedade. Em particular, o socket não emitirá eventos 'readable' devido à forma como o analisador de protocolo se conecta ao socket.

ESM

import http from 'node:http'
const options = {
  host: 'www.google.com',
}
const req = http.get(options)
req.end()
req.once('response', res => {
  const ip = req.socket.localAddress
  const port = req.socket.localPort
  console.log(`Seu endereço IP é ${ip} e sua porta de origem é ${port}.`)
  // Consumir objeto de resposta
})

CJS

const http = require('node:http')
const options = {
  host: 'www.google.com',
}
const req = http.get(options)
req.end()
req.once('response', res => {
  const ip = req.socket.localAddress
  const port = req.socket.localPort
  console.log(`Seu endereço IP é ${ip} e sua porta de origem é ${port}.`)
  // Consumir objeto de resposta
})

Esta propriedade tem a garantia de ser uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário tenha especificado um tipo de socket diferente de <net.Socket>.

request.uncork()

Adicionado em: v13.2.0, v12.16.0

Veja writable.uncork().

request.writableEnded

Adicionado em: v12.9.0

• <boolean>

É true depois que request.end() foi chamado. Esta propriedade não indica se os dados foram descarregados, para isso use request.writableFinished em vez disso.

request.writableFinished

Adicionado em: v12.7.0

• <boolean>

É true se todos os dados foram descarregados para o sistema subjacente, imediatamente antes do evento 'finish' ser emitido.

request.write(chunk[, encoding][, callback])

[Histórico]

Versão	Alterações
v15.0.0	O parâmetro chunk agora pode ser um Uint8Array.
v0.1.29	Adicionado em: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Retorna: <boolean>

Envia um pedaço do corpo. Este método pode ser chamado várias vezes. Se nenhum Content-Length for definido, os dados serão automaticamente codificados em codificação de transferência HTTP Chunked, para que o servidor saiba quando os dados terminam. O cabeçalho Transfer-Encoding: chunked é adicionado. Chamar request.end() é necessário para terminar de enviar a requisição.

O argumento encoding é opcional e só se aplica quando chunk é uma string. O padrão é 'utf8'.

O argumento callback é opcional e será chamado quando este pedaço de dados for descarregado, mas apenas se o pedaço não estiver vazio.

Retorna true se todos os dados foram descarregados com sucesso para o buffer do kernel. Retorna false se todos ou parte dos dados foram enfileirados na memória do usuário. 'drain' será emitido quando o buffer estiver livre novamente.

Quando a função write é chamada com uma string ou buffer vazio, ela não faz nada e espera por mais entrada.

Classe: http.Server

Adicionado em: v0.1.17

• Estende: <net.Server>

Evento: 'checkContinue'

Adicionado em: v0.3.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Emitido cada vez que uma requisição com um Expect: 100-continue HTTP é recebida. Se este evento não for ouvido, o servidor responderá automaticamente com um 100 Continue conforme apropriado.

Lidar com este evento envolve chamar response.writeContinue() se o cliente deve continuar a enviar o corpo da requisição, ou gerar uma resposta HTTP apropriada (por exemplo, 400 Bad Request) se o cliente não deve continuar a enviar o corpo da requisição.

Quando este evento é emitido e tratado, o evento 'request' não será emitido.

Evento: 'checkExpectation'

Adicionado em: v5.5.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Emitido cada vez que uma requisição com um cabeçalho HTTP Expect é recebida, onde o valor não é 100-continue. Se este evento não for ouvido, o servidor responderá automaticamente com um 417 Expectation Failed conforme apropriado.

Quando este evento é emitido e tratado, o evento 'request' não será emitido.

Evento: 'clientError'

[Histórico]

Versão	Mudanças
v12.0.0	O comportamento padrão retornará um 431 Request Header Fields Too Large se ocorrer um erro HPE_HEADER_OVERFLOW.
v9.4.0	O rawPacket é o buffer atual que acabou de ser analisado. Adicionar este buffer ao objeto de erro do evento 'clientError' é para tornar possível que os desenvolvedores possam registrar o pacote corrompido.
v6.0.0	A ação padrão de chamar .destroy() no socket não ocorrerá mais se houver listeners anexados para 'clientError'.
v0.1.94	Adicionado em: v0.1.94

• exception <Error>
• socket <stream.Duplex>

Se uma conexão de cliente emitir um evento 'error', ele será encaminhado para cá. O listener deste evento é responsável por fechar/destruir o socket subjacente. Por exemplo, pode-se desejar fechar o socket de forma mais elegante com uma resposta HTTP personalizada em vez de interromper abruptamente a conexão. O socket deve ser fechado ou destruído antes que o listener termine.

É garantido que este evento receba uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket>.

O comportamento padrão é tentar fechar o socket com um HTTP '400 Bad Request', ou um HTTP '431 Request Header Fields Too Large' no caso de um erro HPE_HEADER_OVERFLOW. Se o socket não for gravável ou os cabeçalhos do http.ServerResponse anexado atual tiverem sido enviados, ele é destruído imediatamente.

socket é o objeto net.Socket de onde o erro se originou.

ESM

import http from 'node:http'

const server = http.createServer((req, res) => {
  res.end()
})
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
})
server.listen(8000)

CJS

const http = require('node:http')

const server = http.createServer((req, res) => {
  res.end()
})
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
})
server.listen(8000)

Quando o evento 'clientError' ocorre, não há objeto request ou response, portanto, qualquer resposta HTTP enviada, incluindo cabeçalhos de resposta e payload, deve ser escrita diretamente no objeto socket. Deve-se ter cuidado para garantir que a resposta seja uma mensagem de resposta HTTP formatada corretamente.

err é uma instância de Error com duas colunas extras:

• bytesParsed: a contagem de bytes do pacote de requisição que o Node.js pode ter analisado corretamente;
• rawPacket: o pacote bruto da requisição atual.

Em alguns casos, o cliente já recebeu a resposta e/ou o socket já foi destruído, como no caso de erros ECONNRESET. Antes de tentar enviar dados para o socket, é melhor verificar se ele ainda é gravável.

server.on('clientError', (err, socket) => {
  if (err.code === 'ECONNRESET' || !socket.writable) {
    return
  }

  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
})

Evento: 'close'

Adicionado em: v0.1.4

Emitido quando o servidor fecha.

Evento: 'connect'

Adicionado em: v0.7.0

• request <http.IncomingMessage> Argumentos para a requisição HTTP, como no evento 'request'
• socket <stream.Duplex> Socket de rede entre o servidor e o cliente
• head <Buffer> O primeiro pacote do fluxo de túnel (pode estar vazio)

Emitido cada vez que um cliente solicita um método HTTP CONNECT. Se este evento não for ouvido, os clientes que solicitarem um método CONNECT terão suas conexões fechadas.

É garantido que este evento receberá uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket>.

Depois que este evento é emitido, o socket da requisição não terá um ouvinte de evento 'data', o que significa que ele precisará ser vinculado para lidar com os dados enviados para o servidor nesse socket.

Evento: 'connection'

Adicionado em: v0.1.0

• socket <stream.Duplex>

Este evento é emitido quando um novo fluxo TCP é estabelecido. socket é normalmente um objeto do tipo net.Socket. Geralmente, os usuários não desejarão acessar este evento. Em particular, o socket não emitirá eventos 'readable' devido à forma como o analisador de protocolo se conecta ao socket. O socket também pode ser acessado em request.socket.

Este evento também pode ser explicitamente emitido pelos usuários para injetar conexões no servidor HTTP. Nesse caso, qualquer fluxo Duplex pode ser passado.

Se socket.setTimeout() for chamado aqui, o tempo limite será substituído por server.keepAliveTimeout quando o socket tiver servido uma requisição (se server.keepAliveTimeout for diferente de zero).

É garantido que este evento receberá uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket>.

Event: 'dropRequest'

Adicionado em: v18.7.0, v16.17.0

• request <http.IncomingMessage> Argumentos para a requisição HTTP, como está no evento 'request'
• socket <stream.Duplex> Socket de rede entre o servidor e o cliente

Quando o número de requisições em um socket atinge o limite de server.maxRequestsPerSocket, o servidor irá descartar novas requisições e emitir o evento 'dropRequest' em vez disso, e então enviar 503 para o cliente.

Event: 'request'

Adicionado em: v0.1.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Emitido cada vez que há uma requisição. Pode haver múltiplas requisições por conexão (no caso de conexões HTTP Keep-Alive).

Event: 'upgrade'

[Histórico]

Versão	Mudanças
v10.0.0	Não escutar este evento não causa mais a destruição do socket se um cliente enviar um cabeçalho Upgrade.
v0.1.94	Adicionado em: v0.1.94

• request <http.IncomingMessage> Argumentos para a requisição HTTP, como está no evento 'request'
• socket <stream.Duplex> Socket de rede entre o servidor e o cliente
• head <Buffer> O primeiro pacote do stream atualizado (pode estar vazio)

Emitido cada vez que um cliente solicita um upgrade HTTP. Escutar este evento é opcional e os clientes não podem insistir em uma mudança de protocolo.

Depois que este evento é emitido, o socket da requisição não terá um listener de evento 'data', o que significa que ele precisará ser vinculado para lidar com os dados enviados para o servidor naquele socket.

É garantido que este evento receberá uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket>.

server.close([callback])

[Histórico]

Versão	Mudanças
v19.0.0	O método fecha conexões ociosas antes de retornar.
v0.1.90	Adicionado em: v0.1.90

• callback <Function>

Impede que o servidor aceite novas conexões e fecha todas as conexões conectadas a este servidor que não estão enviando uma solicitação ou esperando uma resposta. Consulte net.Server.close().

const http = require('node:http')

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Olá Mundo!',
    })
  )
})

server.listen(8000)
// Fecha o servidor após 10 segundos
setTimeout(() => {
  server.close(() => {
    console.log('servidor na porta 8000 fechado com sucesso')
  })
}, 10000)

server.closeAllConnections()

Adicionado em: v18.2.0

Fecha todas as conexões HTTP(S) estabelecidas conectadas a este servidor, incluindo conexões ativas conectadas a este servidor que estão enviando uma solicitação ou esperando uma resposta. Isso não destrói sockets atualizados para um protocolo diferente, como WebSocket ou HTTP/2.

const http = require('node:http')

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Olá Mundo!',
    })
  )
})

server.listen(8000)
// Fecha o servidor após 10 segundos
setTimeout(() => {
  server.close(() => {
    console.log('servidor na porta 8000 fechado com sucesso')
  })
  // Fecha todas as conexões, garantindo que o servidor feche com sucesso
  server.closeAllConnections()
}, 10000)

server.closeIdleConnections()

Adicionado em: v18.2.0

Fecha todas as conexões conectadas a este servidor que não estão enviando uma solicitação ou esperando uma resposta.

const http = require('node:http')

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Olá Mundo!',
    })
  )
})

server.listen(8000)
// Fecha o servidor após 10 segundos
setTimeout(() => {
  server.close(() => {
    console.log('servidor na porta 8000 fechado com sucesso')
  })
  // Fecha conexões ociosas, como conexões keep-alive. O servidor será fechado
  // assim que as conexões ativas restantes forem terminadas
  server.closeIdleConnections()
}, 10000)

server.headersTimeout

[Histórico]

Versão	Mudanças
v19.4.0, v18.14.0	O padrão agora é definido como o mínimo entre 60000 (60 segundos) ou requestTimeout.
v11.3.0, v10.14.0	Adicionado em: v11.3.0, v10.14.0

• <number> Padrão: O mínimo entre server.requestTimeout ou 60000.

Limita a quantidade de tempo que o analisador aguardará para receber os cabeçalhos HTTP completos.

Se o tempo limite expirar, o servidor responde com o status 408 sem encaminhar a solicitação para o ouvinte de solicitação e, em seguida, fecha a conexão.

Ele deve ser definido como um valor diferente de zero (por exemplo, 120 segundos) para proteger contra possíveis ataques de negação de serviço caso o servidor seja implantado sem um proxy reverso na frente.

server.listen()

Inicia o servidor HTTP ouvindo conexões. Este método é idêntico a server.listen() de net.Server.

server.listening

Adicionado em: v5.7.0

• <boolean> Indica se o servidor está ou não ouvindo conexões.

server.maxHeadersCount

Adicionado em: v0.7.0

• <number> Padrão: 2000

Limita a contagem máxima de cabeçalhos de entrada. Se definido como 0, nenhum limite será aplicado.

server.requestTimeout

[Histórico]

Versão	Mudanças
v18.0.0	O tempo limite de solicitação padrão mudou de nenhum tempo limite para 300s (5 minutos).
v14.11.0	Adicionado em: v14.11.0

• <number> Padrão: 300000

Define o valor de tempo limite em milissegundos para receber toda a solicitação do cliente.

Se o tempo limite expirar, o servidor responde com o status 408 sem encaminhar a solicitação para o ouvinte de solicitação e, em seguida, fecha a conexão.

Ele deve ser definido como um valor diferente de zero (por exemplo, 120 segundos) para proteger contra possíveis ataques de negação de serviço caso o servidor seja implantado sem um proxy reverso na frente.

server.setTimeout([msecs][, callback])

[Histórico]

Versão	Mudanças
v13.0.0	O tempo limite padrão mudou de 120s para 0 (sem tempo limite).
v0.9.12	Adicionado em: v0.9.12

• msecs <number> Padrão: 0 (sem tempo limite)
• callback <Function>
• Retorna: <http.Server>

Define o valor do tempo limite para os sockets e emite um evento 'timeout' no objeto Server, passando o socket como argumento, se ocorrer um tempo limite.

Se houver um listener de evento 'timeout' no objeto Server, ele será chamado com o socket com tempo limite como argumento.

Por padrão, o Server não define tempo limite para sockets. No entanto, se um callback for atribuído ao evento 'timeout' do Server, os tempos limites deverão ser tratados explicitamente.

server.maxRequestsPerSocket

Adicionado em: v16.10.0

• <number> Requisições por socket. Padrão: 0 (sem limite)

O número máximo de requisições que um socket pode lidar antes de fechar a conexão keep-alive.

Um valor de 0 desabilitará o limite.

Quando o limite é atingido, ele definirá o valor do cabeçalho Connection para close, mas não fechará a conexão de fato, requisições subsequentes enviadas após o limite ser atingido receberão 503 Service Unavailable como resposta.

server.timeout

[Histórico]

Versão	Mudanças
v13.0.0	O tempo limite padrão mudou de 120s para 0 (sem tempo limite).
v0.9.12	Adicionado em: v0.9.12

• <number> Tempo limite em milissegundos. Padrão: 0 (sem tempo limite)

O número de milissegundos de inatividade antes que um socket seja considerado como tendo expirado.

Um valor de 0 desabilitará o comportamento de tempo limite em conexões de entrada.

A lógica de tempo limite do socket é configurada na conexão, portanto, alterar esse valor afeta apenas novas conexões com o servidor, não quaisquer conexões existentes.

server.keepAliveTimeout

Adicionado em: v8.0.0

• <number> Tempo limite em milissegundos. Padrão: 5000 (5 segundos).

O número de milissegundos de inatividade que um servidor precisa esperar por dados de entrada adicionais, depois de terminar de escrever a última resposta, antes que um socket seja destruído. Se o servidor receber novos dados antes que o tempo limite de keep-alive seja atingido, ele redefinirá o tempo limite de inatividade regular, ou seja, server.timeout.

Um valor de 0 desabilitará o comportamento de tempo limite de keep-alive em conexões de entrada. Um valor de 0 faz com que o servidor http se comporte de forma semelhante às versões do Node.js anteriores à 8.0.0, que não tinham um tempo limite de keep-alive.

A lógica de tempo limite do socket é configurada na conexão, portanto, alterar esse valor afeta apenas novas conexões com o servidor, e não quaisquer conexões existentes.

server[Symbol.asyncDispose]()

Adicionado em: v20.4.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Chama server.close() e retorna uma promise que é cumprida quando o servidor é fechado.

Classe: http.ServerResponse

Adicionado em: v0.1.17

• Estende: <http.OutgoingMessage>

Este objeto é criado internamente por um servidor HTTP, não pelo usuário. Ele é passado como o segundo parâmetro para o evento 'request'.

Evento: 'close'

Adicionado em: v0.6.7

Indica que a resposta foi concluída ou que sua conexão subjacente foi encerrada prematuramente (antes da conclusão da resposta).

Evento: 'finish'

Adicionado em: v0.3.6

Emitido quando a resposta foi enviada. Mais especificamente, este evento é emitido quando o último segmento dos cabeçalhos e corpo da resposta foi entregue ao sistema operacional para transmissão pela rede. Isso não implica que o cliente tenha recebido algo ainda.

response.addTrailers(headers)

Adicionado em: v0.3.0

• headers <Objeto>

Este método adiciona cabeçalhos de rodapé HTTP (um cabeçalho, mas no final da mensagem) à resposta.

Os rodapés só serão emitidos se a codificação de fragmentos for usada para a resposta; se não for (por exemplo, se a requisição fosse HTTP/1.0), eles serão descartados silenciosamente.

O HTTP requer que o cabeçalho Trailer seja enviado para emitir rodapés, com uma lista dos campos de cabeçalho em seu valor. Por exemplo:

response.writeHead(200, { 'Content-Type': 'text/plain', Trailer: 'Content-MD5' })
response.write(fileData)
response.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' })
response.end()

Tentar definir um nome ou valor de campo de cabeçalho que contenha caracteres inválidos resultará no lançamento de um TypeError.

response.connection

Adicionado em: v0.3.0

Obsoleto desde: v13.0.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Use response.socket.

• <stream.Duplex>

Veja response.socket.

response.cork()

Adicionado em: v13.2.0, v12.16.0

Veja writable.cork().

response.end([data[, encoding]][, callback])

[Histórico]

Versão	Mudanças
v15.0.0	O parâmetro data agora pode ser um Uint8Array.
v10.0.0	Este método agora retorna uma referência a ServerResponse.
v0.1.90	Adicionado em: v0.1.90

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Função>
• Retorna: <this>

Este método sinaliza para o servidor que todos os cabeçalhos e o corpo da resposta foram enviados; esse servidor deve considerar esta mensagem completa. O método, response.end(), DEVE ser chamado em cada resposta.

Se data for especificado, tem um efeito semelhante a chamar response.write(data, encoding) seguido por response.end(callback).

Se callback for especificado, será chamado quando o fluxo de resposta terminar.

response.finished

Adicionado em: v0.0.2

Obsoleto desde: v13.4.0, v12.16.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Use response.writableEnded.

• <boolean>

A propriedade response.finished será true se response.end() tiver sido chamado.

response.flushHeaders()

Adicionado em: v1.6.0

Envia os cabeçalhos de resposta. Consulte também: request.flushHeaders().

response.getHeader(name)

Adicionado em: v0.4.0

• name <string>
• Retorna: <any>

Lê um cabeçalho que já foi enfileirado, mas não enviado para o cliente. O nome não diferencia maiúsculas de minúsculas. O tipo do valor de retorno depende dos argumentos fornecidos para response.setHeader().

response.setHeader('Content-Type', 'text/html')
response.setHeader('Content-Length', Buffer.byteLength(body))
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript'])
const contentType = response.getHeader('content-type')
// contentType é 'text/html'
const contentLength = response.getHeader('Content-Length')
// contentLength é do tipo number
const setCookie = response.getHeader('set-cookie')
// setCookie é do tipo string[]

response.getHeaderNames()

Adicionado em: v7.7.0

• Retorna: <string[]>

Retorna um array contendo os nomes únicos dos cabeçalhos de saída atuais. Todos os nomes de cabeçalho são em minúsculas.

response.setHeader('Foo', 'bar')
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headerNames = response.getHeaderNames()
// headerNames === ['foo', 'set-cookie']

response.getHeaders()

Adicionado em: v7.7.0

• Retorna: <Object>

Retorna uma cópia superficial dos cabeçalhos de saída atuais. Como uma cópia superficial é usada, os valores de array podem ser mutados sem chamadas adicionais para vários métodos do módulo http relacionados a cabeçalhos. As chaves do objeto retornado são os nomes dos cabeçalhos e os valores são os respectivos valores dos cabeçalhos. Todos os nomes de cabeçalhos estão em letras minúsculas.

O objeto retornado pelo método response.getHeaders() não herda prototipicamente do Object JavaScript. Isso significa que métodos Object típicos como obj.toString(), obj.hasOwnProperty() e outros não são definidos e não funcionarão.

response.setHeader('Foo', 'bar')
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headers = response.getHeaders()
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }

response.hasHeader(name)

Adicionado em: v7.7.0

• name <string>
• Retorna: <boolean>

Retorna true se o cabeçalho identificado por name estiver definido atualmente nos cabeçalhos de saída. A correspondência do nome do cabeçalho não diferencia maiúsculas de minúsculas.

const hasContentType = response.hasHeader('content-type')

response.headersSent

Adicionado em: v0.9.3

• <boolean>

Booleano (somente leitura). Verdadeiro se os cabeçalhos foram enviados, falso caso contrário.

response.removeHeader(name)

Adicionado em: v0.4.0

• name <string>

Remove um cabeçalho que está na fila para envio implícito.

response.removeHeader('Content-Encoding')

response.req

Adicionado em: v15.7.0

• <http.IncomingMessage>

Uma referência ao objeto request HTTP original.

response.sendDate

Adicionado em: v0.7.5

• <boolean>

Quando verdadeiro, o cabeçalho Date será gerado automaticamente e enviado na resposta se já não estiver presente nos cabeçalhos. O padrão é verdadeiro.

Isto só deve ser desativado para testes; HTTP requer o cabeçalho Date nas respostas.

response.setHeader(name, value)

Adicionado em: v0.4.0

• name <string>
• value <any>
• Retorna: <http.ServerResponse>

Retorna o objeto de resposta.

Define um único valor de cabeçalho para cabeçalhos implícitos. Se este cabeçalho já existir nos cabeçalhos a serem enviados, o seu valor será substituído. Use um array de strings aqui para enviar vários cabeçalhos com o mesmo nome. Valores não string serão armazenados sem modificação. Portanto, response.getHeader() pode retornar valores não string. No entanto, os valores não string serão convertidos para strings para transmissão na rede. O mesmo objeto de resposta é retornado ao chamador, para permitir o encadeamento de chamadas.

response.setHeader('Content-Type', 'text/html')

ou

response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript'])

A tentativa de definir um nome ou valor de campo de cabeçalho que contenha caracteres inválidos resultará no lançamento de um TypeError.

Quando os cabeçalhos tiverem sido definidos com response.setHeader(), eles serão mesclados com quaisquer cabeçalhos passados para response.writeHead(), com os cabeçalhos passados para response.writeHead() recebendo precedência.

// Retorna content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('ok')
})

Se o método response.writeHead() for chamado e este método não tiver sido chamado, ele gravará diretamente os valores de cabeçalho fornecidos no canal de rede sem armazenar em cache internamente, e o response.getHeader() no cabeçalho não produzirá o resultado esperado. Se a população progressiva de cabeçalhos for desejada com possível recuperação e modificação futuras, use response.setHeader() em vez de response.writeHead().

response.setTimeout(msecs[, callback])

Adicionado em: v0.9.12

• msecs <number>
• callback <Function>
• Retorna: <http.ServerResponse>

Define o valor de tempo limite do Socket para msecs. Se um retorno de chamada for fornecido, ele será adicionado como um ouvinte no evento 'timeout' no objeto de resposta.

Se nenhum ouvinte 'timeout' for adicionado à requisição, à resposta ou ao servidor, os sockets serão destruídos quando expirarem. Se um manipulador for atribuído aos eventos 'timeout' da requisição, da resposta ou do servidor, os sockets com tempo limite devem ser tratados explicitamente.

response.socket

Adicionado em: v0.3.0

• <stream.Duplex>

Referência ao socket subjacente. Normalmente, os usuários não desejarão acessar esta propriedade. Em particular, o socket não emitirá eventos 'readable' devido à forma como o analisador de protocolo se conecta ao socket. Após response.end(), a propriedade é anulada.

ESM

import http from 'node:http'
const server = http
  .createServer((req, res) => {
    const ip = res.socket.remoteAddress
    const port = res.socket.remotePort
    res.end(`Your IP address is ${ip} and your source port is ${port}.`)
  })
  .listen(3000)

CJS

const http = require('node:http')
const server = http
  .createServer((req, res) => {
    const ip = res.socket.remoteAddress
    const port = res.socket.remotePort
    res.end(`Your IP address is ${ip} and your source port is ${port}.`)
  })
  .listen(3000)

É garantido que esta propriedade seja uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário tenha especificado um tipo de socket diferente de <net.Socket>.

response.statusCode

Adicionado em: v0.4.0

• <number> Padrão: 200

Ao usar cabeçalhos implícitos (não chamar response.writeHead() explicitamente), esta propriedade controla o código de status que será enviado ao cliente quando os cabeçalhos forem liberados.

response.statusCode = 404

Após o cabeçalho da resposta ser enviado ao cliente, esta propriedade indica o código de status que foi enviado.

response.statusMessage

Adicionado em: v0.11.8

• <string>

Ao usar cabeçalhos implícitos (não chamar response.writeHead() explicitamente), esta propriedade controla a mensagem de status que será enviada ao cliente quando os cabeçalhos forem descarregados. Se isso for deixado como undefined, a mensagem padrão para o código de status será usada.

response.statusMessage = 'Não encontrado'

Depois que o cabeçalho da resposta foi enviado ao cliente, esta propriedade indica a mensagem de status que foi enviada.

response.strictContentLength

Adicionado em: v18.10.0, v16.18.0

• <boolean> Padrão: false

Se definido como true, o Node.js verificará se o valor do cabeçalho Content-Length e o tamanho do corpo, em bytes, são iguais. A incompatibilidade do valor do cabeçalho Content-Length resultará em um Error sendo lançado, identificado por code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

response.uncork()

Adicionado em: v13.2.0, v12.16.0

Consulte writable.uncork().

response.writableEnded

Adicionado em: v12.9.0

• <boolean>

É true depois que response.end() foi chamado. Esta propriedade não indica se os dados foram descarregados, para isso use response.writableFinished.

response.writableFinished

Adicionado em: v12.7.0

• <boolean>

É true se todos os dados foram descarregados para o sistema subjacente, imediatamente antes do evento 'finish' ser emitido.

response.write(chunk[, encoding][, callback])

[Histórico]

Versão	Mudanças
v15.0.0	O parâmetro chunk agora pode ser um Uint8Array.
v0.1.29	Adicionado em: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Padrão: 'utf8'
• callback <Function>
• Retorna: <boolean>

Se este método for chamado e response.writeHead() não tiver sido chamado, ele mudará para o modo de cabeçalho implícito e descarregará os cabeçalhos implícitos.

Isso envia um pedaço do corpo da resposta. Este método pode ser chamado várias vezes para fornecer partes sucessivas do corpo.

Se rejectNonStandardBodyWrites for definido como true em createServer, a gravação no corpo não será permitida quando o método de requisição ou o status da resposta não suportarem conteúdo. Se for feita uma tentativa de gravação no corpo para uma requisição HEAD ou como parte de uma resposta 204 ou 304, um Error síncrono com o código ERR_HTTP_BODY_NOT_ALLOWED é lançado.

chunk pode ser uma string ou um buffer. Se chunk for uma string, o segundo parâmetro especifica como codificá-la em um fluxo de bytes. callback será chamado quando este pedaço de dados for descarregado.

Este é o corpo HTTP bruto e não tem nada a ver com codificações de corpo multipartes de nível superior que podem ser usadas.

A primeira vez que response.write() é chamado, ele enviará as informações de cabeçalho armazenadas em buffer e o primeiro pedaço do corpo para o cliente. A segunda vez que response.write() é chamado, o Node.js assume que os dados serão transmitidos e envia os novos dados separadamente. Ou seja, a resposta é armazenada em buffer até o primeiro pedaço do corpo.

Retorna true se todos os dados foram descarregados com sucesso para o buffer do kernel. Retorna false se todos ou parte dos dados foram enfileirados na memória do usuário. 'drain' será emitido quando o buffer estiver livre novamente.

response.writeContinue()

Adicionado em: v0.3.0

Envia uma mensagem HTTP/1.1 100 Continue para o cliente, indicando que o corpo da solicitação deve ser enviado. Veja o evento 'checkContinue' em Server.

response.writeEarlyHints(hints[, callback])

[Histórico]

Versão	Mudanças
v18.11.0	Permite passar hints como um objeto.
v18.11.0	Adicionado em: v18.11.0

• hints <Objeto>
• callback <Função>

Envia uma mensagem HTTP/1.1 103 Early Hints para o cliente com um cabeçalho Link, indicando que o agente do usuário pode pré-carregar/pré-conectar os recursos vinculados. O hints é um objeto contendo os valores dos cabeçalhos a serem enviados com a mensagem de early hints. O argumento opcional callback será chamado quando a mensagem de resposta tiver sido escrita.

Exemplo

const earlyHintsLink = '</styles.css>; rel=preload; as=style'
response.writeEarlyHints({
  link: earlyHintsLink,
})

const earlyHintsLinks = ['</styles.css>; rel=preload; as=style', '</scripts.js>; rel=preload; as=script']
response.writeEarlyHints({
  link: earlyHintsLinks,
  'x-trace-id': 'id for diagnostics',
})

const earlyHintsCallback = () => console.log('early hints message sent')
response.writeEarlyHints(
  {
    link: earlyHintsLinks,
  },
  earlyHintsCallback
)

response.writeHead(statusCode[, statusMessage][, headers])

[Histórico]

Versão	Mudanças
v14.14.0	Permite passar cabeçalhos como um array.
v11.10.0, v10.17.0	Retorna this de writeHead() para permitir encadeamento com end().
v5.11.0, v4.4.5	Um RangeError é lançado se statusCode não for um número no intervalo [100, 999].
v0.1.30	Adicionado em: v0.1.30

• statusCode <number>
• statusMessage <string>
• headers <Objeto> | <Array>
• Retorna: <http.ServerResponse>

Envia um cabeçalho de resposta para a requisição. O código de status é um código de status HTTP de 3 dígitos, como 404. O último argumento, headers, são os cabeçalhos de resposta. Opcionalmente, pode-se fornecer uma statusMessage legível por humanos como o segundo argumento.

headers pode ser um Array onde as chaves e valores estão na mesma lista. Não é uma lista de tuplas. Portanto, os deslocamentos de número par são valores de chave e os deslocamentos de número ímpar são os valores associados. O array está no mesmo formato que request.rawHeaders.

Retorna uma referência ao ServerResponse, para que as chamadas possam ser encadeadas.

const body = 'hello world'
response
  .writeHead(200, {
    'Content-Length': Buffer.byteLength(body),
    'Content-Type': 'text/plain',
  })
  .end(body)

Este método deve ser chamado apenas uma vez em uma mensagem e deve ser chamado antes de response.end() ser chamado.

Se response.write() ou response.end() forem chamados antes de chamar este, os cabeçalhos implícitos/mutáveis serão calculados e chamarão esta função.

Quando os cabeçalhos tiverem sido definidos com response.setHeader(), eles serão mesclados com quaisquer cabeçalhos passados para response.writeHead(), com os cabeçalhos passados para response.writeHead() tendo precedência.

Se este método for chamado e response.setHeader() não tiver sido chamado, ele gravará diretamente os valores de cabeçalho fornecidos no canal de rede sem armazenar em cache internamente, e o response.getHeader() no cabeçalho não produzirá o resultado esperado. Se a população progressiva de cabeçalhos for desejada com potencial recuperação e modificação futura, use response.setHeader() em vez disso.

// Retorna content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('ok')
})

Content-Length é lido em bytes, não em caracteres. Use Buffer.byteLength() para determinar o comprimento do corpo em bytes. O Node.js verificará se Content-Length e o comprimento do corpo que foi transmitido são iguais ou não.

Tentar definir um nome ou valor de campo de cabeçalho que contenha caracteres inválidos resultará em um [Erro][] sendo lançado.

response.writeProcessing()

Adicionado em: v10.0.0

Envia uma mensagem HTTP/1.1 102 Processing para o cliente, indicando que o corpo da requisição deve ser enviado.

Classe: http.IncomingMessage

[Histórico]

Versão	Mudanças
v15.5.0	O valor destroyed retorna true após o consumo dos dados recebidos.
v13.1.0, v12.16.0	O valor readableHighWaterMark espelha o do socket.
v0.1.17	Adicionado em: v0.1.17

• Estende: <stream.Readable>

Um objeto IncomingMessage é criado por http.Server ou http.ClientRequest e passado como o primeiro argumento para os eventos 'request' e 'response', respectivamente. Ele pode ser usado para acessar o status da resposta, cabeçalhos e dados.

Diferentemente do seu valor socket, que é uma subclasse de <stream.Duplex>, o IncomingMessage em si estende <stream.Readable> e é criado separadamente para analisar e emitir os cabeçalhos HTTP de entrada e o payload, já que o socket subjacente pode ser reutilizado várias vezes em caso de keep-alive.

Evento: 'aborted'

Adicionado em: v0.3.8

Obsoleto desde: v17.0.0, v16.12.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Ouça o evento 'close' em vez disso.

Emitido quando a requisição foi abortada.

Evento: 'close'

[Histórico]

Versão	Mudanças
v16.0.0	O evento close agora é emitido quando a requisição foi concluída e não quando o socket subjacente é fechado.
v0.4.2	Adicionado em: v0.4.2

Emitido quando a requisição foi concluída.

message.aborted

Adicionado em: v10.1.0

Obsoleto desde: v17.0.0, v16.12.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Verifique message.destroyed de <stream.Readable>.

• <boolean>

A propriedade message.aborted será true se a requisição tiver sido abortada.

message.complete

Adicionado em: v0.3.0

• <boolean>

A propriedade message.complete será true se uma mensagem HTTP completa tiver sido recebida e analisada com sucesso.

Essa propriedade é particularmente útil como meio de determinar se um cliente ou servidor transmitiu totalmente uma mensagem antes que uma conexão fosse encerrada:

const req = http.request(
  {
    host: '127.0.0.1',
    port: 8080,
    method: 'POST',
  },
  res => {
    res.resume()
    res.on('end', () => {
      if (!res.complete) console.error('A conexão foi encerrada enquanto a mensagem ainda estava sendo enviada')
    })
  }
)

message.connection

Adicionado em: v0.1.90

Obsoleto desde: v16.0.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Use message.socket.

Alias para message.socket.

message.destroy([error])

[Histórico]

Versão	Mudanças
v14.5.0, v12.19.0	A função retorna this para consistência com outros fluxos Readable.
v0.3.0	Adicionado em: v0.3.0

• error <Error>
• Retorna: <this>

Chama destroy() no socket que recebeu o IncomingMessage. Se error for fornecido, um evento 'error' é emitido no socket e error é passado como um argumento para quaisquer ouvintes no evento.

message.headers

[Histórico]

Versão	Mudanças
v19.5.0, v18.14.0	A opção joinDuplicateHeaders nas funções http.request() e http.createServer() garante que cabeçalhos duplicados não sejam descartados, mas sim combinados usando um separador de vírgula, de acordo com a Seção 5.3 do RFC 9110.
v15.1.0	message.headers agora é calculado preguiçosamente usando uma propriedade de acessador no protótipo e não é mais enumerável.
v0.1.5	Adicionado em: v0.1.5

• <Object>

O objeto de cabeçalhos de solicitação/resposta.

Pares de chave-valor de nomes e valores de cabeçalho. Os nomes de cabeçalho são convertidos para minúsculas.

// Imprime algo como:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers)

Duplicatas em cabeçalhos brutos são tratadas das seguintes maneiras, dependendo do nome do cabeçalho:

• Duplicatas de age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server ou user-agent são descartadas. Para permitir que valores duplicados dos cabeçalhos listados acima sejam unidos, use a opção joinDuplicateHeaders em http.request() e http.createServer(). Consulte a Seção 5.3 do RFC 9110 para obter mais informações.
• set-cookie é sempre um array. Duplicatas são adicionadas ao array.
• Para cabeçalhos cookie duplicados, os valores são unidos com ; .
• Para todos os outros cabeçalhos, os valores são unidos com , .

message.headersDistinct

Adicionado em: v18.3.0, v16.17.0

• <Object>

Semelhante a message.headers, mas não há lógica de junção e os valores são sempre arrays de strings, mesmo para cabeçalhos recebidos apenas uma vez.

// Imprime algo como:
//
// { 'user-agent': ['curl/7.22.0'],
//   host: ['127.0.0.1:8000'],
//   accept: ['*/*'] }
console.log(request.headersDistinct)

message.httpVersion

Adicionado em: v0.1.1

• <string>

No caso de solicitação do servidor, a versão HTTP enviada pelo cliente. No caso de resposta do cliente, a versão HTTP do servidor conectado. Provavelmente '1.1' ou '1.0'.

Além disso, message.httpVersionMajor é o primeiro número inteiro e message.httpVersionMinor é o segundo.

message.method

Adicionado em: v0.1.1

• <string>

Válido apenas para solicitação obtida de http.Server.

O método de solicitação como uma string. Somente leitura. Exemplos: 'GET', 'DELETE'.

message.rawHeaders

Adicionado em: v0.11.6

• <string[]>

A lista bruta de cabeçalhos de solicitação/resposta exatamente como foram recebidos.

As chaves e os valores estão na mesma lista. Não é uma lista de tuplas. Portanto, os deslocamentos de número par são valores de chave e os deslocamentos de número ímpar são os valores associados.

Os nomes de cabeçalho não são minúsculos e os duplicados não são mesclados.

// Imprime algo como:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders)

message.rawTrailers

Adicionado em: v0.11.6

• <string[]>

As chaves e valores brutos de trailer de solicitação/resposta exatamente como foram recebidos. Preenchido apenas no evento 'end'.

message.setTimeout(msecs[, callback])

Adicionado em: v0.5.9

• msecs <number>
• callback <Function>
• Retorna: <http.IncomingMessage>

Chama message.socket.setTimeout(msecs, callback).

message.socket

Adicionado em: v0.3.0

• <stream.Duplex>

O objeto net.Socket associado à conexão.

Com suporte a HTTPS, use request.socket.getPeerCertificate() para obter os detalhes de autenticação do cliente.

Esta propriedade tem a garantia de ser uma instância da classe <net.Socket>, uma subclasse de <stream.Duplex>, a menos que o usuário especifique um tipo de socket diferente de <net.Socket> ou anulado internamente.

message.statusCode

Adicionado em: v0.1.1

• <number>

Válido apenas para a resposta obtida de http.ClientRequest.

O código de status de resposta HTTP de 3 dígitos. Ex: 404.

message.statusMessage

Adicionado em: v0.11.10

• <string>

Válido apenas para a resposta obtida de http.ClientRequest.

A mensagem de status da resposta HTTP (frase de motivo). Ex: OK ou Internal Server Error.

message.trailers

Adicionado em: v0.3.0

• <Object>

O objeto de trailers de solicitação/resposta. Preenchido apenas no evento 'end'.

message.trailersDistinct

Adicionado em: v18.3.0, v16.17.0

• <Object>

Semelhante a message.trailers, mas não há lógica de junção e os valores são sempre arrays de strings, mesmo para cabeçalhos recebidos apenas uma vez. Preenchido apenas no evento 'end'.

message.url

Adicionado em: v0.1.90

• <string>

Válido apenas para requisições obtidas de http.Server.

String da URL da requisição. Contém apenas a URL presente na requisição HTTP real. Considere a seguinte requisição:

GET /status?name=ryan HTTP/1.1 Accept: text/plain

Para analisar a URL em suas partes:

new URL(`http://${process.env.HOST ?? 'localhost'}${request.url}`)

Quando request.url é '/status?name=ryan' e process.env.HOST não está definido:

$ node
> new URL(`http://${process.env.HOST ?? 'localhost'}${request.url}`);
URL {
  href: 'http://localhost/status?name=ryan',
  origin: 'http://localhost',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'localhost',
  hostname: 'localhost',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

Certifique-se de definir process.env.HOST para o nome do host do servidor ou considere substituir esta parte completamente. Se estiver usando req.headers.host, garanta que a validação apropriada seja usada, pois os clientes podem especificar um cabeçalho Host personalizado.

Classe: http.OutgoingMessage

Adicionado em: v0.1.17

• Estende: <Stream>

Esta classe serve como classe pai de http.ClientRequest e http.ServerResponse. É uma mensagem de saída abstrata da perspectiva dos participantes de uma transação HTTP.

Evento: 'drain'

Adicionado em: v0.3.6

Emitido quando o buffer da mensagem está livre novamente.

Evento: 'finish'

Adicionado em: v0.1.17

Emitido quando a transmissão é concluída com sucesso.

Evento: 'prefinish'

Adicionado em: v0.11.6

Emitido após outgoingMessage.end() ser chamado. Quando o evento é emitido, todos os dados foram processados, mas não necessariamente totalmente descarregados.

outgoingMessage.addTrailers(headers)

Adicionado em: v0.3.0

• headers <Objeto>

Adiciona trailers HTTP (cabeçalhos, mas no final da mensagem) à mensagem.

Os trailers serão emitidos apenas se a mensagem for codificada em partes. Caso contrário, os trailers serão silenciosamente descartados.

O HTTP requer que o cabeçalho Trailer seja enviado para emitir trailers, com uma lista de nomes de campos de cabeçalho em seu valor, por exemplo:

message.writeHead(200, { 'Content-Type': 'text/plain', Trailer: 'Content-MD5' })
message.write(fileData)
message.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' })
message.end()

A tentativa de definir um nome de campo de cabeçalho ou valor que contenha caracteres inválidos resultará no lançamento de um TypeError.

outgoingMessage.appendHeader(name, value)

Adicionado em: v18.3.0, v16.17.0

• name <string> Nome do cabeçalho
• value <string> | <string[]> Valor do cabeçalho
• Retorna: <this>

Adiciona um único valor de cabeçalho ao objeto de cabeçalho.

Se o valor for um array, isso é equivalente a chamar este método várias vezes.

Se não houvesse valores anteriores para o cabeçalho, isso é equivalente a chamar outgoingMessage.setHeader(name, value).

Dependendo do valor de options.uniqueHeaders quando a solicitação do cliente ou o servidor foram criados, isso acabará fazendo com que o cabeçalho seja enviado várias vezes ou uma única vez com os valores unidos usando ; .

outgoingMessage.connection

Adicionado em: v0.3.0

Obsoleto desde: v15.12.0, v14.17.1

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use outgoingMessage.socket em vez disso.

Alias de outgoingMessage.socket.

outgoingMessage.cork()

Adicionado em: v13.2.0, v12.16.0

Ver writable.cork().

outgoingMessage.destroy([error])

Adicionado em: v0.3.0

• error <Error> Opcional, um erro para emitir com o evento error
• Retorna: <this>

Destrói a mensagem. Assim que um socket está associado à mensagem e está conectado, esse socket também será destruído.

outgoingMessage.end(chunk[, encoding][, callback])

[Histórico]

Versão	Mudanças
v15.0.0	O parâmetro chunk agora pode ser um Uint8Array.
v0.11.6	adicionado argumento callback.
v0.1.90	Adicionado em: v0.1.90

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Opcional, Padrão: utf8
• callback <Function> Opcional
• Retorna: <this>

Finaliza a mensagem de saída. Se alguma parte do corpo não for enviada, ela será descarregada para o sistema subjacente. Se a mensagem for em partes, ela enviará a parte final 0\r\n\r\n e enviará os trailers (se houver).

Se chunk for especificado, é equivalente a chamar outgoingMessage.write(chunk, encoding), seguido por outgoingMessage.end(callback).

Se callback for fornecido, ele será chamado quando a mensagem for finalizada (equivalente a um listener do evento 'finish').

outgoingMessage.flushHeaders()

Adicionado em: v1.6.0

Descarrega os cabeçalhos da mensagem.

Por razões de eficiência, o Node.js normalmente armazena em buffer os cabeçalhos da mensagem até que outgoingMessage.end() seja chamado ou o primeiro pedaço de dados da mensagem seja gravado. Em seguida, ele tenta empacotar os cabeçalhos e os dados em um único pacote TCP.

Geralmente é desejável (economiza uma viagem de ida e volta TCP), mas não quando os primeiros dados não são enviados até possivelmente muito mais tarde. outgoingMessage.flushHeaders() ignora a otimização e inicia a mensagem.

outgoingMessage.getHeader(name)

Adicionado em: v0.4.0

• name <string> Nome do cabeçalho
• Retorna: <string> | <undefined>

Obtém o valor do cabeçalho HTTP com o nome fornecido. Se esse cabeçalho não estiver definido, o valor retornado será undefined.

outgoingMessage.getHeaderNames()

Adicionado em: v7.7.0

• Retorna: <string[]>

Retorna um array contendo os nomes únicos dos cabeçalhos de saída atuais. Todos os nomes são em minúsculas.

outgoingMessage.getHeaders()

Adicionado em: v7.7.0

• Retorna: <Object>

Retorna uma cópia superficial dos cabeçalhos de saída atuais. Como uma cópia superficial é usada, os valores de array podem ser modificados sem chamadas adicionais para vários métodos de módulo HTTP relacionados a cabeçalhos. As chaves do objeto retornado são os nomes dos cabeçalhos e os valores são os respectivos valores dos cabeçalhos. Todos os nomes de cabeçalhos são em minúsculas.

O objeto retornado pelo método outgoingMessage.getHeaders() não herda prototipicamente de Object JavaScript. Isso significa que métodos típicos de Object, como obj.toString(), obj.hasOwnProperty() e outros não são definidos e não funcionarão.

outgoingMessage.setHeader('Foo', 'bar')
outgoingMessage.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headers = outgoingMessage.getHeaders()
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }

outgoingMessage.hasHeader(name)

Adicionado em: v7.7.0

• name <string>
• Retorna: <boolean>

Retorna true se o cabeçalho identificado por name estiver atualmente definido nos cabeçalhos de saída. O nome do cabeçalho não diferencia maiúsculas de minúsculas.

const hasContentType = outgoingMessage.hasHeader('content-type')

outgoingMessage.headersSent

Adicionado em: v0.9.3

• <boolean>

Somente leitura. true se os cabeçalhos foram enviados, caso contrário, false.

outgoingMessage.pipe()

Adicionado em: v9.0.0

Substitui o método stream.pipe() herdado da classe legada Stream, que é a classe pai de http.OutgoingMessage.

Chamar este método lançará um Error porque outgoingMessage é um fluxo somente para escrita.

outgoingMessage.removeHeader(name)

Adicionado em: v0.4.0

• name <string> Nome do cabeçalho

Remove um cabeçalho que está na fila para envio implícito.

outgoingMessage.removeHeader('Content-Encoding')

outgoingMessage.setHeader(name, value)

Adicionado em: v0.4.0

• name <string> Nome do cabeçalho
• value <any> Valor do cabeçalho
• Retorna: <this>

Define um único valor de cabeçalho. Se o cabeçalho já existir nos cabeçalhos a serem enviados, seu valor será substituído. Use um array de strings para enviar vários cabeçalhos com o mesmo nome.

outgoingMessage.setHeaders(headers)

Adicionado em: v19.6.0, v18.15.0

• headers <Headers> | <Map>
• Retorna: <this>

Define vários valores de cabeçalho para cabeçalhos implícitos. headers deve ser uma instância de Headers ou Map, se um cabeçalho já existir nos cabeçalhos a serem enviados, seu valor será substituído.

const headers = new Headers({ foo: 'bar' })
outgoingMessage.setHeaders(headers)

ou

const headers = new Map([['foo', 'bar']])
outgoingMessage.setHeaders(headers)

Quando os cabeçalhos foram definidos com outgoingMessage.setHeaders(), eles serão mesclados com quaisquer cabeçalhos passados para response.writeHead(), com os cabeçalhos passados para response.writeHead() tendo precedência.

// Retorna content-type = text/plain
const server = http.createServer((req, res) => {
  const headers = new Headers({ 'Content-Type': 'text/html' })
  res.setHeaders(headers)
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('ok')
})

outgoingMessage.setTimeout(msesc[, callback])

Adicionado em: v0.9.12

• msesc <number>
• callback <Function> Função opcional a ser chamada quando ocorre um timeout. O mesmo que vincular ao evento timeout.
• Retorna: <this>

Assim que um socket é associado à mensagem e está conectado, socket.setTimeout() será chamado com msecs como o primeiro parâmetro.

outgoingMessage.socket

Adicionado em: v0.3.0

• <stream.Duplex>

Referência ao socket subjacente. Geralmente, os usuários não desejam acessar essa propriedade.

Depois de chamar outgoingMessage.end(), esta propriedade será anulada.

outgoingMessage.uncork()

Adicionado em: v13.2.0, v12.16.0

Ver writable.uncork()

outgoingMessage.writableCorked

Adicionado em: v13.2.0, v12.16.0

• <number>

O número de vezes que outgoingMessage.cork() foi chamado.

outgoingMessage.writableEnded

Adicionado em: v12.9.0

• <boolean>

É true se outgoingMessage.end() foi chamado. Esta propriedade não indica se os dados foram descarregados. Para esse propósito, use message.writableFinished em vez disso.

outgoingMessage.writableFinished

Adicionado em: v12.7.0

• <boolean>

É true se todos os dados foram descarregados para o sistema subjacente.

outgoingMessage.writableHighWaterMark

Adicionado em: v12.9.0

• <number>

O highWaterMark do socket subjacente, se atribuído. Caso contrário, o nível de buffer padrão quando writable.write() começa a retornar falso (16384).

outgoingMessage.writableLength

Adicionado em: v12.9.0

• <number>

O número de bytes em buffer.

outgoingMessage.writableObjectMode

Adicionado em: v12.9.0

• <boolean>

Sempre false.

outgoingMessage.write(chunk[, encoding][, callback])

[Histórico]

Versão	Mudanças
v15.0.0	O parâmetro chunk agora pode ser um Uint8Array.
v0.11.6	O argumento callback foi adicionado.
v0.1.29	Adicionado em: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Padrão: utf8
• callback <Function>
• Retorna: <boolean>

Envia um pedaço do corpo. Este método pode ser chamado várias vezes.

O argumento encoding só é relevante quando chunk é uma string. O padrão é 'utf8'.

O argumento callback é opcional e será chamado quando este pedaço de dados for liberado.

Retorna true se todos os dados foram liberados com sucesso para o buffer do kernel. Retorna false se todos ou parte dos dados foram enfileirados na memória do usuário. O evento 'drain' será emitido quando o buffer estiver livre novamente.

http.METHODS

Adicionado em: v0.11.8

• <string[]>

Uma lista dos métodos HTTP que são suportados pelo analisador.

http.STATUS_CODES

Adicionado em: v0.1.22

• <Object>

Uma coleção de todos os códigos de status de resposta HTTP padrão e a descrição curta de cada um. Por exemplo, http.STATUS_CODES[404] === 'Not Found'.

http.createServer([options][, requestListener])

[Histórico]

Versão	Mudanças
v20.1.0, v18.17.0	A opção highWaterMark agora é suportada.
v18.0.0	As opções requestTimeout, headersTimeout, keepAliveTimeout e connectionsCheckingInterval agora são suportadas.
v18.0.0	A opção noDelay agora é definida como true por padrão.
v17.7.0, v16.15.0	As opções noDelay, keepAlive e keepAliveInitialDelay agora são suportadas.
v13.3.0	A opção maxHeaderSize agora é suportada.
v13.8.0, v12.15.0, v10.19.0	A opção insecureHTTPParser agora é suportada.
v9.6.0, v8.12.0	O argumento options agora é suportado.
v0.1.13	Adicionado em: v0.1.13

• options <Objeto>

  • connectionsCheckingInterval: Define o valor do intervalo em milissegundos para verificar o tempo limite de requisição e cabeçalhos em requisições incompletas. Padrão: 30000.
  • headersTimeout: Define o valor do tempo limite em milissegundos para receber os cabeçalhos HTTP completos do cliente. Consulte server.headersTimeout para mais informações. Padrão: 60000.
  • highWaterMark <número> Opcionalmente, sobrescreve todos os readableHighWaterMark e writableHighWaterMark dos sockets. Isso afeta a propriedade highWaterMark tanto de IncomingMessage quanto de ServerResponse. Padrão: Consulte stream.getDefaultHighWaterMark().
  • insecureHTTPParser <booleano> Se definido como true, utilizará um analisador HTTP com flags de tolerância habilitadas. O uso do analisador inseguro deve ser evitado. Consulte --insecure-http-parser para mais informações. Padrão: false.
  • IncomingMessage <http.IncomingMessage> Especifica a classe IncomingMessage a ser usada. Útil para estender o IncomingMessage original. Padrão: IncomingMessage.
  • joinDuplicateHeaders <booleano> Se definido como true, esta opção permite unir os valores das linhas de campo de vários cabeçalhos em uma requisição com uma vírgula (, ) em vez de descartar os duplicados. Para mais informações, consulte message.headers. Padrão: false.
  • keepAlive <booleano> Se definido como true, habilita a funcionalidade keep-alive no socket imediatamente após o recebimento de uma nova conexão de entrada, similar ao que é feito em [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)]. Padrão: false.
  • keepAliveInitialDelay <número> Se definido com um número positivo, define o atraso inicial antes que a primeira sonda keepalive seja enviada em um socket ocioso. Padrão: 0.
  • keepAliveTimeout: O número de milissegundos de inatividade que um servidor precisa esperar por dados de entrada adicionais, após terminar de escrever a última resposta, antes que um socket seja destruído. Consulte server.keepAliveTimeout para mais informações. Padrão: 5000.
  • maxHeaderSize <número> Opcionalmente, sobrescreve o valor de --max-http-header-size para requisições recebidas por este servidor, ou seja, o tamanho máximo dos cabeçalhos de requisição em bytes. Padrão: 16384 (16 KiB).
  • noDelay <booleano> Se definido como true, desabilita o uso do algoritmo de Nagle imediatamente após o recebimento de uma nova conexão de entrada. Padrão: true.
  • requestTimeout: Define o valor do tempo limite em milissegundos para receber toda a requisição do cliente. Consulte server.requestTimeout para mais informações. Padrão: 300000.
  • requireHostHeader <booleano> Se definido como true, força o servidor a responder com um código de status 400 (Bad Request) para qualquer mensagem de requisição HTTP/1.1 que não possua um cabeçalho Host (conforme exigido pela especificação). Padrão: true.
  • ServerResponse <http.ServerResponse> Especifica a classe ServerResponse a ser usada. Útil para estender o ServerResponse original. Padrão: ServerResponse.
  • uniqueHeaders <Array> Uma lista de cabeçalhos de resposta que devem ser enviados apenas uma vez. Se o valor do cabeçalho for um array, os itens serão unidos usando ; .
  • rejectNonStandardBodyWrites <booleano> Se definido como true, um erro será lançado ao escrever em uma resposta HTTP que não possui um corpo. Padrão: false.

• requestListener <Função>

• Retorna: <http.Server>

Retorna uma nova instância de http.Server.

O requestListener é uma função que é automaticamente adicionada ao evento 'request'.

ESM

import http from 'node:http'

// Cria um servidor local para receber dados de
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Olá Mundo!',
    })
  )
})

server.listen(8000)

CJS

const http = require('node:http')

// Cria um servidor local para receber dados de
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Olá Mundo!',
    })
  )
})

server.listen(8000)

ESM

import http from 'node:http'

// Cria um servidor local para receber dados de
const server = http.createServer()

// Escuta o evento de requisição
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Olá Mundo!',
    })
  )
})

server.listen(8000)

CJS

const http = require('node:http')

// Cria um servidor local para receber dados de
const server = http.createServer()

// Escuta o evento de requisição
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Olá Mundo!',
    })
  )
})

server.listen(8000)

http.get(options[, callback])

http.get(url[, options][, callback])

[Histórico]

Versão	Mudanças
v10.9.0	O parâmetro url agora pode ser passado junto com um objeto options separado.
v7.5.0	O parâmetro options pode ser um objeto URL WHATWG.
v0.3.6	Adicionado em: v0.3.6

• url <string> | <URL>
• options <Object> Aceita as mesmas options que http.request(), com o método definido como GET por padrão.
• callback <Function>
• Retorna: <http.ClientRequest>

Como a maioria das requisições são requisições GET sem corpos, o Node.js fornece este método de conveniência. A única diferença entre este método e http.request() é que ele define o método como GET por padrão e chama req.end() automaticamente. O callback deve ter o cuidado de consumir os dados de resposta pelas razões declaradas na seção http.ClientRequest.

O callback é invocado com um único argumento que é uma instância de http.IncomingMessage.

Exemplo de busca JSON:

http
  .get('http://localhost:8000/', res => {
    const { statusCode } = res
    const contentType = res.headers['content-type']

    let error
    // Qualquer código de status 2xx sinaliza uma resposta bem-sucedida, mas
    // aqui estamos verificando apenas 200.
    if (statusCode !== 200) {
      error = new Error('Falha na Requisição.\n' + `Código de Status: ${statusCode}`)
    } else if (!/^application\/json/.test(contentType)) {
      error = new Error('Tipo de conteúdo inválido.\n' + `Esperado application/json, mas recebido ${contentType}`)
    }
    if (error) {
      console.error(error.message)
      // Consumir dados de resposta para liberar memória
      res.resume()
      return
    }

    res.setEncoding('utf8')
    let rawData = ''
    res.on('data', chunk => {
      rawData += chunk
    })
    res.on('end', () => {
      try {
        const parsedData = JSON.parse(rawData)
        console.log(parsedData)
      } catch (e) {
        console.error(e.message)
      }
    })
  })
  .on('error', e => {
    console.error(`Obteve erro: ${e.message}`)
  })

// Criar um servidor local para receber dados
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: 'Olá Mundo!',
    })
  )
})

server.listen(8000)

http.globalAgent

[Histórico]

Versão	Mudanças
v19.0.0	O agente agora usa HTTP Keep-Alive e um tempo limite de 5 segundos por padrão.
v0.5.9	Adicionado em: v0.5.9

• <http.Agent>

Instância global de Agent que é usada como padrão para todas as requisições de cliente HTTP. Difere de uma configuração Agent padrão por ter keepAlive habilitado e um timeout de 5 segundos.

http.maxHeaderSize

Adicionado em: v11.6.0, v10.15.0

• <number>

Propriedade somente leitura que especifica o tamanho máximo permitido de cabeçalhos HTTP em bytes. O padrão é 16 KiB. Configurável usando a opção CLI --max-http-header-size.

Isso pode ser substituído para servidores e solicitações de clientes passando a opção maxHeaderSize.

http.request(options[, callback])

http.request(url[, options][, callback])

[Histórico]

Versão	Mudanças
v16.7.0, v14.18.0	Ao usar um objeto URL analisado, o nome de usuário e a senha agora serão decodificados corretamente em URI.
v15.3.0, v14.17.0	É possível abortar uma requisição com um AbortSignal.
v13.3.0	A opção maxHeaderSize agora é suportada.
v13.8.0, v12.15.0, v10.19.0	A opção insecureHTTPParser agora é suportada.
v10.9.0	O parâmetro url agora pode ser passado juntamente com um objeto options separado.
v7.5.0	O parâmetro options pode ser um objeto WHATWG URL.
v0.3.6	Adicionado em: v0.3.6

• url <string> | <URL>
• options <Object>
  • agent <http.Agent> | <boolean> Controla o comportamento do Agent. Valores possíveis:
  • undefined (padrão): usa http.globalAgent para este host e porta.
  • Objeto Agent: usa explicitamente o Agent passado.
  • false: faz com que um novo Agent com valores padrão seja usado.
  • auth <string> Autenticação básica ('usuário:senha') para calcular um cabeçalho de Autorização.
  • createConnection <Function> Uma função que produz um socket/stream para usar na requisição quando a opção agent não é usada. Isso pode ser usado para evitar criar uma classe Agent personalizada apenas para substituir a função padrão createConnection. Consulte agent.createConnection() para mais detalhes. Qualquer stream Duplex é um valor de retorno válido.
  • defaultPort <number> Porta padrão para o protocolo. Padrão: agent.defaultPort se um Agent for usado, caso contrário, undefined.
  • family <number> Família de endereço IP a ser usada ao resolver host ou hostname. Valores válidos são 4 ou 6. Quando não especificado, ambos os IP v4 e v6 serão usados.
  • headers <Object> Um objeto contendo os cabeçalhos da requisição.
  • hints <number> Dicas opcionais do dns.lookup().
  • host <string> Um nome de domínio ou endereço IP do servidor para o qual emitir a requisição. Padrão: 'localhost'.
  • hostname <string> Alias para host. Para suportar url.parse(), hostname será usado se ambos host e hostname forem especificados.
  • insecureHTTPParser <boolean> Se definido como true, ele usará um analisador HTTP com flags de tolerância habilitadas. O uso do analisador inseguro deve ser evitado. Consulte --insecure-http-parser para mais informações. Padrão: false
  • joinDuplicateHeaders <boolean> Ele une os valores de linha de campo de vários cabeçalhos em uma requisição com , em vez de descartar os duplicados. Consulte message.headers para mais informações. Padrão: false.
  • localAddress <string> Interface local para vincular para conexões de rede.
  • localPort <number> Porta local para se conectar.
  • lookup <Function> Função de pesquisa personalizada. Padrão: dns.lookup().
  • maxHeaderSize <number> Opcionalmente, substitui o valor de --max-http-header-size (o comprimento máximo dos cabeçalhos de resposta em bytes) para respostas recebidas do servidor. Padrão: 16384 (16 KiB).
  • method <string> Uma string especificando o método de requisição HTTP. Padrão: 'GET'.
  • path <string> Caminho da requisição. Deve incluir a string de consulta, se houver. Ex: '/index.html?page=12'. Uma exceção é lançada quando o caminho da requisição contém caracteres ilegais. Atualmente, apenas espaços são rejeitados, mas isso pode mudar no futuro. Padrão: '/'.
  • port <number> Porta do servidor remoto. Padrão: defaultPort se definido, caso contrário, 80.
  • protocol <string> Protocolo a ser usado. Padrão: 'http:'.
  • setDefaultHeaders <boolean>: Especifica se deve ou não adicionar automaticamente cabeçalhos padrão, como Connection, Content-Length, Transfer-Encoding e Host. Se definido como false, todos os cabeçalhos necessários devem ser adicionados manualmente. O padrão é true.
  • setHost <boolean>: Especifica se deve ou não adicionar automaticamente o cabeçalho Host. Se fornecido, isso substitui setDefaultHeaders. O padrão é true.
  • signal <AbortSignal>: Um AbortSignal que pode ser usado para abortar uma requisição em andamento.
  • socketPath <string> Socket de domínio Unix. Não pode ser usado se um de host ou port for especificado, pois eles especificam um Socket TCP.
  • timeout <number>: Um número especificando o tempo limite do socket em milissegundos. Isso definirá o tempo limite antes que o socket seja conectado.
  • uniqueHeaders <Array> Uma lista de cabeçalhos de requisição que devem ser enviados apenas uma vez. Se o valor do cabeçalho for um array, os itens serão unidos usando ; .
• callback <Function>
• Retorna: <http.ClientRequest>

options em socket.connect() também são suportadas.

O Node.js mantém várias conexões por servidor para fazer requisições HTTP. Essa função permite que se emita requisições de forma transparente.

url pode ser uma string ou um objeto URL. Se url for uma string, ela será analisada automaticamente com new URL(). Se for um objeto URL, ele será automaticamente convertido em um objeto options comum.

Se ambos url e options forem especificados, os objetos serão mesclados, com as propriedades options tendo precedência.

O parâmetro callback opcional será adicionado como um listener único para o evento 'response'.

http.request() retorna uma instância da classe http.ClientRequest. A instância ClientRequest é um stream gravável. Se for necessário fazer upload de um arquivo com uma requisição POST, então escreva para o objeto ClientRequest.

ESM

import http from 'node:http'
import { Buffer } from 'node:buffer'

const postData = JSON.stringify({
  msg: 'Olá Mundo!',
})

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
}

const req = http.request(options, res => {
  console.log(`STATUS: ${res.statusCode}`)
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`)
  res.setEncoding('utf8')
  res.on('data', chunk => {
    console.log(`BODY: ${chunk}`)
  })
  res.on('end', () => {
    console.log('Não há mais dados na resposta.')
  })
})

req.on('error', e => {
  console.error(`problema com a requisição: ${e.message}`)
})

// Escreve dados no corpo da requisição
req.write(postData)
req.end()

CJS

const http = require('node:http')

const postData = JSON.stringify({
  msg: 'Olá Mundo!',
})

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
}

const req = http.request(options, res => {
  console.log(`STATUS: ${res.statusCode}`)
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`)
  res.setEncoding('utf8')
  res.on('data', chunk => {
    console.log(`BODY: ${chunk}`)
  })
  res.on('end', () => {
    console.log('Não há mais dados na resposta.')
  })
})

req.on('error', e => {
  console.error(`problema com a requisição: ${e.message}`)
})

// Escreve dados no corpo da requisição
req.write(postData)
req.end()

No exemplo, req.end() foi chamado. Com http.request(), deve-se sempre chamar req.end() para indicar o final da requisição - mesmo que não haja dados sendo escritos no corpo da requisição.

Se algum erro for encontrado durante a requisição (seja com a resolução de DNS, erros de nível TCP ou erros reais de análise HTTP), um evento 'error' será emitido no objeto de requisição retornado. Como com todos os eventos 'error', se nenhum listener for registrado, o erro será lançado.

Existem alguns cabeçalhos especiais que devem ser observados.

• Enviar um 'Connection: keep-alive' notificará o Node.js que a conexão com o servidor deve ser persistida até a próxima requisição.
• Enviar um cabeçalho 'Content-Length' desabilitará a codificação em partes padrão.
• Enviar um cabeçalho 'Expect' enviará imediatamente os cabeçalhos da requisição. Normalmente, ao enviar 'Expect: 100-continue', um tempo limite e um listener para o evento 'continue' devem ser definidos. Consulte a Seção 8.2.3 da RFC 2616 para obter mais informações.
• Enviar um cabeçalho Authorization substituirá o uso da opção auth para calcular a autenticação básica.

Exemplo usando um URL como options:

const options = new URL('http://abc:')

const req = http.request(options, res => {
  // ...
})

Em uma requisição bem-sucedida, os seguintes eventos serão emitidos na seguinte ordem:

• 'socket'
• 'response'
  • 'data' qualquer número de vezes, no objeto res ('data' não será emitido se o corpo da resposta estiver vazio, por exemplo, na maioria dos redirecionamentos)
  • 'end' no objeto res
• 'close'

No caso de um erro de conexão, os seguintes eventos serão emitidos:

• 'socket'
• 'error'
• 'close'

No caso de um fechamento prematuro da conexão antes que a resposta seja recebida, os seguintes eventos serão emitidos na seguinte ordem:

• 'socket'
• 'error' com um erro com a mensagem 'Error: socket hang up' e o código 'ECONNRESET'
• 'close'

No caso de um fechamento prematuro da conexão após o recebimento da resposta, os seguintes eventos serão emitidos na seguinte ordem:

• 'socket'
• 'response'
  • 'data' qualquer número de vezes, no objeto res
• (conexão fechada aqui)
• 'aborted' no objeto res
• 'close'
• 'error' no objeto res com um erro com a mensagem 'Error: aborted' e o código 'ECONNRESET'
• 'close' no objeto res

Se req.destroy() for chamado antes que um socket seja atribuído, os seguintes eventos serão emitidos na seguinte ordem:

• (req.destroy() chamado aqui)
• 'error' com um erro com a mensagem 'Error: socket hang up' e o código 'ECONNRESET', ou o erro com o qual req.destroy() foi chamado
• 'close'

Se req.destroy() for chamado antes que a conexão seja bem-sucedida, os seguintes eventos serão emitidos na seguinte ordem:

• 'socket'
• (req.destroy() chamado aqui)
• 'error' com um erro com a mensagem 'Error: socket hang up' e o código 'ECONNRESET', ou o erro com o qual req.destroy() foi chamado
• 'close'

Se req.destroy() for chamado após o recebimento da resposta, os seguintes eventos serão emitidos na seguinte ordem:

• 'socket'
• 'response'
  • 'data' qualquer número de vezes, no objeto res
• (req.destroy() chamado aqui)
• 'aborted' no objeto res
• 'close'
• 'error' no objeto res com um erro com a mensagem 'Error: aborted' e o código 'ECONNRESET', ou o erro com o qual req.destroy() foi chamado
• 'close' no objeto res

Se req.abort() for chamado antes que um socket seja atribuído, os seguintes eventos serão emitidos na seguinte ordem:

• (req.abort() chamado aqui)
• 'abort'
• 'close'

Se req.abort() for chamado antes que a conexão seja bem-sucedida, os seguintes eventos serão emitidos na seguinte ordem:

• 'socket'
• (req.abort() chamado aqui)
• 'abort'
• 'error' com um erro com a mensagem 'Error: socket hang up' e o código 'ECONNRESET'
• 'close'

Se req.abort() for chamado após o recebimento da resposta, os seguintes eventos serão emitidos na seguinte ordem:

• 'socket'
• 'response'
  • 'data' qualquer número de vezes, no objeto res
• (req.abort() chamado aqui)
• 'abort'
• 'aborted' no objeto res
• 'error' no objeto res com um erro com a mensagem 'Error: aborted' e o código 'ECONNRESET'.
• 'close'
• 'close' no objeto res

Definir a opção timeout ou usar a função setTimeout() não abortará a requisição nem fará nada além de adicionar um evento 'timeout'.

Passar um AbortSignal e, em seguida, chamar abort() no AbortController correspondente terá o mesmo comportamento que chamar .destroy() na requisição. Especificamente, o evento 'error' será emitido com um erro com a mensagem 'AbortError: The operation was aborted', o código 'ABORT_ERR' e a cause, se uma foi fornecida.

http.validateHeaderName(name[, label])

[Histórico]

Versão	Mudanças
v19.5.0, v18.14.0	O parâmetro label foi adicionado.
v14.3.0	Adicionado em: v14.3.0

• name <string>
• label <string> Rótulo para a mensagem de erro. Padrão: 'Nome do cabeçalho'.

Realiza as validações de baixo nível no name fornecido que são feitas quando res.setHeader(name, value) é chamado.

Passar um valor ilegal como name resultará em um TypeError sendo lançado, identificado por code: 'ERR_INVALID_HTTP_TOKEN'.

Não é necessário usar este método antes de passar cabeçalhos para uma requisição ou resposta HTTP. O módulo HTTP validará automaticamente tais cabeçalhos.

Exemplo:

ESM

import { validateHeaderName } from 'node:http'

try {
  validateHeaderName('')
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code) // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message) // --> 'O nome do cabeçalho deve ser um token HTTP válido [""]'
}

CJS

const { validateHeaderName } = require('node:http')

try {
  validateHeaderName('')
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code) // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message) // --> 'O nome do cabeçalho deve ser um token HTTP válido [""]'
}

http.validateHeaderValue(name, value)

Adicionado em: v14.3.0

• name <string>
• value <any>

Realiza as validações de baixo nível no value fornecido que são feitas quando res.setHeader(name, value) é chamado.

Passar um valor ilegal como value resultará em um TypeError sendo lançado.

• O erro de valor indefinido é identificado por code: 'ERR_HTTP_INVALID_HEADER_VALUE'.
• O erro de caractere de valor inválido é identificado por code: 'ERR_INVALID_CHAR'.

Não é necessário usar este método antes de passar cabeçalhos para uma requisição ou resposta HTTP. O módulo HTTP validará automaticamente tais cabeçalhos.

Exemplos:

ESM

import { validateHeaderValue } from 'node:http'

try {
  validateHeaderValue('x-my-header', undefined)
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE') // --> true
  console.error(err.message) // --> 'Valor inválido "undefined" para o cabeçalho "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə')
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code === 'ERR_INVALID_CHAR') // --> true
  console.error(err.message) // --> 'Caractere inválido no conteúdo do cabeçalho ["x-my-header"]'
}

CJS

const { validateHeaderValue } = require('node:http')

try {
  validateHeaderValue('x-my-header', undefined)
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE') // --> true
  console.error(err.message) // --> 'Valor inválido "undefined" para o cabeçalho "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə')
} catch (err) {
  console.error(err instanceof TypeError) // --> true
  console.error(err.code === 'ERR_INVALID_CHAR') // --> true
  console.error(err.message) // --> 'Caractere inválido no conteúdo do cabeçalho ["x-my-header"]'
}

http.setMaxIdleHTTPParsers(max)

Adicionado em: v18.8.0, v16.18.0

• max <number> Padrão: 1000.

Define o número máximo de analisadores HTTP ociosos.

WebSocket

Adicionado em: v22.5.0

Uma implementação compatível com o navegador de WebSocket.