HTTP/2

[Histórico]

Versão	Mudanças
v15.0.0	Requisições com o cabeçalho host (com ou sem :authority) agora podem ser enviadas/recebidas.
v15.3.0, v14.17.0	É possível abortar uma requisição com um AbortSignal.
v10.10.0	HTTP/2 agora é Estável. Anteriormente, era Experimental.
v8.4.0	Adicionado em: v8.4.0

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código Fonte: lib/http2.js

O módulo node:http2 fornece uma implementação do protocolo HTTP/2. Ele pode ser acessado usando:

const http2 = require('node:http2')

Determinando se o suporte a criptografia não está disponível

É possível que o Node.js seja construído sem incluir suporte para o módulo node:crypto. Nesses casos, tentar import de node:http2 ou chamar require('node:http2') resultará em um erro sendo lançado.

Ao usar CommonJS, o erro lançado pode ser capturado usando try/catch:

let http2
try {
  http2 = require('node:http2')
} catch (err) {
  console.error('O suporte a http2 está desabilitado!')
}

Ao usar a palavra-chave léxica import do ESM, o erro só pode ser capturado se um manipulador para process.on('uncaughtException') for registrado antes de qualquer tentativa de carregar o módulo ser feita (usando, por exemplo, um módulo de pré-carregamento).

Ao usar ESM, se houver uma chance de que o código possa ser executado em uma construção do Node.js onde o suporte a criptografia não esteja habilitado, considere usar a função import() em vez da palavra-chave léxica import:

let http2
try {
  http2 = await import('node:http2')
} catch (err) {
  console.error('O suporte a http2 está desabilitado!')
}

API Principal

A API Principal fornece uma interface de baixo nível projetada especificamente em torno do suporte para recursos do protocolo HTTP/2. Ela não foi projetada especificamente para compatibilidade com a API do módulo HTTP/1 existente. No entanto, a API de Compatibilidade é.

A API Principal http2 é muito mais simétrica entre cliente e servidor do que a API http. Por exemplo, a maioria dos eventos, como 'error', 'connect' e 'stream', pode ser emitida pelo código do lado do cliente ou pelo código do lado do servidor.

Exemplo do lado do servidor

O exemplo a seguir ilustra um servidor HTTP/2 simples usando a API Core. Como não há navegadores conhecidos que suportem HTTP/2 não criptografado, o uso de http2.createSecureServer() é necessário ao se comunicar com clientes de navegador.

ESM

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

const server = createSecureServer({
  key: readFileSync('localhost-privkey.pem'),
  cert: readFileSync('localhost-cert.pem'),
})

server.on('error', err => console.error(err))

server.on('stream', (stream, headers) => {
  // stream é um Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Olá Mundo</h1>')
})

server.listen(8443)

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const server = http2.createSecureServer({
  key: fs.readFileSync('localhost-privkey.pem'),
  cert: fs.readFileSync('localhost-cert.pem'),
})
server.on('error', err => console.error(err))

server.on('stream', (stream, headers) => {
  // stream é um Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Olá Mundo</h1>')
})

server.listen(8443)

Para gerar o certificado e a chave para este exemplo, execute:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout localhost-privkey.pem -out localhost-cert.pem

Exemplo do lado do cliente

O seguinte ilustra um cliente HTTP/2:

ESM

import { connect } from 'node:http2'
import { readFileSync } from 'node:fs'

const client = connect('https://localhost:8443', {
  ca: readFileSync('localhost-cert.pem'),
})
client.on('error', err => console.error(err))

const req = client.request({ ':path': '/' })

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`)
  }
})

req.setEncoding('utf8')
let data = ''
req.on('data', chunk => {
  data += chunk
})
req.on('end', () => {
  console.log(`\n${data}`)
  client.close()
})
req.end()

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const client = http2.connect('https://localhost:8443', {
  ca: fs.readFileSync('localhost-cert.pem'),
})
client.on('error', err => console.error(err))

const req = client.request({ ':path': '/' })

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`)
  }
})

req.setEncoding('utf8')
let data = ''
req.on('data', chunk => {
  data += chunk
})
req.on('end', () => {
  console.log(`\n${data}`)
  client.close()
})
req.end()

Classe: Http2Session

Adicionado em: v8.4.0

• Estende: <EventEmitter>

Instâncias da classe http2.Http2Session representam uma sessão de comunicação ativa entre um cliente HTTP/2 e um servidor. Instâncias desta classe não se destinam a ser construídas diretamente pelo código do usuário.

Cada instância de Http2Session exibirá comportamentos ligeiramente diferentes dependendo de estar operando como um servidor ou um cliente. A propriedade http2session.type pode ser usada para determinar o modo em que uma Http2Session está operando. No lado do servidor, o código do usuário raramente deve ter ocasião de trabalhar diretamente com o objeto Http2Session, com a maioria das ações normalmente realizadas por meio de interações com os objetos Http2Server ou Http2Stream.

O código do usuário não criará instâncias Http2Session diretamente. As instâncias Http2Session do lado do servidor são criadas pela instância Http2Server quando uma nova conexão HTTP/2 é recebida. As instâncias Http2Session do lado do cliente são criadas usando o método http2.connect().

Http2Session e sockets

Cada instância de Http2Session está associada a exatamente um net.Socket ou tls.TLSSocket quando é criada. Quando o Socket ou o Http2Session são destruídos, ambos serão destruídos.

Devido aos requisitos específicos de serialização e processamento impostos pelo protocolo HTTP/2, não é recomendável que o código do usuário leia ou escreva dados em uma instância de Socket vinculada a uma Http2Session. Isso pode colocar a sessão HTTP/2 em um estado indeterminado, fazendo com que a sessão e o socket se tornem inutilizáveis.

Depois que um Socket é vinculado a uma Http2Session, o código do usuário deve confiar exclusivamente na API do Http2Session.

Evento: 'close'

Adicionado em: v8.4.0

O evento 'close' é emitido quando o Http2Session é destruído. Seu ouvinte não espera nenhum argumento.

Evento: 'connect'

Adicionado em: v8.4.0

• session <Http2Session>
• socket <net.Socket>

O evento 'connect' é emitido quando o Http2Session foi conectado com sucesso ao par remoto e a comunicação pode começar.

O código do usuário normalmente não ouvirá este evento diretamente.

Event: 'error'

Adicionado em: v8.4.0

• error <Error>

O evento 'error' é emitido quando ocorre um erro durante o processamento de uma Http2Session.

Event: 'frameError'

Adicionado em: v8.4.0

• type <integer> O tipo de frame.
• code <integer> O código de erro.
• id <integer> O id do fluxo (ou 0 se o frame não estiver associado a um fluxo).

O evento 'frameError' é emitido quando ocorre um erro ao tentar enviar um frame na sessão. Se o frame que não pôde ser enviado estiver associado a um Http2Stream específico, é feita uma tentativa de emitir um evento 'frameError' no Http2Stream.

Se o evento 'frameError' estiver associado a um fluxo, o fluxo será fechado e destruído imediatamente após o evento 'frameError'. Se o evento não estiver associado a um fluxo, a Http2Session será desligada imediatamente após o evento 'frameError'.

Event: 'goaway'

Adicionado em: v8.4.0

• errorCode <number> O código de erro HTTP/2 especificado no frame GOAWAY.
• lastStreamID <number> O ID do último fluxo que o peer remoto processou com sucesso (ou 0 se nenhum ID for especificado).
• opaqueData <Buffer> Se dados opacos adicionais foram incluídos no frame GOAWAY, uma instância de Buffer será passada contendo esses dados.

O evento 'goaway' é emitido quando um frame GOAWAY é recebido.

A instância Http2Session será desligada automaticamente quando o evento 'goaway' for emitido.

Evento: 'localSettings'

Adicionado em: v8.4.0

• settings <Objeto de Configurações HTTP/2> Uma cópia do quadro SETTINGS recebido.

O evento 'localSettings' é emitido quando um quadro de SETTINGS de confirmação foi recebido.

Ao usar http2session.settings() para enviar novas configurações, as configurações modificadas não entrarão em vigor até que o evento 'localSettings' seja emitido.

session.settings({ enablePush: false })

session.on('localSettings', settings => {
  /* Use as novas configurações */
})

Evento: 'ping'

Adicionado em: v10.12.0

• payload <Buffer> O payload de 8 bytes do quadro PING

O evento 'ping' é emitido sempre que um quadro PING é recebido do peer conectado.

Evento: 'remoteSettings'

Adicionado em: v8.4.0

• settings <Objeto de Configurações HTTP/2> Uma cópia do quadro SETTINGS recebido.

O evento 'remoteSettings' é emitido quando um novo quadro SETTINGS é recebido do peer conectado.

session.on('remoteSettings', settings => {
  /* Use as novas configurações */
})

Evento: 'stream'

Adicionado em: v8.4.0

• stream <Http2Stream> Uma referência para o stream
• headers <Objeto de Cabeçalhos HTTP/2> Um objeto descrevendo os cabeçalhos
• flags <number> Os flags numéricos associados
• rawHeaders <Array> Um array contendo os nomes de cabeçalho brutos seguidos por seus respectivos valores.

O evento 'stream' é emitido quando um novo Http2Stream é criado.

session.on('stream', (stream, headers, flags) => {
  const method = headers[':method']
  const path = headers[':path']
  // ...
  stream.respond({
    ':status': 200,
    'content-type': 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

No lado do servidor, o código do usuário normalmente não escutará este evento diretamente e, em vez disso, registrará um manipulador para o evento 'stream' emitido pelas instâncias net.Server ou tls.Server retornadas por http2.createServer() e http2.createSecureServer(), respectivamente, como no exemplo abaixo:

ESM

import { createServer } from 'node:http2'

// Cria um servidor HTTP/2 não criptografado
const server = createServer()

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.on('error', error => console.error(error))
  stream.end('<h1>Hello World</h1>')
})

server.listen(8000)

CJS

const http2 = require('node:http2')

// Cria um servidor HTTP/2 não criptografado
const server = http2.createServer()

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.on('error', error => console.error(error))
  stream.end('<h1>Hello World</h1>')
})

server.listen(8000)

Embora os streams HTTP/2 e os sockets de rede não estejam em uma correspondência 1:1, um erro de rede destruirá cada stream individual e deverá ser tratado no nível do stream, conforme mostrado acima.

Evento: 'timeout'

Adicionado em: v8.4.0

Após o método http2session.setTimeout() ser usado para definir o período de timeout para esta Http2Session, o evento 'timeout' é emitido se não houver atividade na Http2Session após o número configurado de milissegundos. Seu listener não espera nenhum argumento.

session.setTimeout(2000)
session.on('timeout', () => {
  /* .. */
})

http2session.alpnProtocol

Adicionado em: v9.4.0

• <string> | <undefined>

O valor será undefined se a Http2Session ainda não estiver conectada a um socket, h2c se a Http2Session não estiver conectada a um TLSSocket ou retornará o valor da própria propriedade alpnProtocol do TLSSocket conectado.

http2session.close([callback])

Adicionado em: v9.4.0

• callback <Function>

Fecha graciosamente a Http2Session, permitindo que quaisquer streams existentes sejam concluídos por conta própria e impedindo a criação de novas instâncias de Http2Stream. Uma vez fechado, http2session.destroy() pode ser chamado se não houver instâncias de Http2Stream abertas.

Se especificado, a função callback é registrada como um manipulador para o evento 'close'.

http2session.closed

Adicionado em: v9.4.0

• <boolean>

Será true se esta instância de Http2Session foi fechada, caso contrário, false.

http2session.connecting

Adicionado em: v10.0.0

• <boolean>

Será true se esta instância de Http2Session ainda estiver se conectando, será definido como false antes de emitir o evento connect e/ou chamar o callback de http2.connect.

http2session.destroy([error][, code])

Adicionado em: v8.4.0

• error <Error> Um objeto Error se a Http2Session estiver sendo destruída devido a um erro.
• code <number> O código de erro HTTP/2 a ser enviado no frame GOAWAY final. Se não especificado, e error não for indefinido, o padrão é INTERNAL_ERROR, caso contrário, o padrão é NO_ERROR.

Encerra imediatamente a Http2Session e o net.Socket ou tls.TLSSocket associados.

Uma vez destruída, a Http2Session emitirá o evento 'close'. Se error não for indefinido, um evento 'error' será emitido imediatamente antes do evento 'close'.

Se houver algum Http2Stream aberto restante associado à Http2Session, eles também serão destruídos.

http2session.destroyed

Adicionado em: v8.4.0

• <boolean>

Será true se esta instância Http2Session tiver sido destruída e não deverá mais ser usada, caso contrário, false.

http2session.encrypted

Adicionado em: v9.4.0

• <boolean> | <undefined>

O valor é undefined se o socket da sessão Http2Session ainda não tiver sido conectado, true se o Http2Session estiver conectado com um TLSSocket e false se o Http2Session estiver conectado a qualquer outro tipo de socket ou fluxo.

http2session.goaway([code[, lastStreamID[, opaqueData]]])

Adicionado em: v9.4.0

• code <number> Um código de erro HTTP/2
• lastStreamID <number> O ID numérico do último Http2Stream processado
• opaqueData <Buffer> | <TypedArray> | <DataView> Uma instância de TypedArray ou DataView contendo dados adicionais a serem transportados dentro do frame GOAWAY.

Transmite um frame GOAWAY para o peer conectado sem encerrar o Http2Session.

http2session.localSettings

Adicionado em: v8.4.0

• <Objeto de Configurações HTTP/2>

Um objeto sem protótipo descrevendo as configurações locais atuais deste Http2Session. As configurações locais são locais para esta instância Http2Session.

http2session.originSet

Adicionado em: v9.4.0

• <string[]> | <undefined>

Se o Http2Session estiver conectado a um TLSSocket, a propriedade originSet retornará um Array de origens para as quais o Http2Session pode ser considerado autoritário.

A propriedade originSet está disponível apenas quando se usa uma conexão TLS segura.

http2session.pendingSettingsAck

Adicionado em: v8.4.0

• <boolean>

Indica se o Http2Session está atualmente aguardando o reconhecimento de um quadro SETTINGS enviado. Será true após chamar o método http2session.settings(). Será false assim que todos os quadros SETTINGS enviados forem reconhecidos.

http2session.ping([payload, ]callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.9.3	Adicionado em: v8.9.3

• payload <Buffer> | <TypedArray> | <DataView> Payload de ping opcional.
• callback <Function>
• Retorna: <boolean>

Envia um quadro PING para o par HTTP/2 conectado. Uma função callback deve ser fornecida. O método retornará true se o PING foi enviado, false caso contrário.

O número máximo de pings pendentes (não reconhecidos) é determinado pela opção de configuração maxOutstandingPings. O máximo padrão é 10.

Se fornecido, o payload deve ser um Buffer, TypedArray ou DataView contendo 8 bytes de dados que serão transmitidos com o PING e retornados com o reconhecimento do ping.

O callback será invocado com três argumentos: um argumento de erro que será null se o PING foi reconhecido com sucesso, um argumento duration que reporta o número de milissegundos decorridos desde que o ping foi enviado e o reconhecimento foi recebido, e um Buffer contendo o payload de 8 bytes do PING.

session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`Ping reconhecido em ${duration} milissegundos`)
    console.log(`Com payload '${payload.toString()}'`)
  }
})

Se o argumento payload não for especificado, o payload padrão será o timestamp de 64 bits (little endian) marcando o início da duração do PING.

http2session.ref()

Adicionado em: v9.4.0

Chama ref() na net.Socket subjacente desta instância de Http2Session.

http2session.remoteSettings

Adicionado em: v8.4.0

• <Objeto de Configurações HTTP/2>

Um objeto sem protótipo que descreve as configurações remotas atuais desta Http2Session. As configurações remotas são definidas pelo par HTTP/2 conectado.

http2session.setLocalWindowSize(windowSize)

Adicionado em: v15.3.0, v14.18.0

• windowSize <number>

Define o tamanho da janela do ponto de extremidade local. O windowSize é o tamanho total da janela a ser definido, não o delta.

ESM

import { createServer } from 'node:http2'

const server = createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // Define o tamanho da janela local para ser 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // Define o tamanho da janela local para ser 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

Para clientes http2, o evento apropriado é 'connect' ou 'remoteSettings'.

http2session.setTimeout(msecs, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.4.0	Adicionado em: v8.4.0

• msecs <number>
• callback <Function>

Usado para definir uma função de callback que é chamada quando não há atividade na Http2Session após msecs milissegundos. O callback fornecido é registrado como um listener no evento 'timeout'.

http2session.socket

Adicionado em: v8.4.0

• <net.Socket> | <tls.TLSSocket>

Retorna um objeto Proxy que atua como um net.Socket (ou tls.TLSSocket), mas limita os métodos disponíveis aos que são seguros para uso com HTTP/2.

destroy, emit, end, pause, read, resume e write lançarão um erro com o código ERR_HTTP2_NO_SOCKET_MANIPULATION. Consulte Http2Session e Sockets para obter mais informações.

O método setTimeout será chamado nesta Http2Session.

Todas as outras interações serão encaminhadas diretamente para o socket.

http2session.state

Adicionado em: v8.4.0

Fornece informações diversas sobre o estado atual da Http2Session.

• <Objeto>
  • effectiveLocalWindowSize <number> O tamanho atual da janela de controle de fluxo local (recebimento) para a Http2Session.
  • effectiveRecvDataLength <number> O número atual de bytes que foram recebidos desde o último WINDOW_UPDATE de controle de fluxo.
  • nextStreamID <number> O identificador numérico a ser usado na próxima vez que um novo Http2Stream for criado por esta Http2Session.
  • localWindowSize <number> O número de bytes que o par remoto pode enviar sem receber um WINDOW_UPDATE.
  • lastProcStreamID <number> O ID numérico do Http2Stream para o qual um quadro HEADERS ou DATA foi recebido mais recentemente.
  • remoteWindowSize <number> O número de bytes que esta Http2Session pode enviar sem receber um WINDOW_UPDATE.
  • outboundQueueSize <number> O número de quadros atualmente dentro da fila de saída para esta Http2Session.
  • deflateDynamicTableSize <number> O tamanho atual em bytes da tabela de estado de compressão de cabeçalho de saída.
  • inflateDynamicTableSize <number> O tamanho atual em bytes da tabela de estado de compressão de cabeçalho de entrada.

Um objeto que descreve o status atual desta Http2Session.

http2session.settings([settings][, callback])

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.4.0	Adicionado em: v8.4.0

• settings <Objeto de Configurações HTTP/2>
• callback <Função> Callback que é chamado assim que a sessão é conectada ou imediatamente se a sessão já estiver conectada.
  • err <Erro> | <null>
  • settings <Objeto de Configurações HTTP/2> O objeto settings atualizado.
  • duration <integer>

Atualiza as configurações locais atuais para esta Http2Session e envia um novo quadro SETTINGS para o par HTTP/2 conectado.

Uma vez chamado, a propriedade http2session.pendingSettingsAck será true enquanto a sessão estiver aguardando o par remoto reconhecer as novas configurações.

As novas configurações não entrarão em vigor até que o reconhecimento do SETTINGS seja recebido e o evento 'localSettings' seja emitido. É possível enviar vários quadros SETTINGS enquanto o reconhecimento ainda estiver pendente.

http2session.type

Adicionado em: v8.4.0

• <número>

O http2session.type será igual a http2.constants.NGHTTP2_SESSION_SERVER se esta instância Http2Session for um servidor, e http2.constants.NGHTTP2_SESSION_CLIENT se a instância for um cliente.

http2session.unref()

Adicionado em: v9.4.0

Chama unref() no net.Socket subjacente desta instância Http2Session.

Classe: ServerHttp2Session

Adicionado em: v8.4.0

• Estende: <Http2Session>

serverhttp2session.altsvc(alt, originOrStream)

Adicionado em: v9.4.0

• alt <string> Uma descrição da configuração do serviço alternativo conforme definido pela RFC 7838.
• originOrStream <number> | <string> | <URL> | <Object> Uma string URL especificando a origem (ou um Object com uma propriedade origin) ou o identificador numérico de um Http2Stream ativo, conforme fornecido pela propriedade http2stream.id.

Envia um frame ALTSVC (conforme definido pela RFC 7838) ao cliente conectado.

ESM

import { createServer } from 'node:http2'

const server = createServer()
server.on('session', session => {
  // Define altsvc para a origem https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // Define altsvc para um stream específico
  stream.session.altsvc('h2=":8000"', stream.id)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
server.on('session', session => {
  // Define altsvc para a origem https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // Define altsvc para um stream específico
  stream.session.altsvc('h2=":8000"', stream.id)
})

O envio de um frame ALTSVC com um ID de stream específico indica que o serviço alternativo está associado à origem do Http2Stream fornecido.

A string alt e a string de origem devem conter apenas bytes ASCII e são estritamente interpretadas como uma sequência de bytes ASCII. O valor especial 'clear' pode ser passado para limpar qualquer serviço alternativo definido anteriormente para um determinado domínio.

Quando uma string é passada para o argumento originOrStream, ela será analisada como uma URL e a origem será derivada. Por exemplo, a origem para a URL HTTP 'https://example.org/foo/bar' é a string ASCII 'https://example.org'. Um erro será lançado se a string fornecida não puder ser analisada como uma URL ou se uma origem válida não puder ser derivada.

Um objeto URL, ou qualquer objeto com uma propriedade origin, pode ser passado como originOrStream, caso em que o valor da propriedade origin será usado. O valor da propriedade origin deve ser uma origem ASCII serializada corretamente.

Especificando serviços alternativos

O formato do parâmetro alt é estritamente definido pela RFC 7838 como uma string ASCII contendo uma lista delimitada por vírgulas de protocolos "alternativos" associados a um host e porta específicos.

Por exemplo, o valor 'h2="example.org:81"' indica que o protocolo HTTP/2 está disponível no host 'example.org' na porta TCP/IP 81. O host e a porta devem estar contidos dentro dos caracteres de aspas (").

Várias alternativas podem ser especificadas, por exemplo: 'h2="example.org:81", h2=":82"'.

O identificador do protocolo ('h2' nos exemplos) pode ser qualquer ID de Protocolo ALPN válido.

A sintaxe desses valores não é validada pela implementação do Node.js e são repassados conforme fornecidos pelo usuário ou recebidos do par.

serverhttp2session.origin(...origins)

Adicionado em: v10.12.0

• origins <string> | <URL> | <Object> Uma ou mais Strings URL passadas como argumentos separados.

Envia um frame ORIGIN (conforme definido pela RFC 8336) para o cliente conectado para anunciar o conjunto de origens para as quais o servidor é capaz de fornecer respostas autoritativas.

ESM

import { createSecureServer } from 'node:http2'
const options = getSecureOptionsSomehow()
const server = createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})
server.on('session', session => {
  session.origin('https://example.com', 'https://example.org')
})

CJS

const http2 = require('node:http2')
const options = getSecureOptionsSomehow()
const server = http2.createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})
server.on('session', session => {
  session.origin('https://example.com', 'https://example.org')
})

Quando uma string é passada como origin, ela será analisada como uma URL e a origem será derivada. Por exemplo, a origem para a URL HTTP 'https://example.org/foo/bar' é a string ASCII 'https://example.org'. Um erro será lançado se a string fornecida não puder ser analisada como uma URL ou se uma origem válida não puder ser derivada.

Um objeto URL, ou qualquer objeto com uma propriedade origin, pode ser passado como uma origin, caso em que o valor da propriedade origin será usado. O valor da propriedade origin deve ser uma origem ASCII devidamente serializada.

Alternativamente, a opção origins pode ser usada ao criar um novo servidor HTTP/2 usando o método http2.createSecureServer():

ESM

import { createSecureServer } from 'node:http2'
const options = getSecureOptionsSomehow()
options.origins = ['https://example.com', 'https://example.org']
const server = createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})

CJS

const http2 = require('node:http2')
const options = getSecureOptionsSomehow()
options.origins = ['https://example.com', 'https://example.org']
const server = http2.createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})

Classe: ClientHttp2Session

Adicionado em: v8.4.0

• Estende: <Http2Session>

Evento: 'altsvc'

Adicionado em: v9.4.0

• alt <string>
• origin <string>
• streamId <number>

O evento 'altsvc' é emitido sempre que um frame ALTSVC é recebido pelo cliente. O evento é emitido com o valor ALTSVC, origem e ID do fluxo. Se nenhuma origin for fornecida no frame ALTSVC, origin será uma string vazia.

ESM

import { connect } from 'node:http2'
const client = connect('https://example.org')

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt)
  console.log(origin)
  console.log(streamId)
})

CJS

const http2 = require('node:http2')
const client = http2.connect('https://example.org')

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt)
  console.log(origin)
  console.log(streamId)
})

Evento: 'origin'

Adicionado em: v10.12.0

• origins <string[]>

O evento 'origin' é emitido sempre que um frame ORIGIN é recebido pelo cliente. O evento é emitido com um array de strings origin. O http2session.originSet será atualizado para incluir as origens recebidas.

ESM

import { connect } from 'node:http2'
const client = connect('https://example.org')

client.on('origin', origins => {
  for (let n = 0; n < origins.length; n++) console.log(origins[n])
})

CJS

const http2 = require('node:http2')
const client = http2.connect('https://example.org')

client.on('origin', origins => {
  for (let n = 0; n < origins.length; n++) console.log(origins[n])
})

O evento 'origin' só é emitido quando se usa uma conexão TLS segura.

clienthttp2session.request(headers[, options])

Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2>

• options <Objeto>

  • endStream <boolean> true se o lado gravável do Http2Stream deve ser fechado inicialmente, como ao enviar uma requisição GET que não deve esperar um corpo de payload.
  • exclusive <boolean> Quando true e parent identifica um Stream pai, o stream criado é feito o único dependente direto do pai, com todos os outros dependentes existentes tornando-se dependentes do stream recém-criado. Padrão: false.
  • parent <number> Especifica o identificador numérico de um stream do qual o stream recém-criado depende.
  • weight <number> Especifica a dependência relativa de um stream em relação a outros streams com o mesmo parent. O valor é um número entre 1 e 256 (inclusive).
  • waitForTrailers <boolean> Quando true, o Http2Stream emitirá o evento 'wantTrailers' após o envio do frame final DATA.
  • signal <AbortSignal> Um AbortSignal que pode ser usado para abortar uma requisição em andamento.

• Retorna: <ClientHttp2Stream>

Apenas para instâncias Http2Session de cliente HTTP/2, o http2session.request() cria e retorna uma instância Http2Stream que pode ser usada para enviar uma requisição HTTP/2 para o servidor conectado.

Quando um ClientHttp2Session é criado pela primeira vez, o socket pode ainda não estar conectado. Se clienthttp2session.request() for chamado durante este tempo, a requisição real será adiada até que o socket esteja pronto para funcionar. Se a session for fechada antes que a requisição real seja executada, um ERR_HTTP2_GOAWAY_SESSION é lançado.

Este método está disponível apenas se http2session.type for igual a http2.constants.NGHTTP2_SESSION_CLIENT.

ESM

import { connect, constants } from 'node:http2'
const clientSession = connect('https://localhost:1234')
const { HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS } = constants

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' })
req.on('response', headers => {
  console.log(headers[HTTP2_HEADER_STATUS])
  req.on('data', chunk => {
    /* .. */
  })
  req.on('end', () => {
    /* .. */
  })
})

CJS

const http2 = require('node:http2')
const clientSession = http2.connect('https://localhost:1234')
const { HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS } = http2.constants

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' })
req.on('response', headers => {
  console.log(headers[HTTP2_HEADER_STATUS])
  req.on('data', chunk => {
    /* .. */
  })
  req.on('end', () => {
    /* .. */
  })
})

Quando a opção options.waitForTrailers é definida, o evento 'wantTrailers' é emitido imediatamente após o enfileiramento do último pedaço de dados de payload a ser enviado. O método http2stream.sendTrailers() pode então ser chamado para enviar cabeçalhos de trailer para o par.

Quando options.waitForTrailers é definido, o Http2Stream não será fechado automaticamente quando o frame final DATA for transmitido. O código do usuário deve chamar http2stream.sendTrailers() ou http2stream.close() para fechar o Http2Stream.

Quando options.signal é definido com um AbortSignal e então abort no AbortController correspondente é chamado, a requisição emitirá um evento 'error' com um erro AbortError.

Os pseudo-cabeçalhos :method e :path não são especificados em headers, eles assumem respectivamente os seguintes valores por padrão:

• :method = 'GET'
• :path = /

Classe: Http2Stream

Adicionado em: v8.4.0

• Estende: <stream.Duplex>

Cada instância da classe Http2Stream representa um fluxo de comunicação HTTP/2 bidirecional sobre uma instância Http2Session. Qualquer Http2Session única pode ter até 2^31-1 instâncias Http2Stream durante sua vida útil.

O código do usuário não construirá instâncias Http2Stream diretamente. Em vez disso, elas são criadas, gerenciadas e fornecidas ao código do usuário através da instância Http2Session. No servidor, as instâncias Http2Stream são criadas em resposta a uma solicitação HTTP de entrada (e entregues ao código do usuário através do evento 'stream'), ou em resposta a uma chamada para o método http2stream.pushStream(). No cliente, as instâncias Http2Stream são criadas e retornadas quando o método http2session.request() é chamado, ou em resposta a um evento 'push' de entrada.

A classe Http2Stream é uma base para as classes ServerHttp2Stream e ClientHttp2Stream, cada uma das quais é usada especificamente pelo lado do Servidor ou do Cliente, respectivamente.

Todas as instâncias Http2Stream são fluxos Duplex. O lado Writable do Duplex é usado para enviar dados para o peer conectado, enquanto o lado Readable é usado para receber dados enviados pelo peer conectado.

A codificação de caracteres de texto padrão para um Http2Stream é UTF-8. Ao usar um Http2Stream para enviar texto, use o cabeçalho 'content-type' para definir a codificação de caracteres.

stream.respond({
  'content-type': 'text/html; charset=utf-8',
  ':status': 200,
})

Ciclo de Vida do Http2Stream

Criação

No lado do servidor, as instâncias de ServerHttp2Stream são criadas quando:

• Um novo quadro HTTP/2 HEADERS com um ID de fluxo não usado anteriormente é recebido;
• O método http2stream.pushStream() é chamado.

No lado do cliente, as instâncias de ClientHttp2Stream são criadas quando o método http2session.request() é chamado.

No cliente, a instância Http2Stream retornada por http2session.request() pode não estar imediatamente pronta para uso se a Http2Session pai ainda não tiver sido totalmente estabelecida. Nesses casos, as operações chamadas no Http2Stream serão armazenadas em buffer até que o evento 'ready' seja emitido. O código do usuário raramente, ou nunca, precisará lidar diretamente com o evento 'ready'. O status de pronto de um Http2Stream pode ser determinado verificando o valor de http2stream.id. Se o valor for undefined, o fluxo ainda não está pronto para uso.

Destruição

Todas as instâncias de Http2Stream são destruídas quando:

• Um frame RST_STREAM para o stream é recebido pelo peer conectado e (somente para streams de cliente) os dados pendentes foram lidos.
• O método http2stream.close() é chamado e (somente para streams de cliente) os dados pendentes foram lidos.
• Os métodos http2stream.destroy() ou http2session.destroy() são chamados.

Quando uma instância de Http2Stream é destruída, uma tentativa será feita para enviar um frame RST_STREAM para o peer conectado.

Quando a instância de Http2Stream é destruída, o evento 'close' será emitido. Como Http2Stream é uma instância de stream.Duplex, o evento 'end' também será emitido se os dados do stream estiverem fluindo no momento. O evento 'error' também pode ser emitido se http2stream.destroy() foi chamado com um Error passado como o primeiro argumento.

Após o Http2Stream ter sido destruído, a propriedade http2stream.destroyed será true e a propriedade http2stream.rstCode especificará o código de erro RST_STREAM. A instância de Http2Stream não é mais utilizável após ser destruída.

Evento: 'aborted'

Adicionado em: v8.4.0

O evento 'aborted' é emitido sempre que uma instância de Http2Stream é abortada anormalmente no meio da comunicação. Seu ouvinte não espera nenhum argumento.

O evento 'aborted' só será emitido se o lado gravável do Http2Stream não tiver sido finalizado.

Evento: 'close'

Adicionado em: v8.4.0

O evento 'close' é emitido quando o Http2Stream é destruído. Uma vez que este evento é emitido, a instância de Http2Stream não é mais utilizável.

O código de erro HTTP/2 usado ao fechar o stream pode ser recuperado usando a propriedade http2stream.rstCode. Se o código for qualquer valor diferente de NGHTTP2_NO_ERROR (0), um evento 'error' também terá sido emitido.

Evento: 'error'

Adicionado em: v8.4.0

• error <Error>

O evento 'error' é emitido quando um erro ocorre durante o processamento de um Http2Stream.

Evento: 'frameError'

Adicionado em: v8.4.0

• type <integer> O tipo de frame.
• code <integer> O código de erro.
• id <integer> O ID do fluxo (ou 0 se o frame não estiver associado a um fluxo).

O evento 'frameError' é emitido quando ocorre um erro ao tentar enviar um frame. Quando invocado, a função manipuladora receberá um argumento inteiro identificando o tipo de frame e um argumento inteiro identificando o código de erro. A instância Http2Stream será destruída imediatamente após a emissão do evento 'frameError'.

Evento: 'ready'

Adicionado em: v8.4.0

O evento 'ready' é emitido quando o Http2Stream foi aberto, recebeu um id e pode ser usado. O ouvinte não espera nenhum argumento.

Evento: 'timeout'

Adicionado em: v8.4.0

O evento 'timeout' é emitido quando nenhuma atividade é recebida para este Http2Stream dentro do número de milissegundos definido usando http2stream.setTimeout(). Seu ouvinte não espera nenhum argumento.

Evento: 'trailers'

Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2> Um objeto descrevendo os cabeçalhos
• flags <número> As flags numéricas associadas

O evento 'trailers' é emitido quando um bloco de cabeçalhos associados a campos de cabeçalho finais é recebido. O retorno de chamada do ouvinte recebe o Objeto de Cabeçalhos HTTP/2 e as flags associadas aos cabeçalhos.

Este evento pode não ser emitido se http2stream.end() for chamado antes que os trailers sejam recebidos e os dados recebidos não estiverem sendo lidos ou ouvidos.

stream.on('trailers', (headers, flags) => {
  console.log(headers)
})

Evento: 'wantTrailers'

Adicionado em: v10.0.0

O evento 'wantTrailers' é emitido quando o Http2Stream enfileirou o último quadro DATA para ser enviado em um quadro e o Http2Stream está pronto para enviar cabeçalhos finais. Ao iniciar uma solicitação ou resposta, a opção waitForTrailers deve ser definida para que esse evento seja emitido.

http2stream.aborted

Adicionado em: v8.4.0

• <boolean>

Definido como true se a instância Http2Stream foi abortada anormalmente. Quando definido, o evento 'aborted' terá sido emitido.

http2stream.bufferSize

Adicionado em: v11.2.0, v10.16.0

• <number>

Esta propriedade mostra o número de caracteres atualmente armazenados em buffer para serem gravados. Consulte net.Socket.bufferSize para detalhes.

http2stream.close(code[, callback])

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.4.0	Adicionado em: v8.4.0

• code <number> Inteiro não assinado de 32 bits que identifica o código de erro. Padrão: http2.constants.NGHTTP2_NO_ERROR (0x00).
• callback <Function> Uma função opcional registrada para ouvir o evento 'close'.

Fecha a instância Http2Stream enviando um quadro RST_STREAM para o par HTTP/2 conectado.

http2stream.closed

Adicionado em: v9.4.0

• <boolean>

Definido como true se a instância Http2Stream foi fechada.

http2stream.destroyed

Adicionado em: v8.4.0

• <boolean>

Definido como true se a instância Http2Stream foi destruída e não está mais utilizável.

http2stream.endAfterHeaders

Adicionado em: v10.11.0

• <boolean>

Definido como true se o sinalizador END_STREAM foi definido no frame HEADERS de solicitação ou resposta recebido, indicando que nenhum dado adicional deve ser recebido e o lado legível do Http2Stream será fechado.

http2stream.id

Adicionado em: v8.4.0

• <number> | <undefined>

O identificador numérico de fluxo desta instância Http2Stream. Definido como undefined se o identificador de fluxo ainda não foi atribuído.

http2stream.pending

Adicionado em: v9.4.0

• <boolean>

Definido como true se a instância Http2Stream ainda não foi atribuída a um identificador de fluxo numérico.

http2stream.priority(options)

Adicionado em: v8.4.0

• options <Object>
  • exclusive <boolean> Quando true e parent identifica um fluxo pai, este fluxo torna-se a única dependência direta do pai, com todos os outros dependentes existentes tornando-se dependentes deste fluxo. Padrão: false.
  • parent <number> Especifica o identificador numérico de um fluxo do qual este fluxo é dependente.
  • weight <number> Especifica a dependência relativa de um fluxo em relação a outros fluxos com o mesmo parent. O valor é um número entre 1 e 256 (inclusive).
  • silent <boolean> Quando true, altera a prioridade localmente sem enviar um frame PRIORITY para o par conectado.

Atualiza a prioridade para esta instância Http2Stream.

http2stream.rstCode

Adicionado em: v8.4.0

• <número>

Definido para o código de erro RST_STREAM código de erro relatado quando o Http2Stream é destruído após receber um quadro RST_STREAM do peer conectado, chamar http2stream.close() ou http2stream.destroy(). Será undefined se o Http2Stream não tiver sido fechado.

http2stream.sentHeaders

Adicionado em: v9.5.0

• <Objeto de Cabeçalhos HTTP/2>

Um objeto contendo os cabeçalhos de saída enviados para este Http2Stream.

http2stream.sentInfoHeaders

Adicionado em: v9.5.0

• <Objeto de Cabeçalhos HTTP/2[]>

Um array de objetos contendo os cabeçalhos informativos (adicionais) de saída enviados para este Http2Stream.

http2stream.sentTrailers

Adicionado em: v9.5.0

• <Objeto de Cabeçalhos HTTP/2>

Um objeto contendo os trailers de saída enviados para este HttpStream.

http2stream.session

Adicionado em: v8.4.0

• <Http2Session>

Uma referência à instância Http2Session que possui este Http2Stream. O valor será undefined após a instância Http2Stream ser destruída.

http2stream.setTimeout(msecs, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.4.0	Adicionado em: v8.4.0

• msecs <número>
• callback <Função>

ESM

import { connect, constants } from 'node:http2'
const client = connect('http://example.org:8000')
const { NGHTTP2_CANCEL } = constants
const req = client.request({ ':path': '/' })

// Cancela o fluxo se não houver atividade após 5 segundos
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

CJS

const http2 = require('node:http2')
const client = http2.connect('http://example.org:8000')
const { NGHTTP2_CANCEL } = http2.constants
const req = client.request({ ':path': '/' })

// Cancela o fluxo se não houver atividade após 5 segundos
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

http2stream.state

Adicionado em: v8.4.0

Fornece informações diversas sobre o estado atual do Http2Stream.

• <Object>
  • localWindowSize <number> O número de bytes que o peer conectado pode enviar para este Http2Stream sem receber um WINDOW_UPDATE.
  • state <number> Um sinalizador indicando o estado atual de baixo nível do Http2Stream conforme determinado por nghttp2.
  • localClose <number> 1 se este Http2Stream foi fechado localmente.
  • remoteClose <number> 1 se este Http2Stream foi fechado remotamente.
  • sumDependencyWeight <number> O peso somado de todas as instâncias Http2Stream que dependem deste Http2Stream conforme especificado usando frames PRIORITY.
  • weight <number> O peso de prioridade deste Http2Stream.

Um estado atual deste Http2Stream.

http2stream.sendTrailers(headers)

Adicionado em: v10.0.0

• headers <Objeto de Cabeçalhos HTTP/2>

Envia um frame HEADERS de trailing para o peer HTTP/2 conectado. Este método fará com que o Http2Stream seja imediatamente fechado e deve ser chamado somente após o evento 'wantTrailers' ter sido emitido. Ao enviar uma solicitação ou enviar uma resposta, a opção options.waitForTrailers deve ser definida para manter o Http2Stream aberto após o frame DATA final para que os trailers possam ser enviados.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respond(undefined, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' })
  })
  stream.end('Hello World')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respond(undefined, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' })
  })
  stream.end('Hello World')
})

A especificação HTTP/1 proíbe que os trailers contenham campos de pseudo-cabeçalho HTTP/2 (por exemplo, ':method', ':path', etc).

Classe: ClientHttp2Stream

Adicionado em: v8.4.0

• Estende <Http2Stream>

A classe ClientHttp2Stream é uma extensão de Http2Stream que é usada exclusivamente em Clientes HTTP/2. As instâncias de Http2Stream no cliente fornecem eventos como 'response' e 'push' que são relevantes apenas no cliente.

Evento: 'continue'

Adicionado em: v8.5.0

Emitido quando o servidor envia um status 100 Continue, geralmente porque a requisição continha Expect: 100-continue. Esta é uma instrução de que o cliente deve enviar o corpo da requisição.

Evento: 'headers'

Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2>
• flags <number>

O evento 'headers' é emitido quando um bloco adicional de cabeçalhos é recebido para um fluxo, como quando um bloco de cabeçalhos informativos 1xx é recebido. O callback do listener recebe o Objeto de Cabeçalhos HTTP/2 e os flags associados aos cabeçalhos.

stream.on('headers', (headers, flags) => {
  console.log(headers)
})

Evento: 'push'

Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2>
• flags <number>

O evento 'push' é emitido quando os cabeçalhos de resposta para um fluxo Server Push são recebidos. O callback do listener recebe o Objeto de Cabeçalhos HTTP/2 e os flags associados aos cabeçalhos.

stream.on('push', (headers, flags) => {
  console.log(headers)
})

Evento: 'response'

Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2>
• flags <number>

O evento 'response' é emitido quando um frame HEADERS de resposta foi recebido para este fluxo do servidor HTTP/2 conectado. O listener é invocado com dois argumentos: um Object contendo o Objeto de Cabeçalhos HTTP/2 recebido e os flags associados aos cabeçalhos.

ESM

import { connect } from 'node:http2'
const client = connect('https://localhost')
const req = client.request({ ':path': '/' })
req.on('response', (headers, flags) => {
  console.log(headers[':status'])
})

CJS

const http2 = require('node:http2')
const client = http2.connect('https://localhost')
const req = client.request({ ':path': '/' })
req.on('response', (headers, flags) => {
  console.log(headers[':status'])
})

Classe: ServerHttp2Stream

Adicionado em: v8.4.0

• Estende: <Http2Stream>

A classe ServerHttp2Stream é uma extensão de Http2Stream que é usada exclusivamente em Servidores HTTP/2. As instâncias de Http2Stream no servidor fornecem métodos adicionais, como http2stream.pushStream() e http2stream.respond(), que são relevantes apenas no servidor.

http2stream.additionalHeaders(headers)

Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2>

Envia um frame HEADERS informativo adicional para o peer HTTP/2 conectado.

http2stream.headersSent

Adicionado em: v8.4.0

• <boolean>

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

http2stream.pushAllowed

Adicionado em: v8.4.0

• <boolean>

Propriedade somente leitura mapeada para o flag SETTINGS_ENABLE_PUSH do frame SETTINGS mais recente do cliente remoto. Será true se o peer remoto aceitar push streams, false caso contrário. As configurações são as mesmas para cada Http2Stream na mesma Http2Session.

http2stream.pushStream(headers[, options], callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.4.0	Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2>

• options <Objeto>

  • exclusive <boolean> Quando true e parent identifica um Stream pai, o stream criado torna-se o único dependente direto do pai, com todos os outros dependentes existentes tornando-se dependentes do stream recém-criado. Padrão: false.
  • parent <number> Especifica o identificador numérico de um stream do qual o stream recém-criado é dependente.

• callback <Função> Callback que é chamado assim que o push stream é iniciado.

  • err <Erro>
  • pushStream <ServerHttp2Stream> O objeto pushStream retornado.
  • headers <Objeto de Cabeçalhos HTTP/2> Objeto de cabeçalhos com o qual o pushStream foi iniciado.

Inicia um push stream. O callback é invocado com a nova instância Http2Stream criada para o push stream passada como o segundo argumento, ou um Erro passado como o primeiro argumento.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 })
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err
    pushStream.respond({ ':status': 200 })
    pushStream.end('some pushed data')
  })
  stream.end('some data')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 })
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err
    pushStream.respond({ ':status': 200 })
    pushStream.end('some pushed data')
  })
  stream.end('some data')
})

Definir o peso de um push stream não é permitido no frame HEADERS. Passe um valor weight para http2stream.priority com a opção silent definida como true para habilitar o balanceamento de largura de banda no lado do servidor entre streams concorrentes.

Chamar http2stream.pushStream() de dentro de um push stream não é permitido e lançará um erro.

http2stream.respond([headers[, options]])

[Histórico]

Versão	Mudanças
v14.5.0, v12.19.0	Permite a definição explícita de cabeçalhos de data.
v8.4.0	Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2>
• options <Objeto>
  • endStream <boolean> Defina como true para indicar que a resposta não incluirá dados de carga.
  • waitForTrailers <boolean> Quando true, o Http2Stream emitirá o evento 'wantTrailers' após o envio do último quadro DATA.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 })
  stream.end('some data')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 })
  stream.end('some data')
})

Inicia uma resposta. Quando a opção options.waitForTrailers é definida, o evento 'wantTrailers' será emitido imediatamente após enfileirar o último bloco de dados de carga a ser enviado. O método http2stream.sendTrailers() pode então ser usado para enviar campos de cabeçalho de trailer para o par.

Quando options.waitForTrailers é definido, o Http2Stream não será fechado automaticamente quando o último quadro DATA for transmitido. O código do usuário deve chamar http2stream.sendTrailers() ou http2stream.close() para fechar o Http2Stream.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })
  stream.end('some data')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })
  stream.end('some data')
})

http2stream.respondWithFD(fd[, headers[, options]])

[Histórico]

Versão	Mudanças
v14.5.0, v12.19.0	Permite definir explicitamente os cabeçalhos de data.
v12.12.0	A opção fd agora pode ser um FileHandle.
v10.0.0	Qualquer descritor de arquivo legível, não necessariamente para um arquivo regular, agora é suportado.
v8.4.0	Adicionado em: v8.4.0

• fd <number> | <FileHandle> Um descritor de arquivo legível.
• headers <Objeto de Cabeçalhos HTTP/2>
• options <Objeto>
  • statCheck <Função>
  • waitForTrailers <boolean> Quando true, o Http2Stream emitirá o evento 'wantTrailers' após o último frame DATA ter sido enviado.
  • offset <number> A posição de deslocamento na qual iniciar a leitura.
  • length <number> A quantidade de dados do fd a serem enviados.

Inicia uma resposta cujos dados são lidos do descritor de arquivo fornecido. Nenhuma validação é realizada no descritor de arquivo fornecido. Se ocorrer um erro ao tentar ler os dados usando o descritor de arquivo, o Http2Stream será fechado usando um frame RST_STREAM usando o código INTERNAL_ERROR padrão.

Quando usado, a interface Duplex do objeto Http2Stream será fechada automaticamente.

ESM

import { createServer } from 'node:http2'
import { openSync, fstatSync, closeSync } from 'node:fs'

const server = createServer()
server.on('stream', stream => {
  const fd = openSync('/some/file', 'r')

  const stat = fstatSync(fd)
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  }
  stream.respondWithFD(fd, headers)
  stream.on('close', () => closeSync(fd))
})

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const server = http2.createServer()
server.on('stream', stream => {
  const fd = fs.openSync('/some/file', 'r')

  const stat = fs.fstatSync(fd)
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  }
  stream.respondWithFD(fd, headers)
  stream.on('close', () => fs.closeSync(fd))
})

A função opcional options.statCheck pode ser especificada para dar ao código do usuário a oportunidade de definir cabeçalhos de conteúdo adicionais com base nos detalhes fs.Stat do fd fornecido. Se a função statCheck for fornecida, o método http2stream.respondWithFD() executará uma chamada fs.fstat() para coletar detalhes sobre o descritor de arquivo fornecido.

As opções offset e length podem ser usadas para limitar a resposta a um subconjunto de intervalo específico. Isso pode ser usado, por exemplo, para dar suporte a solicitações de intervalo HTTP.

O descritor de arquivo ou FileHandle não é fechado quando o stream é fechado, portanto, ele precisará ser fechado manualmente quando não for mais necessário. O uso do mesmo descritor de arquivo simultaneamente para vários streams não é suportado e pode resultar em perda de dados. Reutilizar um descritor de arquivo após o término de um stream é suportado.

Quando a opção options.waitForTrailers é definida, o evento 'wantTrailers' será emitido imediatamente após colocar na fila o último bloco de dados de carga útil a ser enviado. O método http2stream.sendTrailers() pode então ser usado para enviar campos de cabeçalho de trailer para o par.

Quando options.waitForTrailers é definido, o Http2Stream não será fechado automaticamente quando o último frame DATA for transmitido. O código do usuário deve chamar http2stream.sendTrailers() ou http2stream.close() para fechar o Http2Stream.

ESM

import { createServer } from 'node:http2'
import { openSync, fstatSync, closeSync } from 'node:fs'

const server = createServer()
server.on('stream', stream => {
  const fd = openSync('/some/file', 'r')

  const stat = fstatSync(fd)
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  }
  stream.respondWithFD(fd, headers, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })

  stream.on('close', () => closeSync(fd))
})

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const server = http2.createServer()
server.on('stream', stream => {
  const fd = fs.openSync('/some/file', 'r')

  const stat = fs.fstatSync(fd)
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  }
  stream.respondWithFD(fd, headers, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })

  stream.on('close', () => fs.closeSync(fd))
})

http2stream.respondWithFile(path[, headers[, options]])

[Histórico]

Versão	Mudanças
v14.5.0, v12.19.0	Permite definir explicitamente os cabeçalhos de data.
v10.0.0	Qualquer arquivo legível, não necessariamente um arquivo regular, agora é suportado.
v8.4.0	Adicionado em: v8.4.0

• path <string> | <Buffer> | <URL>
• headers <Objeto de Cabeçalhos HTTP/2>
• options <Object>
  • statCheck <Function>
  • onError <Function> Função de callback invocada em caso de erro antes do envio.
  • waitForTrailers <boolean> Quando true, o Http2Stream emitirá o evento 'wantTrailers' após o envio do último frame DATA.
  • offset <number> A posição de offset na qual começar a leitura.
  • length <number> A quantidade de dados do fd a serem enviados.

Envia um arquivo regular como resposta. O path deve especificar um arquivo regular ou um evento 'error' será emitido no objeto Http2Stream.

Quando usado, a interface Duplex do objeto Http2Stream será fechada automaticamente.

A função opcional options.statCheck pode ser especificada para dar ao código do usuário a oportunidade de definir cabeçalhos de conteúdo adicionais com base nos detalhes fs.Stat do arquivo fornecido:

Se ocorrer um erro ao tentar ler os dados do arquivo, o Http2Stream será fechado usando um frame RST_STREAM com o código INTERNAL_ERROR padrão. Se o callback onError for definido, ele será chamado. Caso contrário, o fluxo será destruído.

Exemplo usando um caminho de arquivo:

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString()
  }

  function onError(err) {
    // stream.respond() pode lançar um erro se o fluxo foi destruído
    // pelo outro lado.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // Realize o tratamento de erro real.
      console.error(err)
    }
    stream.end()
  }

  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck, onError })
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString()
  }

  function onError(err) {
    // stream.respond() pode lançar um erro se o fluxo foi destruído
    // pelo outro lado.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // Realize o tratamento de erro real.
      console.error(err)
    }
    stream.end()
  }

  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck, onError })
})

A função options.statCheck também pode ser usada para cancelar a operação de envio retornando false. Por exemplo, uma solicitação condicional pode verificar os resultados do stat para determinar se o arquivo foi modificado para retornar uma resposta 304 apropriada:

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    // Verifique o stat aqui...
    stream.respond({ ':status': 304 })
    return false // Cancela a operação de envio
  }
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck })
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    // Verifique o stat aqui...
    stream.respond({ ':status': 304 })
    return false // Cancela a operação de envio
  }
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck })
})

O campo de cabeçalho content-length será definido automaticamente.

As opções offset e length podem ser usadas para limitar a resposta a um subconjunto de intervalo específico. Isso pode ser usado, por exemplo, para suportar solicitações de intervalo HTTP.

A função options.onError também pode ser usada para tratar todos os erros que podem acontecer antes que a entrega do arquivo seja iniciada. O comportamento padrão é destruir o fluxo.

Quando a opção options.waitForTrailers é definida, o evento 'wantTrailers' será emitido imediatamente após o enfileiramento do último bloco de dados de carga útil a ser enviado. O método http2stream.sendTrailers() pode então ser usado para enviar campos de cabeçalho de rastreamento ao peer.

Quando options.waitForTrailers é definido, o Http2Stream não será fechado automaticamente quando o último frame DATA for transmitido. O código do usuário deve chamar http2stream.sendTrailers() ou http2stream.close() para fechar o Http2Stream.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'algum valor a ser enviado' })
  })
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'algum valor a ser enviado' })
  })
})

Classe: Http2Server

Adicionado em: v8.4.0

• Extende: <net.Server>

Instâncias de Http2Server são criadas usando a função http2.createServer(). A classe Http2Server não é exportada diretamente pelo módulo node:http2.

Evento: 'checkContinue'

Adicionado em: v8.5.0

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

Se um listener 'request' é registrado ou http2.createServer() recebe uma função de callback, o evento 'checkContinue' é emitido cada vez que uma requisição com um HTTP Expect: 100-continue é recebida. Se este evento não for escutado, o servidor responderá automaticamente com o status 100 Continue como 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 (ex: 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: 'connection'

Adicionado em: v8.4.0

• socket <stream.Duplex>

Este evento é emitido quando um novo fluxo TCP é estabelecido. socket é tipicamente um objeto do tipo net.Socket. Normalmente, os usuários não vão querer acessar este evento.

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

Evento: 'request'

Adicionado em: v8.4.0

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

Emitido cada vez que há uma requisição. Pode haver várias requisições por sessão. Veja a API de Compatibilidade.

Evento: 'session'

Adicionado em: v8.4.0

• session <ServerHttp2Session>

O evento 'session' é emitido quando uma nova Http2Session é criada pelo Http2Server.

Evento: 'sessionError'

Adicionado em: v8.4.0

• error <Error>
• session <ServerHttp2Session>

O evento 'sessionError' é emitido quando um evento 'error' é emitido por um objeto Http2Session associado ao Http2Server.

Evento: 'stream'

Adicionado em: v8.4.0

• stream <Http2Stream> Uma referência ao fluxo
• headers <Objeto de Cabeçalhos HTTP/2> Um objeto descrevendo os cabeçalhos
• flags <number> As flags numéricas associadas
• rawHeaders <Array> Um array contendo os nomes dos cabeçalhos brutos seguidos por seus respectivos valores.

O evento 'stream' é emitido quando um evento 'stream' foi emitido por uma Http2Session associada ao servidor.

Veja também o evento 'stream' de Http2Session.

ESM

import { createServer, constants } from 'node:http2'
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = constants

const server = createServer()
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD]
  const path = headers[HTTP2_HEADER_PATH]
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

CJS

const http2 = require('node:http2')
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = http2.constants

const server = http2.createServer()
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD]
  const path = headers[HTTP2_HEADER_PATH]
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

Evento: 'timeout'

[Histórico]

Versão	Mudanças
v13.0.0	O timeout padrão mudou de 120s para 0 (sem timeout).
v8.4.0	Adicionado em: v8.4.0

O evento 'timeout' é emitido quando não há atividade no Servidor por um determinado número de milissegundos definido usando http2server.setTimeout(). Padrão: 0 (sem timeout)

server.close([callback])

Adicionado em: v8.4.0

• callback <Function>

Impede que o servidor estabeleça novas sessões. Isso não impede que novos fluxos de solicitação sejam criados devido à natureza persistente das sessões HTTP/2. Para desligar o servidor corretamente, chame http2session.close() em todas as sessões ativas.

Se callback for fornecido, ele não será invocado até que todas as sessões ativas tenham sido fechadas, embora o servidor já tenha parado de permitir novas sessões. Consulte net.Server.close() para obter mais detalhes.

server[Symbol.asyncDispose]()

Adicionado em: v20.4.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

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

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v13.0.0	O timeout padrão mudou de 120s para 0 (sem timeout).
v8.4.0	Adicionado em: v8.4.0

• msecs <number> Padrão: 0 (sem timeout)
• callback <Function>
• Retorna: <Http2Server>

Usado para definir o valor de timeout para solicitações do servidor http2 e define uma função de callback que é chamada quando não há atividade no Http2Server após msecs milissegundos.

O callback fornecido é registrado como um listener no evento 'timeout'.

Caso callback não seja uma função, um novo erro ERR_INVALID_ARG_TYPE será lançado.

server.timeout

[Histórico]

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

• <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 desativará 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 conexões existentes.

server.updateSettings([settings])

Adicionado em: v15.1.0, v14.17.0

• settings <Objeto de Configurações HTTP/2>

Usado para atualizar o servidor com as configurações fornecidas.

Lança ERR_HTTP2_INVALID_SETTING_VALUE para valores de settings inválidos.

Lança ERR_INVALID_ARG_TYPE para argumento de settings inválido.

Classe: Http2SecureServer

Adicionado em: v8.4.0

• Estende: <tls.Server>

Instâncias de Http2SecureServer são criadas usando a função http2.createSecureServer(). A classe Http2SecureServer não é exportada diretamente pelo módulo node:http2.

Evento: 'checkContinue'

Adicionado em: v8.5.0

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

Se um listener 'request' estiver registrado ou http2.createSecureServer() receber uma função de retorno de chamada, o evento 'checkContinue' é emitido sempre que uma requisição com um HTTP Expect: 100-continue é recebida. Se este evento não for ouvido, o servidor responderá automaticamente com um status 100 Continue, conforme apropriado.

O tratamento desse 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: 'connection'

Adicionado em: v8.4.0

• socket <stream.Duplex>

Este evento é emitido quando um novo fluxo TCP é estabelecido, antes que o handshake TLS comece. socket é tipicamente um objeto do tipo net.Socket. Normalmente, os usuários não desejam acessar este evento.

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

Evento: 'request'

Adicionado em: v8.4.0

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

Emitido cada vez que há uma solicitação. Pode haver várias solicitações por sessão. Veja a API de Compatibilidade.

Evento: 'session'

Adicionado em: v8.4.0

• session <ServerHttp2Session>

O evento 'session' é emitido quando uma nova Http2Session é criada pelo Http2SecureServer.

Evento: 'sessionError'

Adicionado em: v8.4.0

• error <Error>
• session <ServerHttp2Session>

O evento 'sessionError' é emitido quando um evento 'error' é emitido por um objeto Http2Session associado ao Http2SecureServer.

Evento: 'stream'

Adicionado em: v8.4.0

• stream <Http2Stream> Uma referência ao fluxo
• headers <Objeto de Cabeçalhos HTTP/2> Um objeto descrevendo os cabeçalhos
• flags <number> As flags numéricas associadas
• rawHeaders <Array> Um array contendo os nomes de cabeçalho brutos seguidos por seus respectivos valores.

O evento 'stream' é emitido quando um evento 'stream' foi emitido por um Http2Session associado ao servidor.

Veja também o evento 'stream' de Http2Session.

ESM

import { createSecureServer, constants } from 'node:http2'
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = constants

const options = getOptionsSomehow()

const server = createSecureServer(options)
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD]
  const path = headers[HTTP2_HEADER_PATH]
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

CJS

const http2 = require('node:http2')
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = http2.constants

const options = getOptionsSomehow()

const server = http2.createSecureServer(options)
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD]
  const path = headers[HTTP2_HEADER_PATH]
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

Evento: 'timeout'

Adicionado em: v8.4.0

O evento 'timeout' é emitido quando não há atividade no Servidor por um determinado número de milissegundos definido usando http2secureServer.setTimeout(). Padrão: 2 minutos.

Evento: 'unknownProtocol'

[Histórico]

Versão	Mudanças
v19.0.0	Este evento só será emitido se o cliente não transmitir uma extensão ALPN durante o handshake TLS.
v8.4.0	Adicionado em: v8.4.0

• socket <stream.Duplex>

O evento 'unknownProtocol' é emitido quando um cliente que se conecta não consegue negociar um protocolo permitido (ou seja, HTTP/2 ou HTTP/1.1). O manipulador de eventos recebe o socket para tratamento. Se nenhum listener for registrado para este evento, a conexão é encerrada. Um timeout pode ser especificado usando a opção 'unknownProtocolTimeout' passada para http2.createSecureServer().

Em versões anteriores do Node.js, este evento seria emitido se allowHTTP1 fosse false e, durante o handshake TLS, o cliente não enviasse uma extensão ALPN ou enviasse uma extensão ALPN que não incluísse HTTP/2 (h2). Versões mais recentes do Node.js só emitem este evento se allowHTTP1 for false e o cliente não enviar uma extensão ALPN. Se o cliente enviar uma extensão ALPN que não inclua HTTP/2 (ou HTTP/1.1 se allowHTTP1 for true), o handshake TLS falhará e nenhuma conexão segura será estabelecida.

Veja a API de Compatibilidade.

server.close([callback])

Adicionado em: v8.4.0

• callback <Function>

Impede que o servidor estabeleça novas sessões. Isso não impede que novos fluxos de solicitação sejam criados devido à natureza persistente das sessões HTTP/2. Para desligar o servidor corretamente, chame http2session.close() em todas as sessões ativas.

Se callback for fornecido, ele não é invocado até que todas as sessões ativas tenham sido fechadas, embora o servidor já tenha parado de permitir novas sessões. Veja tls.Server.close() para mais detalhes.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.4.0	Adicionado em: v8.4.0

• msecs <number> Padrão: 120000 (2 minutos)
• callback <Function>
• Retorna: <Http2SecureServer>

Usado para definir o valor de tempo limite para solicitações de servidor seguro http2, e define uma função de callback que é chamada quando não há atividade no Http2SecureServer após msecs milissegundos.

O callback fornecido é registrado como um listener no evento 'timeout'.

Caso callback não seja uma função, um novo erro ERR_INVALID_ARG_TYPE será lançado.

server.timeout

[Histórico]

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

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

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

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

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

server.updateSettings([settings])

Adicionado em: v15.1.0, v14.17.0

• settings <Objeto de Configurações HTTP/2>

Usado para atualizar o servidor com as configurações fornecidas.

Lança ERR_HTTP2_INVALID_SETTING_VALUE para valores de settings inválidos.

Lança ERR_INVALID_ARG_TYPE para argumento settings inválido.

http2.createServer([options][, onRequestHandler])

[Histórico]

Versão	Mudanças
v23.0.0	Adicionado streamResetBurst e streamResetRate.
v13.0.0	O PADDING_STRATEGY_CALLBACK foi tornado equivalente a fornecer PADDING_STRATEGY_ALIGNED e selectPadding foi removido.
v13.3.0, v12.16.0	Adicionado a opção maxSessionRejectedStreams com um padrão de 100.
v13.3.0, v12.16.0	Adicionado a opção maxSessionInvalidFrames com um padrão de 1000.
v12.4.0	O parâmetro options agora suporta opções net.createServer().
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Adicionado a opção unknownProtocolTimeout com um padrão de 10000.
v14.4.0, v12.18.0, v10.21.0	Adicionado a opção maxSettings com um padrão de 32.
v9.6.0	Adicionado a opção Http1IncomingMessage e Http1ServerResponse.
v8.9.3	Adicionado a opção maxOutstandingPings com um limite padrão de 10.
v8.9.3	Adicionado a opção maxHeaderListPairs com um limite padrão de 128 pares de cabeçalho.
v8.4.0	Adicionado em: v8.4.0

• options <Object>

  • maxDeflateDynamicTableSize <number> Define o tamanho máximo da tabela dinâmica para descompactar campos de cabeçalho. Padrão: 4Kib.

  • maxSettings <number> Define o número máximo de entradas de configurações por frame SETTINGS. O valor mínimo permitido é 1. Padrão: 32.

  • maxSessionMemory <number> Define a memória máxima que a Http2Session está permitida a usar. O valor é expresso em termos de número de megabytes, por exemplo, 1 igual a 1 megabyte. O valor mínimo permitido é 1. Este é um limite baseado em crédito, Http2Streams existentes podem fazer com que este limite seja excedido, mas novas instâncias Http2Stream serão rejeitadas enquanto este limite for excedido. O número atual de sessões Http2Stream, o uso de memória atual das tabelas de compressão de cabeçalho, os dados atuais enfileirados para serem enviados e os frames PING e SETTINGS não reconhecidos são todos contados para o limite atual. Padrão: 10.

  • maxHeaderListPairs <number> Define o número máximo de entradas de cabeçalho. Isso é semelhante a server.maxHeadersCount ou request.maxHeadersCount no módulo node:http. O valor mínimo é 4. Padrão: 128.

  • maxOutstandingPings <number> Define o número máximo de pings pendentes e não reconhecidos. Padrão: 10.

  • maxSendHeaderBlockLength <number> Define o tamanho máximo permitido para um bloco de cabeçalhos serializado e compactado. Tentativas de enviar cabeçalhos que excedam este limite resultarão em um evento 'frameError' sendo emitido e o stream sendo fechado e destruído. Embora isso defina o tamanho máximo permitido para todo o bloco de cabeçalhos, nghttp2 (a biblioteca interna http2) tem um limite de 65536 para cada par chave/valor descompactado.

  • paddingStrategy <number> A estratégia usada para determinar a quantidade de preenchimento a ser usada para os frames HEADERS e DATA. Padrão: http2.constants.PADDING_STRATEGY_NONE. O valor pode ser um de:

  • http2.constants.PADDING_STRATEGY_NONE: Nenhum preenchimento é aplicado.

  • http2.constants.PADDING_STRATEGY_MAX: A quantidade máxima de preenchimento, determinada pela implementação interna, é aplicada.

  • http2.constants.PADDING_STRATEGY_ALIGNED: Tenta aplicar preenchimento suficiente para garantir que o comprimento total do frame, incluindo o cabeçalho de 9 bytes, seja um múltiplo de 8. Para cada frame, há um número máximo permitido de bytes de preenchimento que é determinado pelo estado e configurações de controle de fluxo atuais. Se este máximo for menor que a quantidade calculada necessária para garantir o alinhamento, o máximo é usado e o comprimento total do frame não é necessariamente alinhado em 8 bytes.

  • peerMaxConcurrentStreams <number> Define o número máximo de streams simultâneos para o peer remoto como se um frame SETTINGS tivesse sido recebido. Será substituído se o peer remoto definir seu próprio valor para maxConcurrentStreams. Padrão: 100.

  • maxSessionInvalidFrames <integer> Define o número máximo de frames inválidos que serão tolerados antes que a sessão seja fechada. Padrão: 1000.

  • maxSessionRejectedStreams <integer> Define o número máximo de streams rejeitados na criação que serão tolerados antes que a sessão seja fechada. Cada rejeição está associada a um erro NGHTTP2_ENHANCE_YOUR_CALM que deve informar ao peer para não abrir mais streams, continuar a abrir streams é, portanto, considerado um sinal de um peer com comportamento inadequado. Padrão: 100.

  • settings <Objeto de Configurações HTTP/2> As configurações iniciais a serem enviadas ao peer remoto após a conexão.

  • streamResetBurst <number> e streamResetRate <number> Define o limite de taxa para a redefinição de stream de entrada (frame RST_STREAM). Ambas as configurações devem ser definidas para ter qualquer efeito, e o padrão é 1000 e 33, respectivamente.

  • remoteCustomSettings <Array> O array de valores inteiros determina os tipos de configurações, que são incluídos na propriedade CustomSettings das remoteSettings recebidas. Consulte a propriedade CustomSettings do objeto Http2Settings para obter mais informações sobre os tipos de configurações permitidos.

  • Http1IncomingMessage <http.IncomingMessage> Especifica a classe IncomingMessage a ser usada para fallback HTTP/1. Útil para estender o http.IncomingMessage original. Padrão: http.IncomingMessage.

  • Http1ServerResponse <http.ServerResponse> Especifica a classe ServerResponse a ser usada para fallback HTTP/1. Útil para estender o http.ServerResponse original. Padrão: http.ServerResponse.

  • Http2ServerRequest <http2.Http2ServerRequest> Especifica a classe Http2ServerRequest a ser usada. Útil para estender o Http2ServerRequest original. Padrão: Http2ServerRequest.

  • Http2ServerResponse <http2.Http2ServerResponse> Especifica a classe Http2ServerResponse a ser usada. Útil para estender o Http2ServerResponse original. Padrão: Http2ServerResponse.

  • unknownProtocolTimeout <number> Especifica um tempo limite em milissegundos que um servidor deve esperar quando um 'unknownProtocol' é emitido. Se o socket não tiver sido destruído nesse tempo, o servidor o destruirá. Padrão: 10000.

  • ...: Qualquer opção net.createServer() pode ser fornecida.

• onRequestHandler <Function> Consulte API de Compatibilidade

• Retorna: <Http2Server>

Retorna uma instância net.Server que cria e gerencia instâncias Http2Session.

Como não há navegadores conhecidos que suportem HTTP/2 não criptografado, o uso de http2.createSecureServer() é necessário ao se comunicar com clientes de navegador.

ESM

import { createServer } from 'node:http2'

// Cria um servidor HTTP/2 não criptografado.
// Como não há navegadores conhecidos que suportem
// HTTP/2 não criptografado, o uso de `createSecureServer()`
// é necessário ao se comunicar com clientes de navegador.
const server = createServer()

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Olá Mundo</h1>')
})

server.listen(8000)

CJS

const http2 = require('node:http2')

// Cria um servidor HTTP/2 não criptografado.
// Como não há navegadores conhecidos que suportem
// HTTP/2 não criptografado, o uso de `http2.createSecureServer()`
// é necessário ao se comunicar com clientes de navegador.
const server = http2.createServer()

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Olá Mundo</h1>')
})

server.listen(8000)

http2.createSecureServer(options[, onRequestHandler])

[Histórico]

Versão	Mudanças
v13.0.0	O PADDING_STRATEGY_CALLBACK foi tornado equivalente a fornecer PADDING_STRATEGY_ALIGNED e selectPadding foi removido.
v13.3.0, v12.16.0	Adicionada a opção maxSessionRejectedStreams com um valor padrão de 100.
v13.3.0, v12.16.0	Adicionada a opção maxSessionInvalidFrames com um valor padrão de 1000.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Adicionada a opção unknownProtocolTimeout com um valor padrão de 10000.
v14.4.0, v12.18.0, v10.21.0	Adicionada a opção maxSettings com um valor padrão de 32.
v10.12.0	Adicionada a opção origins para enviar automaticamente um quadro ORIGIN na inicialização da Http2Session.
v8.9.3	Adicionada a opção maxOutstandingPings com um limite padrão de 10.
v8.9.3	Adicionada a opção maxHeaderListPairs com um limite padrão de 128 pares de cabeçalho.
v8.4.0	Adicionado em: v8.4.0

• options <Objeto>

  • allowHTTP1 <boolean> As conexões de cliente de entrada que não suportam HTTP/2 serão rebaixadas para HTTP/1.x quando definido como true. Veja o evento 'unknownProtocol'. Veja negociação ALPN. Padrão: false.

  • maxDeflateDynamicTableSize <number> Define o tamanho máximo da tabela dinâmica para desinflar campos de cabeçalho. Padrão: 4Kib.

  • maxSettings <number> Define o número máximo de entradas de configurações por quadro SETTINGS. O valor mínimo permitido é 1. Padrão: 32.

  • maxSessionMemory<number> Define a memória máxima que a Http2Session tem permissão para usar. O valor é expresso em termos de número de megabytes, por exemplo, 1 igual a 1 megabyte. O valor mínimo permitido é 1. Este é um limite baseado em crédito, Http2Streams existentes podem fazer com que esse limite seja excedido, mas novas instâncias de Http2Stream serão rejeitadas enquanto esse limite for excedido. O número atual de sessões Http2Stream, o uso atual de memória das tabelas de compactação de cabeçalho, os dados atuais enfileirados para serem enviados e os quadros PING e SETTINGS não reconhecidos são todos contados para o limite atual. Padrão: 10.

  • maxHeaderListPairs <number> Define o número máximo de entradas de cabeçalho. Isso é semelhante a server.maxHeadersCount ou request.maxHeadersCount no módulo node:http. O valor mínimo é 4. Padrão: 128.

  • maxOutstandingPings <number> Define o número máximo de pings pendentes e não reconhecidos. Padrão: 10.

  • maxSendHeaderBlockLength <number> Define o tamanho máximo permitido para um bloco de cabeçalhos serializado e compactado. As tentativas de enviar cabeçalhos que excedam esse limite resultarão na emissão de um evento 'frameError' e no fechamento e destruição do fluxo.

  • paddingStrategy <number> Estratégia usada para determinar a quantidade de preenchimento a ser usada para quadros HEADERS e DATA. Padrão: http2.constants.PADDING_STRATEGY_NONE. O valor pode ser um dos seguintes:

    • http2.constants.PADDING_STRATEGY_NONE: Nenhum preenchimento é aplicado.
    • http2.constants.PADDING_STRATEGY_MAX: A quantidade máxima de preenchimento, determinada pela implementação interna, é aplicada.
    • http2.constants.PADDING_STRATEGY_ALIGNED: Tenta aplicar preenchimento suficiente para garantir que o comprimento total do quadro, incluindo o cabeçalho de 9 bytes, seja um múltiplo de 8. Para cada quadro, há um número máximo permitido de bytes de preenchimento que é determinado pelo estado atual de controle de fluxo e configurações. Se esse máximo for menor do que a quantidade calculada necessária para garantir o alinhamento, o máximo é usado e o comprimento total do quadro não é necessariamente alinhado em 8 bytes.

  • peerMaxConcurrentStreams <number> Define o número máximo de fluxos simultâneos para o peer remoto como se um quadro SETTINGS tivesse sido recebido. Será substituído se o peer remoto definir seu próprio valor para maxConcurrentStreams. Padrão: 100.

  • maxSessionInvalidFrames <integer> Define o número máximo de quadros inválidos que serão tolerados antes do fechamento da sessão. Padrão: 1000.

  • maxSessionRejectedStreams <integer> Define o número máximo de fluxos rejeitados na criação que serão tolerados antes do fechamento da sessão. Cada rejeição está associada a um erro NGHTTP2_ENHANCE_YOUR_CALM que deve dizer ao peer para não abrir mais fluxos, continuar a abrir fluxos é, portanto, considerado um sinal de um peer com comportamento incorreto. Padrão: 100.

  • settings <Objeto de configurações HTTP/2> As configurações iniciais para enviar ao peer remoto após a conexão.

  • remoteCustomSettings <Array> A array de valores inteiros determina os tipos de configurações, que estão incluídos na propriedade customSettings do remoteSettings recebido. Consulte a propriedade customSettings do objeto Http2Settings para obter mais informações sobre os tipos de configuração permitidos.

  • ...: Quaisquer opções tls.createServer() podem ser fornecidas. Para servidores, as opções de identidade (pfx ou key/cert) são geralmente necessárias.

  • origins <string[]> Uma array de strings de origem para enviar dentro de um quadro ORIGIN imediatamente após a criação de uma nova Http2Session de servidor.

  • unknownProtocolTimeout <number> Especifica um tempo limite em milissegundos que um servidor deve esperar quando um evento 'unknownProtocol' é emitido. Se o socket não foi destruído até aquele momento, o servidor irá destruí-lo. Padrão: 10000.

• onRequestHandler <Função> Veja API de compatibilidade

• Retorna: <Http2SecureServer>

Retorna uma instância tls.Server que cria e gerencia instâncias Http2Session.

ESM

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),
}

// Criar um servidor HTTP/2 seguro
const server = createSecureServer(options)

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Olá Mundo</h1>')
})

server.listen(8443)

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
}

// Criar um servidor HTTP/2 seguro
const server = http2.createSecureServer(options)

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Olá Mundo</h1>')
})

server.listen(8443)

http2.connect(authority[, options][, listener])

[Histórico]

Versão	Mudanças
v13.0.0	O PADDING_STRATEGY_CALLBACK foi tornado equivalente a fornecer PADDING_STRATEGY_ALIGNED e selectPadding foi removido.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Adicionada a opção unknownProtocolTimeout com o padrão de 10000.
v14.4.0, v12.18.0, v10.21.0	Adicionada a opção maxSettings com o padrão de 32.
v8.9.3	Adicionada a opção maxOutstandingPings com um limite padrão de 10.
v8.9.3	Adicionada a opção maxHeaderListPairs com um limite padrão de 128 pares de cabeçalho.
v8.4.0	Adicionado em: v8.4.0

• authority <string> | <URL> O servidor HTTP/2 remoto ao qual se conectar. Este deve estar na forma de um URL mínimo e válido com o prefixo http:// ou https://, nome do host e porta IP (se uma porta não padrão for usada). Userinfo (ID do usuário e senha), caminho, querystring e detalhes de fragmento no URL serão ignorados.

• options <Object>

  • maxDeflateDynamicTableSize <number> Define o tamanho máximo da tabela dinâmica para desinflar campos de cabeçalho. Padrão: 4Kib.
  • maxSettings <number> Define o número máximo de entradas de configurações por quadro SETTINGS. O valor mínimo permitido é 1. Padrão: 32.
  • maxSessionMemory <number> Define a memória máxima que a Http2Session tem permissão para usar. O valor é expresso em termos de número de megabytes, por exemplo, 1 é igual a 1 megabyte. O valor mínimo permitido é 1. Este é um limite baseado em crédito, Http2Streams existentes podem fazer com que esse limite seja excedido, mas novas instâncias de Http2Stream serão rejeitadas enquanto esse limite for excedido. O número atual de sessões de Http2Stream, o uso atual de memória das tabelas de compactação de cabeçalho, os dados atuais enfileirados para serem enviados e os quadros PING e SETTINGS não reconhecidos são todos contados para o limite atual. Padrão: 10.
  • maxHeaderListPairs <number> Define o número máximo de entradas de cabeçalho. Isso é semelhante a server.maxHeadersCount ou request.maxHeadersCount no módulo node:http. O valor mínimo é 1. Padrão: 128.
  • maxOutstandingPings <number> Define o número máximo de pings pendentes e não reconhecidos. Padrão: 10.
  • maxReservedRemoteStreams <number> Define o número máximo de fluxos de push reservados que o cliente aceitará a qualquer momento. Assim que o número atual de fluxos de push reservados exceder esse limite, novos fluxos de push enviados pelo servidor serão automaticamente rejeitados. O valor mínimo permitido é 0. O valor máximo permitido é 2-1. Um valor negativo define esta opção para o valor máximo permitido. Padrão: 200.
  • maxSendHeaderBlockLength <number> Define o tamanho máximo permitido para um bloco de cabeçalhos serializado e compactado. Tentativas de enviar cabeçalhos que excedam este limite resultarão em um evento 'frameError' sendo emitido e o fluxo sendo fechado e destruído.
  • paddingStrategy <number> Estratégia usada para determinar a quantidade de padding a ser usada para quadros HEADERS e DATA. Padrão: http2.constants.PADDING_STRATEGY_NONE. O valor pode ser um de:
    • http2.constants.PADDING_STRATEGY_NONE: Nenhum padding é aplicado.
    • http2.constants.PADDING_STRATEGY_MAX: A quantidade máxima de padding, determinada pela implementação interna, é aplicada.
    • http2.constants.PADDING_STRATEGY_ALIGNED: Tenta aplicar padding suficiente para garantir que o comprimento total do quadro, incluindo o cabeçalho de 9 bytes, seja um múltiplo de 8. Para cada quadro, há um número máximo permitido de bytes de padding que é determinado pelo estado e configurações atuais do controle de fluxo. Se este máximo for menor que a quantidade calculada necessária para garantir o alinhamento, o máximo será usado e o comprimento total do quadro não será necessariamente alinhado em 8 bytes.
  • peerMaxConcurrentStreams <number> Define o número máximo de fluxos simultâneos para o par remoto como se um quadro SETTINGS tivesse sido recebido. Será substituído se o par remoto definir seu próprio valor para maxConcurrentStreams. Padrão: 100.
  • protocol <string> O protocolo para se conectar, se não definido na authority. O valor pode ser 'http:' ou 'https:'. Padrão: 'https:'
  • settings <Objeto de Configurações HTTP/2> As configurações iniciais para enviar para o par remoto após a conexão.
  • remoteCustomSettings <Array> O array de valores inteiros determina os tipos de configurações, que são incluídos na propriedade CustomSettings do remoteSettings recebido. Consulte a propriedade CustomSettings do objeto Http2Settings para obter mais informações sobre os tipos de configurações permitidos.
  • createConnection <Function> Um retorno de chamada opcional que recebe a instância URL passada para connect e o objeto options, e retorna qualquer fluxo Duplex que será usado como conexão para esta sessão.
  • ...: Quaisquer opções net.connect() ou tls.connect() podem ser fornecidas.
  • unknownProtocolTimeout <number> Especifica um tempo limite em milissegundos que um servidor deve esperar quando um evento 'unknownProtocol' é emitido. Se o socket não tiver sido destruído até esse momento, o servidor o destruirá. Padrão: 10000.

• listener <Function> Será registrado como um ouvinte único do evento 'connect'.

• Retorna: <ClientHttp2Session>

Retorna uma instância ClientHttp2Session.

ESM

import { connect } from 'node:http2'
const client = connect('https://localhost:1234')

/* Use o cliente */

client.close()

CJS

const http2 = require('node:http2')
const client = http2.connect('https://localhost:1234')

/* Use o cliente */

client.close()

http2.constants

Adicionado em: v8.4.0

Códigos de erro para RST_STREAM e GOAWAY

Valor	Nome	Constante
0x00	Sem Erro	http2.constants.NGHTTP2_NO_ERROR
0x01	Erro de Protocolo	http2.constants.NGHTTP2_PROTOCOL_ERROR
0x02	Erro Interno	http2.constants.NGHTTP2_INTERNAL_ERROR
0x03	Erro de Controle de Fluxo	http2.constants.NGHTTP2_FLOW_CONTROL_ERROR
0x04	Tempo Limite das Configurações	http2.constants.NGHTTP2_SETTINGS_TIMEOUT
0x05	Stream Fechado	http2.constants.NGHTTP2_STREAM_CLOSED
0x06	Erro de Tamanho do Frame	http2.constants.NGHTTP2_FRAME_SIZE_ERROR
0x07	Stream Recusado	http2.constants.NGHTTP2_REFUSED_STREAM
0x08	Cancelar	http2.constants.NGHTTP2_CANCEL
0x09	Erro de Compressão	http2.constants.NGHTTP2_COMPRESSION_ERROR
0x0a	Erro de Conexão	http2.constants.NGHTTP2_CONNECT_ERROR
0x0b	Acalme-se	http2.constants.NGHTTP2_ENHANCE_YOUR_CALM
0x0c	Segurança Inadequada	http2.constants.NGHTTP2_INADEQUATE_SECURITY
0x0d	HTTP/1.1 Requerido	http2.constants.NGHTTP2_HTTP_1_1_REQUIRED

O evento 'timeout' é emitido quando não há atividade no Servidor por um determinado número de milissegundos definido usando http2server.setTimeout().

http2.getDefaultSettings()

Adicionado em: v8.4.0

• Retorna: <Objeto de Configurações HTTP/2>

Retorna um objeto contendo as configurações padrão para uma instância Http2Session. Este método retorna uma nova instância de objeto cada vez que é chamado, portanto, as instâncias retornadas podem ser modificadas com segurança para uso.

http2.getPackedSettings([settings])

Adicionado em: v8.4.0

• settings <Objeto de Configurações HTTP/2>
• Retorna: <Buffer>

Retorna uma instância de Buffer contendo a representação serializada das configurações HTTP/2 fornecidas, conforme especificado na especificação HTTP/2. Isso é destinado ao uso com o campo de cabeçalho HTTP2-Settings.

ESM

import { getPackedSettings } from 'node:http2'

const packed = getPackedSettings({ enablePush: false })

console.log(packed.toString('base64'))
// Imprime: AAIAAAAA

CJS

const http2 = require('node:http2')

const packed = http2.getPackedSettings({ enablePush: false })

console.log(packed.toString('base64'))
// Imprime: AAIAAAAA

http2.getUnpackedSettings(buf)

Adicionado em: v8.4.0

• buf <Buffer> | <TypedArray> As configurações compactadas.
• Retorna: <Objeto de Configurações HTTP/2>

Retorna um Objeto de Configurações HTTP/2 contendo as configurações desserializadas do Buffer fornecido, conforme gerado por http2.getPackedSettings().

http2.performServerHandshake(socket[, options])

Adicionado em: v21.7.0, v20.12.0

• socket <stream.Duplex>

• options <Objeto>

  • ...: Qualquer opção de http2.createServer() pode ser fornecida.

• Retorna: <ServerHttp2Session>

Cria uma sessão de servidor HTTP/2 a partir de um socket existente.

http2.sensitiveHeaders

Adicionado em: v15.0.0, v14.18.0

• <symbol>

Este símbolo pode ser definido como uma propriedade no objeto de cabeçalhos HTTP/2 com um valor de array para fornecer uma lista de cabeçalhos considerados sensíveis. Consulte Cabeçalhos Sensíveis para mais detalhes.

Objeto de Cabeçalhos

Os cabeçalhos são representados como propriedades próprias em objetos JavaScript. As chaves de propriedade serão serializadas em letras minúsculas. Os valores de propriedade devem ser strings (se não forem, serão convertidos em strings) ou um Array de strings (para enviar mais de um valor por campo de cabeçalho).

const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  ABC: ['has', 'more', 'than', 'one', 'value'],
}

stream.respond(headers)

Os objetos de cabeçalho passados para as funções de retorno de chamada terão um protótipo null. Isso significa que os métodos normais de objetos JavaScript, como Object.prototype.toString() e Object.prototype.hasOwnProperty(), não funcionarão.

Para cabeçalhos de entrada:

• O cabeçalho :status é convertido em number.
• Duplicatas de :status, :method, :authority, :scheme, :path, :protocol, age, authorization, access-control-allow-credentials, access-control-max-age, access-control-request-method, content-encoding, content-language, content-length, content-location, content-md5, content-range, content-type, date, dnt, etag, expires, from, host, if-match, if-modified-since, if-none-match, if-range, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, range, referer,retry-after, tk, upgrade-insecure-requests, user-agent ou x-content-type-options são descartados.
• 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 ', '.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', (stream, headers) => {
  console.log(headers[':path'])
  console.log(headers.ABC)
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', (stream, headers) => {
  console.log(headers[':path'])
  console.log(headers.ABC)
})

Cabeçalhos sensíveis

Os cabeçalhos HTTP2 podem ser marcados como sensíveis, o que significa que o algoritmo de compressão de cabeçalhos HTTP/2 nunca os indexará. Isso pode fazer sentido para valores de cabeçalho com baixa entropia e que podem ser considerados valiosos para um invasor, por exemplo, Cookie ou Authorization. Para conseguir isso, adicione o nome do cabeçalho à propriedade [http2.sensitiveHeaders] como um array:

const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  cookie: 'some-cookie',
  'other-sensitive-header': 'very secret data',
  [http2.sensitiveHeaders]: ['cookie', 'other-sensitive-header'],
}

stream.respond(headers)

Para alguns cabeçalhos, como Authorization e cabeçalhos Cookie curtos, esta flag é definida automaticamente.

Esta propriedade também é definida para os cabeçalhos recebidos. Ela conterá os nomes de todos os cabeçalhos marcados como sensíveis, incluindo aqueles marcados dessa forma automaticamente.

Objeto de configurações

[Histórico]

Versão	Mudanças
v12.12.0	A configuração maxConcurrentStreams é mais restritiva.
v8.9.3	A configuração maxHeaderListSize agora é rigorosamente imposta.
v8.4.0	Adicionado em: v8.4.0

As APIs http2.getDefaultSettings(), http2.getPackedSettings(), http2.createServer(), http2.createSecureServer(), http2session.settings(), http2session.localSettings e http2session.remoteSettings retornam ou recebem como entrada um objeto que define as configurações para um objeto Http2Session. Esses objetos são objetos JavaScript comuns que contêm as seguintes propriedades.

• headerTableSize <number> Especifica o número máximo de bytes usados para compressão de cabeçalho. O valor mínimo permitido é 0. O valor máximo permitido é 2-1. Padrão: 4096.
• enablePush <boolean> Especifica true se os HTTP/2 Push Streams devem ser permitidos nas instâncias Http2Session. Padrão: true.
• initialWindowSize <number> Especifica o tamanho da janela inicial do remetente em bytes para o controle de fluxo em nível de stream. O valor mínimo permitido é 0. O valor máximo permitido é 2-1. Padrão: 65535.
• maxFrameSize <number> Especifica o tamanho em bytes do maior payload de frame. O valor mínimo permitido é 16.384. O valor máximo permitido é 2-1. Padrão: 16384.
• maxConcurrentStreams <number> Especifica o número máximo de streams simultâneos permitidos em uma Http2Session. Não há valor padrão, o que implica que, pelo menos teoricamente, 2-1 streams podem ser abertos simultaneamente a qualquer momento em uma Http2Session. O valor mínimo é 0. O valor máximo permitido é 2-1. Padrão: 4294967295.
• maxHeaderListSize <number> Especifica o tamanho máximo (octetos não comprimidos) da lista de cabeçalhos que será aceita. O valor mínimo permitido é 0. O valor máximo permitido é 2-1. Padrão: 65535.
• maxHeaderSize <number> Alias para maxHeaderListSize.
• enableConnectProtocol<boolean> Especifica true se o "Extended Connect Protocol" definido por RFC 8441 deve ser habilitado. Esta configuração só faz sentido se enviada pelo servidor. Depois que a configuração enableConnectProtocol for habilitada para uma determinada Http2Session, ela não poderá ser desabilitada. Padrão: false.
• customSettings <Object> Especifica configurações adicionais, ainda não implementadas no node e nas bibliotecas subjacentes. A chave do objeto define o valor numérico do tipo de configuração (conforme definido no registro "HTTP/2 SETTINGS" estabelecido por [RFC 7540]) e os valores o valor numérico real das configurações. O tipo de configuração deve ser um inteiro no intervalo de 1 a 2^16-1. Não deve ser um tipo de configuração já tratado pelo node, ou seja, atualmente deve ser maior que 6, embora não seja um erro. Os valores precisam ser inteiros não assinados no intervalo de 0 a 2^32-1. Atualmente, um máximo de até 10 configurações personalizadas é suportado. Ele é suportado apenas para o envio de SETTINGS ou para o recebimento de valores de configuração especificados nas opções remoteCustomSettings do objeto servidor ou cliente. Não misture o mecanismo customSettings para um ID de configurações com interfaces para as configurações tratadas nativamente, caso uma configuração se torne suportada nativamente em uma futura versão do node.

Todas as propriedades adicionais no objeto de configurações são ignoradas.

Tratamento de erros

Existem vários tipos de condições de erro que podem surgir ao usar o módulo node:http2:

Erros de validação ocorrem quando um argumento, opção ou valor de configuração incorreto é passado. Eles sempre serão reportados por um throw síncrono.

Erros de estado ocorrem quando uma ação é tentada em um momento incorreto (por exemplo, tentar enviar dados em um fluxo depois que ele foi fechado). Eles serão relatados usando um throw síncrono ou através de um evento 'error' nos objetos Http2Stream, Http2Session ou Servidor HTTP/2, dependendo de onde e quando o erro ocorre.

Erros internos ocorrem quando uma sessão HTTP/2 falha inesperadamente. Eles serão relatados através de um evento 'error' nos objetos Http2Session ou Servidor HTTP/2.

Erros de protocolo ocorrem quando várias restrições do protocolo HTTP/2 são violadas. Eles serão relatados usando um throw síncrono ou através de um evento 'error' nos objetos Http2Stream, Http2Session ou Servidor HTTP/2, dependendo de onde e quando o erro ocorre.

Tratamento de caracteres inválidos em nomes e valores de cabeçalho

A implementação HTTP/2 aplica um tratamento mais rigoroso de caracteres inválidos em nomes e valores de cabeçalho HTTP do que a implementação HTTP/1.

Os nomes de campos de cabeçalho não diferenciam maiúsculas de minúsculas e são transmitidos pela rede estritamente como strings em minúsculas. A API fornecida pelo Node.js permite que os nomes de cabeçalho sejam definidos como strings em maiúsculas e minúsculas (por exemplo, Content-Type), mas irá convertê-los para minúsculas (por exemplo, content-type) após a transmissão.

Os nomes de campos de cabeçalho devem conter apenas um ou mais dos seguintes caracteres ASCII: a-z, A-Z, 0-9, !, #, $, %, &, ', *, +, -, ., ^, _, ```(acento grave),|e~.

O uso de caracteres inválidos em um nome de campo de cabeçalho HTTP fará com que o fluxo seja fechado com um erro de protocolo sendo reportado.

Os valores de campos de cabeçalho são tratados com mais tolerância, mas não devem conter caracteres de nova linha ou retorno de carro e devem ser limitados a caracteres US-ASCII, de acordo com os requisitos da especificação HTTP.

Push streams no cliente

Para receber streams push no cliente, defina um ouvinte para o evento 'stream' no ClientHttp2Session:

ESM

import { connect } from 'node:http2'

const client = connect('http://localhost')

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', responseHeaders => {
    // Processar cabeçalhos de resposta
  })
  pushedStream.on('data', chunk => {
    /* lidar com dados push */
  })
})

const req = client.request({ ':path': '/' })

CJS

const http2 = require('node:http2')

const client = http2.connect('http://localhost')

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', responseHeaders => {
    // Processar cabeçalhos de resposta
  })
  pushedStream.on('data', chunk => {
    /* lidar com dados push */
  })
})

const req = client.request({ ':path': '/' })

Suporte ao método CONNECT

O método CONNECT é usado para permitir que um servidor HTTP/2 seja usado como um proxy para conexões TCP/IP.

Um Servidor TCP simples:

ESM

import { createServer } from 'node:net'

const server = createServer(socket => {
  let name = ''
  socket.setEncoding('utf8')
  socket.on('data', chunk => (name += chunk))
  socket.on('end', () => socket.end(`olá ${name}`))
})

server.listen(8000)

CJS

const net = require('node:net')

const server = net.createServer(socket => {
  let name = ''
  socket.setEncoding('utf8')
  socket.on('data', chunk => (name += chunk))
  socket.on('end', () => socket.end(`olá ${name}`))
})

server.listen(8000)

Um proxy HTTP/2 CONNECT:

ESM

import { createServer, constants } from 'node:http2'
const { NGHTTP2_REFUSED_STREAM, NGHTTP2_CONNECT_ERROR } = constants
import { connect } from 'node:net'

const proxy = createServer()
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // Aceitar apenas requisições CONNECT
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // É uma ótima ideia verificar se o hostname e a porta são
  // coisas que este proxy deve conectar.
  const socket = connect(auth.port, auth.hostname, () => {
    stream.respond()
    socket.pipe(stream)
    stream.pipe(socket)
  })
  socket.on('error', error => {
    stream.close(NGHTTP2_CONNECT_ERROR)
  })
})

proxy.listen(8001)

CJS

const http2 = require('node:http2')
const { NGHTTP2_REFUSED_STREAM } = http2.constants
const net = require('node:net')

const proxy = http2.createServer()
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // Aceitar apenas requisições CONNECT
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // É uma ótima ideia verificar se o hostname e a porta são
  // coisas que este proxy deve conectar.
  const socket = net.connect(auth.port, auth.hostname, () => {
    stream.respond()
    socket.pipe(stream)
    stream.pipe(socket)
  })
  socket.on('error', error => {
    stream.close(http2.constants.NGHTTP2_CONNECT_ERROR)
  })
})

proxy.listen(8001)

Um cliente HTTP/2 CONNECT:

ESM

import { connect, constants } from 'node:http2'

const client = connect('http://localhost:8001')

// Não deve especificar os cabeçalhos ':path' e ':scheme'
// para requisições CONNECT ou um erro será lançado.
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
})

req.on('response', headers => {
  console.log(headers[constants.HTTP2_HEADER_STATUS])
})
let data = ''
req.setEncoding('utf8')
req.on('data', chunk => (data += chunk))
req.on('end', () => {
  console.log(`O servidor diz: ${data}`)
  client.close()
})
req.end('Jane')

CJS

const http2 = require('node:http2')

const client = http2.connect('http://localhost:8001')

// Não deve especificar os cabeçalhos ':path' e ':scheme'
// para requisições CONNECT ou um erro será lançado.
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
})

req.on('response', headers => {
  console.log(headers[http2.constants.HTTP2_HEADER_STATUS])
})
let data = ''
req.setEncoding('utf8')
req.on('data', chunk => (data += chunk))
req.on('end', () => {
  console.log(`O servidor diz: ${data}`)
  client.close()
})
req.end('Jane')

O protocolo CONNECT estendido

RFC 8441 define uma extensão "Protocolo CONNECT Estendido" para HTTP/2 que pode ser usada para inicializar o uso de um Http2Stream usando o método CONNECT como um túnel para outros protocolos de comunicação (como WebSockets).

O uso do Protocolo CONNECT Estendido é habilitado por servidores HTTP/2 usando a configuração enableConnectProtocol:

ESM

import { createServer } from 'node:http2'
const settings = { enableConnectProtocol: true }
const server = createServer({ settings })

CJS

const http2 = require('node:http2')
const settings = { enableConnectProtocol: true }
const server = http2.createServer({ settings })

Depois que o cliente recebe o quadro SETTINGS do servidor indicando que o CONNECT estendido pode ser usado, ele pode enviar solicitações CONNECT que usam o pseudo-cabeçalho HTTP/2 ':protocol':

ESM

import { connect } from 'node:http2'
const client = connect('http://localhost:8080')
client.on('remoteSettings', settings => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' })
    // ...
  }
})

CJS

const http2 = require('node:http2')
const client = http2.connect('http://localhost:8080')
client.on('remoteSettings', settings => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' })
    // ...
  }
})

API de Compatibilidade

A API de Compatibilidade tem como objetivo fornecer uma experiência de desenvolvedor semelhante ao HTTP/1 ao usar HTTP/2, possibilitando o desenvolvimento de aplicações que suportam tanto HTTP/1 quanto HTTP/2. Essa API tem como alvo apenas a API pública do HTTP/1. No entanto, muitos módulos usam métodos ou estados internos, e esses não são suportados, pois é uma implementação completamente diferente.

O exemplo a seguir cria um servidor HTTP/2 usando a API de compatibilidade:

ESM

import { createServer } from 'node:http2'
const server = createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
  res.end('ok')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
  res.end('ok')
})

Para criar um servidor misto HTTPS e HTTP/2, consulte a seção negociação ALPN. Não é suportada a atualização de servidores HTTP/1 não-tls.

A API de compatibilidade HTTP/2 é composta por Http2ServerRequest e Http2ServerResponse. Eles visam a compatibilidade da API com HTTP/1, mas não ocultam as diferenças entre os protocolos. Como exemplo, a mensagem de status para códigos HTTP é ignorada.

Negociação ALPN

A negociação ALPN permite suportar tanto HTTPS quanto HTTP/2 sobre o mesmo socket. Os objetos req e res podem ser tanto HTTP/1 quanto HTTP/2, e uma aplicação deve se restringir à API pública de HTTP/1, e detectar se é possível usar os recursos mais avançados do HTTP/2.

O exemplo a seguir cria um servidor que suporta ambos os protocolos:

ESM

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

const cert = readFileSync('./cert.pem')
const key = readFileSync('./key.pem')

const server = createSecureServer({ cert, key, allowHTTP1: true }, onRequest).listen(8000)

function onRequest(req, res) {
  // Detecta se é uma requisição HTTPS ou HTTP/2
  const {
    socket: { alpnProtocol },
  } = req.httpVersion === '2.0' ? req.stream.session : req
  res.writeHead(200, { 'content-type': 'application/json' })
  res.end(
    JSON.stringify({
      alpnProtocol,
      httpVersion: req.httpVersion,
    })
  )
}

CJS

const { createSecureServer } = require('node:http2')
const { readFileSync } = require('node:fs')

const cert = readFileSync('./cert.pem')
const key = readFileSync('./key.pem')

const server = createSecureServer({ cert, key, allowHTTP1: true }, onRequest).listen(4443)

function onRequest(req, res) {
  // Detecta se é uma requisição HTTPS ou HTTP/2
  const {
    socket: { alpnProtocol },
  } = req.httpVersion === '2.0' ? req.stream.session : req
  res.writeHead(200, { 'content-type': 'application/json' })
  res.end(
    JSON.stringify({
      alpnProtocol,
      httpVersion: req.httpVersion,
    })
  )
}

O evento 'request' funciona de forma idêntica tanto em HTTPS quanto em HTTP/2.

Classe: http2.Http2ServerRequest

Adicionado em: v8.4.0

• Estende: <stream.Readable>

Um objeto Http2ServerRequest é criado por http2.Server ou http2.SecureServer e passado como o primeiro argumento para o evento 'request'. Ele pode ser usado para acessar o status de uma requisição, cabeçalhos e dados.

Evento: 'aborted'

Adicionado em: v8.4.0

O evento 'aborted' é emitido sempre que uma instância Http2ServerRequest é abortada de forma anormal no meio da comunicação.

O evento 'aborted' só será emitido se o lado gravável do Http2ServerRequest não tiver sido finalizado.

Evento: 'close'

Adicionado em: v8.4.0

Indica que o Http2Stream subjacente foi fechado. Assim como 'end', este evento ocorre apenas uma vez por resposta.

request.aborted

Adicionado em: v10.1.0

• <boolean>

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

request.authority

Adicionado em: v8.4.0

• <string>

O campo do pseudo cabeçalho de autoridade da solicitação. Como o HTTP/2 permite que as solicitações definam :authority ou host, este valor é derivado de req.headers[':authority'] se presente. Caso contrário, é derivado de req.headers['host'].

request.complete

Adicionado em: v12.10.0

• <boolean>

A propriedade request.complete será true se a solicitação tiver sido concluída, abortada ou destruída.

request.connection

Adicionado em: v8.4.0

Obsoleto desde: v13.0.0

[Estável: 0 - Obsoleto]

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

• <net.Socket> | <tls.TLSSocket>

Veja request.socket.

request.destroy([error])

Adicionado em: v8.4.0

• error <Error>

Chama destroy() no Http2Stream que recebeu o Http2ServerRequest. Se error for fornecido, um evento 'error' é emitido e error é passado como argumento para qualquer ouvinte do evento.

Não faz nada se o fluxo já tiver sido destruído.

request.headers

Adicionado em: v8.4.0

• <Objeto>

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

Pares de chave-valor de nomes e valores de cabeçalho. Os nomes dos cabeçalhos estão em letras minúsculas.

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

Veja Objeto de Cabeçalhos HTTP/2.

Em HTTP/2, o caminho da solicitação, o nome do host, o protocolo e o método são representados como cabeçalhos especiais prefixados com o caractere : (por exemplo, ':path'). Esses cabeçalhos especiais serão incluídos no objeto request.headers. Deve-se tomar cuidado para não modificar inadvertidamente esses cabeçalhos especiais ou erros podem ocorrer. Por exemplo, remover todos os cabeçalhos da solicitação fará com que ocorram erros:

removeAllHeaders(request.headers)
assert(request.url) // Falha porque o cabeçalho :path foi removido

request.httpVersion

Adicionado em: v8.4.0

• <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. Retorna '2.0'.

Também message.httpVersionMajor é o primeiro inteiro e message.httpVersionMinor é o segundo.

request.method

Adicionado em: v8.4.0

• <string>

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

request.rawHeaders

Adicionado em: v8.4.0

• <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 é não uma lista de tuplas. Portanto, os offsets de números pares são valores de chave, e os offsets de números ímpares são os valores associados.

Os nomes dos cabeçalhos não estão em letras minúsculas e os duplicados não são mesclados.

// Imprime algo como:
//
// [ 'user-agent',
//   'isso é inválido porque só pode haver um',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders)

request.rawTrailers

Adicionado em: v8.4.0

• <string[]>

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

request.scheme

Adicionado em: v8.4.0

• <string>

O campo de pseudo-cabeçalho de esquema de solicitação que indica a parte do esquema da URL de destino.

request.setTimeout(msecs, callback)

Adicionado em: v8.4.0

• msecs <number>
• callback <Function>
• Retorna: <http2.Http2ServerRequest>

Define o valor de tempo limite do Http2Stream 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 à solicitação, à resposta ou ao servidor, os Http2Stream serão destruídos quando o tempo limite for atingido. Se um manipulador for atribuído aos eventos 'timeout' da solicitação, da resposta ou do servidor, os sockets com tempo limite esgotado deverão ser tratados explicitamente.

request.socket

Adicionado em: v8.4.0

• <net.Socket> | <tls.TLSSocket>

Retorna um objeto Proxy que atua como um net.Socket (ou tls.TLSSocket), mas aplica getters, setters e métodos com base na lógica HTTP/2.

As propriedades destroyed, readable e writable serão recuperadas e definidas em request.stream.

Os métodos destroy, emit, end, on e once serão chamados em request.stream.

O método setTimeout será chamado em request.stream.session.

pause, read, resume e write lançarão um erro com o código ERR_HTTP2_NO_SOCKET_MANIPULATION. Consulte Http2Session e Sockets para obter mais informações.

Todas as outras interações serão encaminhadas diretamente para o socket. Com suporte TLS, use request.socket.getPeerCertificate() para obter os detalhes de autenticação do cliente.

request.stream

Adicionado em: v8.4.0

• <Http2Stream>

O objeto Http2Stream que suporta a requisição.

request.trailers

Adicionado em: v8.4.0

• <Object>

O objeto de trailers de requisição/resposta. É preenchido apenas no evento 'end'.

request.url

Adicionado em: v8.4.0

• <string>

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

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

Então request.url será:

'/status?name=ryan'

Para analisar a url em suas partes, new URL() pode ser usado:

$ node
> new URL('/status?name=ryan', 'http://example.com')
URL {
  href: 'http://example.com/status?name=ryan',
  origin: 'http://example.com',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'example.com',
  hostname: 'example.com',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

Classe: http2.Http2ServerResponse

Adicionado em: v8.4.0

• Estende: <Stream>

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: v8.4.0

Indica que o Http2Stream subjacente foi terminado antes que response.end() fosse chamado ou fosse capaz de liberar.

Evento: 'finish'

Adicionado em: v8.4.0

Emitido quando a resposta foi enviada. Mais especificamente, este evento é emitido quando o último segmento dos cabeçalhos de resposta e corpo foram entregues ao multiplexamento HTTP/2 para transmissão pela rede. Não implica que o cliente já tenha recebido algo.

Após este evento, nenhum outro evento será emitido no objeto de resposta.

response.addTrailers(headers)

Adicionado em: v8.4.0

• headers <Object>

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

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.

response.appendHeader(name, value)

Adicionado em: v21.7.0, v20.12.0

• name <string>
• value <string> | <string[]>

Anexe 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 houver valores anteriores para o cabeçalho, isso é equivalente a chamar response.setHeader().

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.

// Retorna cabeçalhos incluindo "set-cookie: a" e "set-cookie: b"
const server = http2.createServer((req, res) => {
  res.setHeader('set-cookie', 'a')
  res.appendHeader('set-cookie', 'b')
  res.writeHead(200)
  res.end('ok')
})

response.connection

Adicionado em: v8.4.0

Obsoleto desde: v13.0.0

[Estável: 0 - Obsoleto]

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

• <net.Socket> | <tls.TLSSocket>

Consulte response.socket.

response.createPushResponse(headers, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.4.0	Adicionado em: v8.4.0

• headers <Objeto de Cabeçalhos HTTP/2> Um objeto descrevendo os cabeçalhos
• callback <Função> Chamada assim que http2stream.pushStream() é concluído, ou quando a tentativa de criar o Http2Stream push falhou ou foi rejeitada, ou o estado de Http2ServerRequest é fechado antes de chamar o método http2stream.pushStream()
  • err <Erro>
  • res <http2.Http2ServerResponse> O objeto Http2ServerResponse recém-criado

Chame http2stream.pushStream() com os cabeçalhos fornecidos e envolva o Http2Stream fornecido em um Http2ServerResponse recém-criado como o parâmetro de retorno de chamada se for bem-sucedido. Quando Http2ServerRequest é fechado, o retorno de chamada é chamado com um erro ERR_HTTP2_INVALID_STREAM.

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

[Histórico]

Versão	Mudanças
v10.0.0	Este método agora retorna uma referência para ServerResponse.
v8.4.0	Adicionado em: v8.4.0

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

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

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

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

response.finished

Adicionado em: v8.4.0

Obsoleto desde: v13.4.0, v12.16.0

[Estável: 0 - Obsoleto]

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

• <boolean>

Valor booleano que indica se a resposta foi concluída. Começa como false. Após a execução de response.end(), o valor será true.

response.getHeader(name)

Adicionado em: v8.4.0

• name <string>
• Retorna: <string>

Lê um cabeçalho que já foi enfileirado, mas não enviado ao cliente. O nome não diferencia maiúsculas de minúsculas.

const contentType = response.getHeader('content-type')

response.getHeaderNames()

Adicionado em: v8.4.0

• Retorna: <string[]>

Retorna um array contendo os nomes únicos dos cabeçalhos de saída atuais. Todos os nomes de cabeçalho estã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: v8.4.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 modificados 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 estão em minúsculas.

O objeto retornado pelo método response.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.

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: v8.4.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 = response.hasHeader('content-type')

response.headersSent

Adicionado em: v8.4.0

• <boolean>

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

response.removeHeader(name)

Adicionado em: v8.4.0

• name <string>

Remove um cabeçalho que foi enfileirado para envio implícito.

response.removeHeader('Content-Encoding')

response.req

Adicionado em: v15.7.0

• <http2.Http2ServerRequest>

Uma referência ao objeto request HTTP2 original.

response.sendDate

Adicionado em: v8.4.0

• <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.

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

response.setHeader(name, value)

Adicionado em: v8.4.0

• name <string>
• value <string> | <string[]>

Define um único valor de cabeçalho para cabeçalhos implícitos. 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.

response.setHeader('Content-Type', 'text/html; charset=utf-8')

ou

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

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

Quando os cabeçalhos foram 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.

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

response.setTimeout(msecs[, callback])

Adicionado em: v8.4.0

• msecs <number>
• callback <Function>
• Retorna: <http2.Http2ServerResponse>

Define o valor de tempo limite do Http2Stream para msecs. Se um callback for fornecido, ele será adicionado como um listener no evento 'timeout' no objeto de resposta.

Se nenhum listener 'timeout' for adicionado à requisição, à resposta ou ao servidor, então os Http2Streams serão destruídos quando expirarem. Se um handler for atribuído aos eventos 'timeout' da requisição, da resposta ou do servidor, sockets expirados devem ser tratados explicitamente.

response.socket

Adicionado em: v8.4.0

• <net.Socket> | <tls.TLSSocket>

Retorna um objeto Proxy que age como um net.Socket (ou tls.TLSSocket), mas aplica getters, setters e métodos baseados na lógica HTTP/2.

As propriedades destroyed, readable e writable serão recuperadas e definidas em response.stream.

Os métodos destroy, emit, end, on e once serão chamados em response.stream.

O método setTimeout será chamado em response.stream.session.

pause, read, resume e write lançarão um erro com o código ERR_HTTP2_NO_SOCKET_MANIPULATION. Consulte Http2Session e Sockets para mais informações.

Todas as outras interações serão roteadas diretamente para o socket.

ESM

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

CJS

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

response.statusCode

Adicionado em: v8.4.0

• <number>

Ao usar cabeçalhos implícitos (não chamando 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

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

response.statusMessage

Adicionado em: v8.4.0

• <string>

A mensagem de status não é suportada pelo HTTP/2 (RFC 7540 8.1.2.4). Retorna uma string vazia.

response.stream

Adicionado em: v8.4.0

• <Http2Stream>

O objeto Http2Stream que suporta a resposta.

response.writableEnded

Adicionado em: v12.9.0

• <boolean>

É true após response.end() ter sido chamado. Esta propriedade não indica se os dados foram liberados, para isso use writable.writableFinished.

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

Adicionado em: v8.4.0

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• 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 liberará os cabeçalhos implícitos.

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

No módulo node:http, o corpo da resposta é omitido quando a solicitação é uma solicitação HEAD. Da mesma forma, as respostas 204 e 304 não devem incluir um corpo de mensagem.

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. Por padrão, o encoding é 'utf8'. callback será chamado quando este trecho de dados for liberado.

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 trecho 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 trecho do corpo.

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. 'drain' será emitido quando o buffer estiver livre novamente.

response.writeContinue()

Adicionado em: v8.4.0

Envia um status 100 Continue para o cliente, indicando que o corpo da requisição deve ser enviado. Veja o evento 'checkContinue' em Http2Server e Http2SecureServer.

response.writeEarlyHints(hints)

Adicionado em: v18.11.0

• hints <Objeto>

Envia um status 103 Early Hints para o cliente com um cabeçalho Link, indicando que o user agent 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.

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,
})

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

[Histórico]

Versão	Mudanças
v11.10.0, v10.17.0	Retorna this de writeHead() para permitir o encadeamento com end().
v8.4.0	Adicionado em: v8.4.0

• statusCode <número>
• statusMessage <string>
• headers <Objeto> | <Array>
• Retorna: <http2.Http2ServerResponse>

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.

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

Para compatibilidade com HTTP/1, uma statusMessage legível por humanos pode ser passada como segundo argumento. No entanto, como o statusMessage não tem significado dentro do HTTP/2, o argumento não terá efeito e um aviso de processo será emitido.

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

Content-Length é fornecido em bytes, não em caracteres. A API Buffer.byteLength() pode ser usada para determinar o número de bytes em uma determinada codificação. Em mensagens de saída, o Node.js não verifica se o Content-Length e o tamanho do corpo sendo transmitido são iguais ou não. No entanto, ao receber mensagens, o Node.js rejeitará automaticamente as mensagens quando o Content-Length não corresponder ao tamanho real da carga útil.

Este método pode ser chamado no máximo uma vez em uma mensagem antes que response.end() seja chamado.

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

Quando os cabeçalhos foram 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.

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

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

Coletando métricas de desempenho HTTP/2

A API Performance Observer pode ser usada para coletar métricas básicas de desempenho para cada instância Http2Session e Http2Stream.

ESM

import { PerformanceObserver } from 'node:perf_hooks'

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // imprime 'http2'
  if (entry.name === 'Http2Session') {
    // Entrada contém estatísticas sobre a Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Entrada contém estatísticas sobre a Http2Stream
  }
})
obs.observe({ entryTypes: ['http2'] })

CJS

const { PerformanceObserver } = require('node:perf_hooks')

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // imprime 'http2'
  if (entry.name === 'Http2Session') {
    // Entrada contém estatísticas sobre a Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Entrada contém estatísticas sobre a Http2Stream
  }
})
obs.observe({ entryTypes: ['http2'] })

A propriedade entryType de PerformanceEntry será igual a 'http2'.

A propriedade name de PerformanceEntry será igual a 'Http2Stream' ou 'Http2Session'.

Se name for igual a Http2Stream, a PerformanceEntry conterá as seguintes propriedades adicionais:

• bytesRead <number> O número de bytes de quadro DATA recebidos para esta Http2Stream.
• bytesWritten <number> O número de bytes de quadro DATA enviados para esta Http2Stream.
• id <number> O identificador da Http2Stream associada.
• timeToFirstByte <number> O número de milissegundos decorridos entre o startTime de PerformanceEntry e o recebimento do primeiro quadro DATA.
• timeToFirstByteSent <number> O número de milissegundos decorridos entre o startTime de PerformanceEntry e o envio do primeiro quadro DATA.
• timeToFirstHeader <number> O número de milissegundos decorridos entre o startTime de PerformanceEntry e o recebimento do primeiro cabeçalho.

Se name for igual a Http2Session, a PerformanceEntry conterá as seguintes propriedades adicionais:

• bytesRead <number> O número de bytes recebidos para esta Http2Session.
• bytesWritten <number> O número de bytes enviados para esta Http2Session.
• framesReceived <number> O número de quadros HTTP/2 recebidos pela Http2Session.
• framesSent <number> O número de quadros HTTP/2 enviados pela Http2Session.
• maxConcurrentStreams <number> O número máximo de fluxos abertos simultaneamente durante a vida útil da Http2Session.
• pingRTT <number> O número de milissegundos decorridos desde a transmissão de um quadro PING e o recebimento de seu reconhecimento. Presente apenas se um quadro PING tiver sido enviado na Http2Session.
• streamAverageDuration <number> A duração média (em milissegundos) para todas as instâncias de Http2Stream.
• streamCount <number> O número de instâncias Http2Stream processadas pela Http2Session.
• type <string> Ou 'server' ou 'client' para identificar o tipo de Http2Session.

Nota sobre :authority e host

O HTTP/2 exige que as solicitações tenham o pseudo-cabeçalho :authority ou o cabeçalho host. Prefira :authority ao construir uma solicitação HTTP/2 diretamente e host ao converter do HTTP/1 (em proxies, por exemplo).

A API de compatibilidade volta para host se :authority não estiver presente. Consulte request.authority para obter mais informações. No entanto, se você não usar a API de compatibilidade (ou usar req.headers diretamente), você precisa implementar qualquer comportamento de fallback por conta própria.