HTTP/2

[Historique]

Version	Modifications
v15.0.0	Les requêtes avec l'en-tête host (avec ou sans :authority) peuvent maintenant être envoyées/reçues.
v15.3.0, v14.17.0	Il est possible d'avorter une requête avec un AbortSignal.
v10.10.0	HTTP/2 est maintenant Stable. Précédemment, il était Expérimental.
v8.4.0	Ajouté dans : v8.4.0

[Stable : 2 - Stable]

Stable : 2 Stabilité : 2 - Stable

Code source : lib/http2.js

Le module node:http2 fournit une implémentation du protocole HTTP/2. Il est accessible en utilisant :

const http2 = require('node:http2')

Détermination de la non-disponibilité de la prise en charge de crypto

Il est possible que Node.js soit compilé sans inclure la prise en charge du module node:crypto. Dans de tels cas, toute tentative d'importation depuis node:http2 ou d'appel de require('node:http2') entraînera le lancement d'une erreur.

Lors de l'utilisation de CommonJS, l'erreur levée peut être interceptée à l'aide de try/catch :

let http2
try {
  http2 = require('node:http2')
} catch (err) {
  console.error('La prise en charge de http2 est désactivée !')
}

Lors de l'utilisation du mot clé import ESM lexical, l'erreur ne peut être interceptée que si un gestionnaire pour process.on('uncaughtException') est enregistré avant toute tentative de chargement du module (en utilisant, par exemple, un module de préchargement).

Lors de l'utilisation d'ESM, s'il y a une chance que le code puisse être exécuté sur une version de Node.js où la prise en charge de crypto n'est pas activée, envisagez d'utiliser la fonction import() au lieu du mot clé import lexical :

let http2
try {
  http2 = await import('node:http2')
} catch (err) {
  console.error('La prise en charge de http2 est désactivée !')
}

API principale

L'API principale fournit une interface de bas niveau conçue spécifiquement pour la prise en charge des fonctionnalités du protocole HTTP/2. Elle n'est pas spécifiquement conçue pour être compatible avec l'API du module HTTP/1 existant. Cependant, l' API de compatibilité l'est.

L'API principale http2 est beaucoup plus symétrique entre le client et le serveur que l'API http. Par exemple, la plupart des événements, tels que 'error', 'connect' et 'stream', peuvent être émis par du code côté client ou côté serveur.

Exemple côté serveur

L'exemple suivant illustre un serveur HTTP/2 simple utilisant l'API Core. Comme il n'existe aucun navigateur connu prenant en charge le HTTP/2 non chiffré, l'utilisation de http2.createSecureServer() est nécessaire lors de la communication avec des clients navigateurs.

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 est un Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</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 est un Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8443)

Pour générer le certificat et la clé pour cet exemple, exécutez :

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

Exemple côté client

L'exemple suivant illustre un client 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

Ajouté dans : v8.4.0

• Étend : <EventEmitter>

Les instances de la classe http2.Http2Session représentent une session de communication active entre un client et un serveur HTTP/2. Les instances de cette classe ne sont pas destinées à être construites directement par le code utilisateur.

Chaque instance Http2Session présentera des comportements légèrement différents selon qu'elle fonctionne en tant que serveur ou client. La propriété http2session.type peut être utilisée pour déterminer le mode dans lequel un Http2Session fonctionne. Côté serveur, le code utilisateur aura rarement l'occasion de travailler directement avec l'objet Http2Session, la plupart des actions étant généralement effectuées par le biais d'interactions avec les objets Http2Server ou Http2Stream.

Le code utilisateur ne créera pas d'instances Http2Session directement. Les instances Http2Session côté serveur sont créées par l'instance Http2Server lorsqu'une nouvelle connexion HTTP/2 est reçue. Les instances Http2Session côté client sont créées à l'aide de la méthode http2.connect().

Http2Session et sockets

Chaque instance Http2Session est associée à exactement un net.Socket ou tls.TLSSocket lors de sa création. Lorsque la Socket ou la Http2Session sont détruites, toutes deux seront détruites.

En raison des exigences spécifiques de sérialisation et de traitement imposées par le protocole HTTP/2, il n'est pas recommandé au code utilisateur de lire ou d'écrire des données dans une instance Socket liée à une Http2Session. Cela peut mettre la session HTTP/2 dans un état indéterminé, rendant la session et la socket inutilisables.

Une fois qu'une Socket a été liée à une Http2Session, le code utilisateur doit s'appuyer uniquement sur l'API de la Http2Session.

Événement : 'close'

Ajouté dans : v8.4.0

L'événement 'close' est émis une fois que la Http2Session a été détruite. Son écouteur n'attend aucun argument.

Événement : 'connect'

Ajouté dans : v8.4.0

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

L'événement 'connect' est émis une fois que la Http2Session a été connectée avec succès à l'homologue distant et que la communication peut commencer.

Le code utilisateur n'écoutera généralement pas directement cet événement.

Événement : 'error'

Ajouté dans : v8.4.0

• error <Error>

L'événement 'error' est émis lorsqu'une erreur survient lors du traitement d'une Http2Session.

Événement : 'frameError'

Ajouté dans : v8.4.0

• type <integer> Le type de trame.
• code <integer> Le code d'erreur.
• id <integer> L'ID du flux (ou 0 si la trame n'est pas associée à un flux).

L'événement 'frameError' est émis lorsqu'une erreur survient lors de la tentative d'envoi d'une trame sur la session. Si la trame qui n'a pas pu être envoyée est associée à un Http2Stream spécifique, une tentative d'émission d'un événement 'frameError' sur le Http2Stream est effectuée.

Si l'événement 'frameError' est associé à un flux, le flux sera fermé et détruit immédiatement après l'événement 'frameError'. Si l'événement n'est pas associé à un flux, le Http2Session sera arrêté immédiatement après l'événement 'frameError'.

Événement : 'goaway'

Ajouté dans : v8.4.0

• errorCode <number> Le code d'erreur HTTP/2 spécifié dans la trame GOAWAY.
• lastStreamID <number> L'ID du dernier flux que le pair distant a correctement traité (ou 0 si aucun ID n'est spécifié).
• opaqueData <Buffer> Si des données opaques supplémentaires ont été incluses dans la trame GOAWAY, une instance Buffer sera passée contenant ces données.

L'événement 'goaway' est émis lorsqu'une trame GOAWAY est reçue.

L'instance Http2Session sera automatiquement arrêtée lorsque l'événement 'goaway' est émis.

Événement : 'localSettings'

Ajouté dans : v8.4.0

• settings <Objet de paramètres HTTP/2> Une copie de l’image SETTINGS reçue.

L’événement 'localSettings' est émis lorsqu’une image d’accusé de réception SETTINGS a été reçue.

Lors de l’utilisation de http2session.settings() pour soumettre de nouveaux paramètres, les paramètres modifiés ne prennent pas effet tant que l’événement 'localSettings' n’est pas émis.

session.settings({ enablePush: false })

session.on('localSettings', settings => {
  /* Utilisez les nouveaux paramètres */
})

Événement : 'ping'

Ajouté dans : v10.12.0

• payload <Buffer> La charge utile de 8 octets de l’image PING

L’événement 'ping' est émis chaque fois qu’une image PING est reçue du pair connecté.

Événement : 'remoteSettings'

Ajouté dans : v8.4.0

• settings <Objet de paramètres HTTP/2> Une copie de l’image SETTINGS reçue.

L’événement 'remoteSettings' est émis lorsqu’une nouvelle image SETTINGS est reçue du pair connecté.

session.on('remoteSettings', settings => {
  /* Utilisez les nouveaux paramètres */
})

Événement : 'stream'

Ajouté dans : v8.4.0

• stream <Http2Stream> Une référence au flux
• headers <Objet d’en-têtes HTTP/2> Un objet décrivant les en-têtes
• flags <nombre> Les indicateurs numériques associés
• rawHeaders <Tableau> Un tableau contenant les noms d’en-têtes bruts suivis de leurs valeurs respectives.

L’événement 'stream' est émis lorsqu’un nouveau Http2Stream est créé.

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

Côté serveur, le code utilisateur n’écoute généralement pas directement cet événement et enregistrerait plutôt un gestionnaire pour l’événement 'stream' émis par les instances net.Server ou tls.Server renvoyées par http2.createServer() et http2.createSecureServer(), respectivement, comme dans l’exemple ci-dessous :

ESM

import { createServer } from 'node:http2'

// Créer un serveur HTTP/2 non chiffré
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')

// Créer un serveur HTTP/2 non chiffré
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)

Même si les flux HTTP/2 et les sockets réseau ne sont pas en correspondance 1:1, une erreur réseau détruira chaque flux individuel et doit être gérée au niveau du flux, comme indiqué ci-dessus.

Événement : 'timeout'

Ajouté dans : v8.4.0

Après que la méthode http2session.setTimeout() a été utilisée pour définir la période d’expiration de cette Http2Session, l’événement 'timeout' est émis s’il n’y a aucune activité sur la Http2Session après le nombre de millisecondes configuré. Son écouteur n’attend aucun argument.

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

http2session.alpnProtocol

Ajouté dans : v9.4.0

• <string> | <undefined>

La valeur sera undefined si la Http2Session n’est pas encore connectée à une socket, h2c si la Http2Session n’est pas connectée à une TLSSocket, ou renverra la valeur de la propriété alpnProtocol de la TLSSocket connectée.

http2session.close([callback])

Ajouté dans : v9.4.0

• callback <Function>

Ferme en douceur la Http2Session, permettant à tous les flux existants de se terminer par eux-mêmes et empêchant la création de nouvelles instances Http2Stream. Une fois fermée, http2session.destroy() pourrait être appelée s’il n’y a aucune instance Http2Stream ouverte.

Si spécifié, la fonction callback est enregistrée comme gestionnaire de l’événement 'close'.

http2session.closed

Ajouté dans : v9.4.0

• <boolean>

Sera true si cette instance Http2Session a été fermée, sinon false.

http2session.connecting

Ajouté dans : v10.0.0

• <boolean>

Sera true si cette instance Http2Session est toujours en cours de connexion, sera définie sur false avant d’émettre l’événement connect et/ou d’appeler la fonction de rappel http2.connect.

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

Ajouté dans : v8.4.0

• error <Error> Un objet Error si la Http2Session est en cours de destruction en raison d’une erreur.
• code <number> Le code d’erreur HTTP/2 à envoyer dans l’image GOAWAY finale. S’il n’est pas spécifié, et que error n’est pas indéfini, la valeur par défaut est INTERNAL_ERROR, sinon la valeur par défaut est NO_ERROR.

Met fin immédiatement à la Http2Session et à la net.Socket ou tls.TLSSocket associée.

Une fois détruite, la Http2Session émettra l’événement 'close'. Si error n’est pas indéfini, un événement 'error' sera émis immédiatement avant l’événement 'close'.

S’il reste des Http2Streams ouverts associés à la Http2Session, ceux-ci seront également détruits.

http2session.destroyed

Ajouté dans : v8.4.0

• <booléen>

Sera true si cette instance Http2Session a été détruite et ne doit plus être utilisée, sinon false.

http2session.encrypted

Ajouté dans : v9.4.0

• <booléen> | <indéfini>

La valeur est indéfinie si le socket de session Http2Session n'a pas encore été connecté, true si le Http2Session est connecté avec un TLSSocket, et false si le Http2Session est connecté à un autre type de socket ou de flux.

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

Ajouté dans : v9.4.0

• code <nombre> Un code d'erreur HTTP/2
• lastStreamID <nombre> L'ID numérique du dernier Http2Stream traité
• opaqueData <Buffer> | <TypedArray> | <DataView> Une instance TypedArray ou DataView contenant des données supplémentaires à transporter dans l'en-tête GOAWAY.

Transmet un en-tête GOAWAY à l'homologue connecté sans arrêter la session Http2Session.

http2session.localSettings

Ajouté dans : v8.4.0

• <Objet Paramètres HTTP/2>

Un objet sans prototype décrivant les paramètres locaux actuels de cette instance Http2Session. Les paramètres locaux sont propres à cette instance Http2Session.

http2session.originSet

Ajouté dans : v9.4.0

• <tableau de chaînes de caractères> | <indéfini>

Si le Http2Session est connecté à un TLSSocket, la propriété originSet renverra un tableau des origines pour lesquelles le Http2Session peut être considéré comme faisant autorité.

La propriété originSet est uniquement disponible lors de l'utilisation d'une connexion TLS sécurisée.

http2session.pendingSettingsAck

Ajouté dans : v8.4.0

• <boolean>

Indique si Http2Session attend actuellement l'accusé de réception d'une trame SETTINGS envoyée. Sera true après l'appel de la méthode http2session.settings(). Sera false une fois que toutes les trames SETTINGS envoyées auront été accusées de réception.

http2session.ping([payload, ]callback)

[Historique]

Version	Modifications
v18.0.0	Le passage d'une fonction de rappel invalide à l'argument callback lève maintenant ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v8.9.3	Ajouté dans : v8.9.3

• payload <Buffer> | <TypedArray> | <DataView> Charge utile de ping facultative.
• callback <Function>
• Retourne : <boolean>

Envoie une trame PING à l'homologue HTTP/2 connecté. Une fonction callback doit être fournie. La méthode retournera true si le PING a été envoyé, false sinon.

Le nombre maximal de pings en attente (non accusés de réception) est déterminé par l'option de configuration maxOutstandingPings. La valeur maximale par défaut est 10.

Si fournie, la payload doit être un objet Buffer, TypedArray ou DataView contenant 8 octets de données qui seront transmis avec le PING et retournés avec l'accusé de réception du ping.

La fonction de rappel sera appelée avec trois arguments : un argument d'erreur qui sera null si le PING a été correctement accusé de réception, un argument duration qui indique le nombre de millisecondes écoulées depuis l'envoi du ping et la réception de l'accusé de réception, et un objet Buffer contenant la charge utile PING de 8 octets.

session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`Ping accusé de réception en ${duration} millisecondes`)
    console.log(`Avec la charge utile '${payload.toString()}'`)
  }
})

Si l'argument payload n'est pas spécifié, la charge utile par défaut sera l'horodatage 64 bits (little endian) marquant le début de la durée du PING.

http2session.ref()

Ajouté dans : v9.4.0

Appelle ref() sur la net.Socket sous-jacente de cette instance Http2Session.

http2session.remoteSettings

Ajouté dans : v8.4.0

• <Objet Paramètres HTTP/2>

Un objet sans prototype décrivant les paramètres distants actuels de cette Http2Session. Les paramètres distants sont définis par le pair HTTP/2 connecté.

http2session.setLocalWindowSize(windowSize)

Ajouté dans : v15.3.0, v14.18.0

• windowSize <nombre>

Définit la taille de la fenêtre du point de terminaison local. windowSize est la taille totale de la fenêtre à définir, et non la différence.

ESM

import { createServer } from 'node:http2'

const server = createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // Définir la taille de la fenêtre locale à 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // Définir la taille de la fenêtre locale à 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

Pour les clients http2, l'événement approprié est soit 'connect', soit 'remoteSettings'.

http2session.setTimeout(msecs, callback)

[Historique]

Version	Modifications
v18.0.0	Passer un rappel invalide à l'argument callback lève maintenant ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v8.4.0	Ajouté dans : v8.4.0

• msecs <nombre>
• callback <Fonction>

Utilisé pour définir une fonction de rappel qui est appelée lorsqu'il n'y a aucune activité sur la Http2Session après msecs millisecondes. Le callback donné est enregistré comme écouteur sur l'événement 'timeout'.

http2session.socket

Ajouté dans : v8.4.0

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

Retourne un objet Proxy qui agit comme un net.Socket (ou tls.TLSSocket) mais limite les méthodes disponibles à celles utilisables en toute sécurité avec HTTP/2.

destroy, emit, end, pause, read, resume, et write déclencheront une erreur avec le code ERR_HTTP2_NO_SOCKET_MANIPULATION. Voir Http2Session et les sockets pour plus d'informations.

La méthode setTimeout sera appelée sur cette Http2Session.

Toutes les autres interactions seront routées directement vers le socket.

http2session.state

Ajouté dans : v8.4.0

Fournit des informations diverses sur l'état actuel de la Http2Session.

• <Object>
  • effectiveLocalWindowSize <number> La taille actuelle de la fenêtre de contrôle de flux locale (réception) pour la Http2Session.
  • effectiveRecvDataLength <number> Le nombre actuel d'octets reçus depuis la dernière mise à jour du contrôle de flux WINDOW_UPDATE.
  • nextStreamID <number> L'identifiant numérique à utiliser la prochaine fois qu'un nouveau Http2Stream sera créé par cette Http2Session.
  • localWindowSize <number> Le nombre d'octets que le pair distant peut envoyer sans recevoir de WINDOW_UPDATE.
  • lastProcStreamID <number> L'identifiant numérique du Http2Stream pour lequel une trame HEADERS ou DATA a été reçue le plus récemment.
  • remoteWindowSize <number> Le nombre d'octets que cette Http2Session peut envoyer sans recevoir de WINDOW_UPDATE.
  • outboundQueueSize <number> Le nombre de trames actuellement dans la file d'attente sortante pour cette Http2Session.
  • deflateDynamicTableSize <number> La taille actuelle en octets de la table d'état de compression d'en-tête sortante.
  • inflateDynamicTableSize <number> La taille actuelle en octets de la table d'état de compression d'en-tête entrante.

Un objet décrivant l'état actuel de cette Http2Session.

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

[Historique]

Version	Modifications
v18.0.0	Le passage d'une fonction de rappel invalide à l'argument callback lève maintenant une erreur ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v8.4.0	Ajouté dans : v8.4.0

• settings <Objet Paramètres HTTP/2>
• callback <Fonction> Fonction de rappel appelée une fois que la session est connectée ou immédiatement si la session est déjà connectée.
  • err <Erreur> | <null>
  • settings <Objet Paramètres HTTP/2> L'objet settings mis à jour.
  • duration <entier>

Met à jour les paramètres locaux actuels pour cette instance Http2Session et envoie un nouvel en-tête SETTINGS au pair HTTP/2 connecté.

Une fois appelée, la propriété http2session.pendingSettingsAck sera true tant que la session attend que le pair distant accuse réception des nouveaux paramètres.

Les nouveaux paramètres ne seront pas effectifs tant que l'accusé de réception SETTINGS n'est pas reçu et que l'événement 'localSettings' n'est pas émis. Il est possible d'envoyer plusieurs en-têtes SETTINGS tant que l'accusé de réception est en attente.

http2session.type

Ajouté dans : v8.4.0

• <nombre>

La valeur de http2session.type sera égale à http2.constants.NGHTTP2_SESSION_SERVER si cette instance Http2Session est un serveur, et à http2.constants.NGHTTP2_SESSION_CLIENT si l'instance est un client.

http2session.unref()

Ajouté dans : v9.4.0

Appelle unref() sur l'instance net.Socket sous-jacente de cette instance Http2Session.

Classe : ServerHttp2Session

Ajouté dans : v8.4.0

• Étend : <Http2Session>

serverhttp2session.altsvc(alt, originOrStream)

Ajouté dans : v9.4.0

• alt <string> Une description de la configuration du service alternatif telle que définie par la RFC 7838.
• originOrStream <number> | <string> | <URL> | <Object> Soit une chaîne de caractères URL spécifiant l’origine (ou un Object avec une propriété origin) soit l’identifiant numérique d’un Http2Stream actif, tel que donné par la propriété http2stream.id.

Soumet une trame ALTSVC (telle que définie par la RFC 7838) au client connecté.

ESM

import { createServer } from 'node:http2'

const server = createServer()
server.on('session', session => {
  // Définir altsvc pour l'origine https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // Définir altsvc pour un flux spécifique
  stream.session.altsvc('h2=":8000"', stream.id)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
server.on('session', session => {
  // Définir altsvc pour l'origine https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // Définir altsvc pour un flux spécifique
  stream.session.altsvc('h2=":8000"', stream.id)
})

L’envoi d’une trame ALTSVC avec un ID de flux spécifique indique que le service alternatif est associé à l’origine du Http2Stream donné.

La chaîne alt et la chaîne d’origine doivent contenir uniquement des octets ASCII et sont strictement interprétées comme une séquence d’octets ASCII. La valeur spéciale 'clear' peut être passée pour effacer tout service alternatif précédemment défini pour un domaine donné.

Lorsqu’une chaîne de caractères est passée pour l’argument originOrStream, elle sera analysée comme une URL et l’origine sera dérivée. Par exemple, l’origine de l’URL HTTP 'https://example.org/foo/bar' est la chaîne ASCII 'https://example.org'. Une erreur sera levée si la chaîne donnée ne peut pas être analysée comme une URL ou si une origine valide ne peut pas être dérivée.

Un objet URL, ou tout objet ayant une propriété origin, peut être passé comme originOrStream, auquel cas la valeur de la propriété origin sera utilisée. La valeur de la propriété origin doit être une origine ASCII correctement sérialisée.

Spécification des services alternatifs

Le format du paramètre alt est strictement défini par la RFC 7838 comme une chaîne ASCII contenant une liste de protocoles « alternatifs » séparés par des virgules, associés à un hôte et un port spécifiques.

Par exemple, la valeur 'h2="example.org:81"' indique que le protocole HTTP/2 est disponible sur l'hôte 'example.org' sur le port TCP/IP 81. L'hôte et le port doivent être contenus entre guillemets (").

Plusieurs alternatives peuvent être spécifiées, par exemple : 'h2="example.org:81", h2=":82"'.

L'identificateur de protocole ('h2' dans les exemples) peut être n'importe quel ID de protocole ALPN valide.

La syntaxe de ces valeurs n'est pas validée par l'implémentation Node.js et est transmise telle quelle, fournie par l'utilisateur ou reçue du pair.

serverhttp2session.origin(...origins)

Ajouté dans : v10.12.0

• origins <string> | <URL> | <Object> Une ou plusieurs chaînes d'URL passées comme arguments séparés.

Soumet une trame ORIGIN (telle que définie par la RFC 8336) au client connecté pour annoncer l'ensemble des origines pour lesquelles le serveur est capable de fournir des réponses faisant autorité.

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

Lorsqu'une chaîne est passée comme origin, elle sera analysée comme une URL et l'origine sera dérivée. Par exemple, l'origine de l'URL HTTP 'https://example.org/foo/bar' est la chaîne ASCII 'https://example.org'. Une erreur sera levée si la chaîne donnée ne peut pas être analysée comme une URL ou si une origine valide ne peut pas être dérivée.

Un objet URL, ou tout objet ayant une propriété origin, peut être passé comme origin, auquel cas la valeur de la propriété origin sera utilisée. La valeur de la propriété origin doit être une origine ASCII correctement sérialisée.

Alternativement, l'option origins peut être utilisée lors de la création d'un nouveau serveur HTTP/2 à l'aide de la méthode 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

Ajouté dans : v8.4.0

• Étend : <Http2Session>

Événement : 'altsvc'

Ajouté dans : v9.4.0

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

L'événement 'altsvc' est émis chaque fois qu'un frame ALTSVC est reçu par le client. L'événement est émis avec la valeur ALTSVC, l'origine et l'ID de flux. Si aucune origin n'est fournie dans le frame ALTSVC, origin sera une chaîne vide.

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

Événement : 'origin'

Ajouté dans : v10.12.0

• origins <string[]>

L'événement 'origin' est émis chaque fois qu'un frame ORIGIN est reçu par le client. L'événement est émis avec un tableau de chaînes origin. Le http2session.originSet sera mis à jour pour inclure les origines reçues.

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

L'événement 'origin' n'est émis que lors de l'utilisation d'une connexion TLS sécurisée.

clienthttp2session.request(headers[, options])

Ajouté dans : v8.4.0

• headers <Objet en-têtes HTTP/2>

• options <Objet>

  • endStream <booléen> true si le côté writable de Http2Stream doit être fermé initialement, comme lors de l’envoi d’une requête GET qui ne doit pas attendre de corps de charge utile.
  • exclusive <booléen> Lorsque true et parent identifie un flux parent, le flux créé devient la seule dépendance directe du parent, toutes les autres dépendances existantes devenant dépendantes du flux nouvellement créé. Défaut : false.
  • parent <nombre> Spécifie l’identifiant numérique d’un flux dont le flux nouvellement créé dépend.
  • weight <nombre> Spécifie la dépendance relative d’un flux par rapport à d’autres flux ayant le même parent. La valeur est un nombre compris entre 1 et 256 (inclus).
  • waitForTrailers <booléen> Lorsque true, Http2Stream émettra l’événement 'wantTrailers' après l’envoi de la dernière trame DATA.
  • signal <AbortSignal> Un AbortSignal qui peut être utilisé pour avorter une requête en cours.

• Retourne : <ClientHttp2Stream>

Pour les instances Http2Session clientes HTTP/2 uniquement, http2session.request() crée et renvoie une instance Http2Stream qui peut être utilisée pour envoyer une requête HTTP/2 au serveur connecté.

Lorsqu’une ClientHttp2Session est créée pour la première fois, la socket n’est peut-être pas encore connectée. Si clienthttp2session.request() est appelé pendant ce temps, la requête réelle sera différée jusqu’à ce que la socket soit prête. Si la session est fermée avant que la requête réelle ne soit exécutée, une erreur ERR_HTTP2_GOAWAY_SESSION est levée.

Cette méthode n’est disponible que si http2session.type est égal à 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', () => {
    /* .. */
  })
})

Lorsque l’option options.waitForTrailers est définie, l’événement 'wantTrailers' est émis immédiatement après la mise en file d’attente du dernier bloc de données de charge utile à envoyer. La méthode http2stream.sendTrailers() peut ensuite être appelée pour envoyer des en-têtes de fin au pair.

Lorsque options.waitForTrailers est défini, Http2Stream ne se fermera pas automatiquement lorsque la dernière trame DATA est transmise. Le code utilisateur doit appeler soit http2stream.sendTrailers(), soit http2stream.close() pour fermer Http2Stream.

Lorsque options.signal est défini avec un AbortSignal puis que abort sur le AbortController correspondant est appelé, la requête émettra un événement 'error' avec une erreur AbortError.

Les pseudo-en-têtes :method et :path ne sont pas spécifiés dans headers, ils sont respectivement définis par défaut sur :

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

Classe : Http2Stream

Ajouté dans : v8.4.0

• Étend : <stream.Duplex>

Chaque instance de la classe Http2Stream représente un flux de communication bidirectionnel HTTP/2 sur une instance Http2Session. Une seule Http2Session peut avoir jusqu'à 2^31 - 1 instances Http2Stream au cours de sa durée de vie.

Le code utilisateur ne construira pas directement des instances Http2Stream. Celles-ci sont plutôt créées, gérées et fournies au code utilisateur via l'instance Http2Session. Sur le serveur, les instances Http2Stream sont créées soit en réponse à une requête HTTP entrante (et transmises au code utilisateur via l'événement 'stream'), soit en réponse à un appel à la méthode http2stream.pushStream(). Sur le client, les instances Http2Stream sont créées et renvoyées lorsque la méthode http2session.request() est appelée, ou en réponse à un événement 'push' entrant.

La classe Http2Stream est une base pour les classes ServerHttp2Stream et ClientHttp2Stream, chacune étant utilisée spécifiquement par le serveur ou le client, respectivement.

Toutes les instances Http2Stream sont des flux Duplex. Le côté Writable du Duplex est utilisé pour envoyer des données au pair connecté, tandis que le côté Readable est utilisé pour recevoir les données envoyées par le pair connecté.

L'encodage de caractères texte par défaut pour un Http2Stream est UTF-8. Lorsque vous utilisez un Http2Stream pour envoyer du texte, utilisez l'en-tête 'content-type' pour définir l'encodage des caractères.

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

Cycle de vie Http2Stream

Création

Côté serveur, des instances de ServerHttp2Stream sont créées lorsque :

• Une nouvelle trame HEADERS HTTP/2 avec un ID de flux non utilisé précédemment est reçue ;
• La méthode http2stream.pushStream() est appelée.

Côté client, des instances de ClientHttp2Stream sont créées lorsque la méthode http2session.request() est appelée.

Sur le client, l'instance Http2Stream renvoyée par http2session.request() peut ne pas être immédiatement prête à l'emploi si la Http2Session parente n'a pas encore été entièrement établie. Dans de tels cas, les opérations appelées sur le Http2Stream seront mises en mémoire tampon jusqu'à ce que l'événement 'ready' soit émis. Le code utilisateur devrait rarement, voire jamais, avoir besoin de gérer directement l'événement 'ready'. L'état prêt d'un Http2Stream peut être déterminé en vérifiant la valeur de http2stream.id. Si la valeur est undefined, le flux n'est pas encore prêt à l'emploi.

Destruction

Toutes les instances de Http2Stream sont détruites lorsque :

• Un frame RST_STREAM pour le flux est reçu par le pair connecté, et (pour les flux client uniquement) les données en attente ont été lues.
• La méthode http2stream.close() est appelée, et (pour les flux client uniquement) les données en attente ont été lues.
• Les méthodes http2stream.destroy() ou http2session.destroy() sont appelées.

Lorsqu'une instance Http2Stream est détruite, une tentative sera faite pour envoyer un frame RST_STREAM au pair connecté.

Lorsque l'instance Http2Stream est détruite, l'événement 'close' est émis. Parce que Http2Stream est une instance de stream.Duplex, l'événement 'end' sera également émis si les données du flux sont actuellement en cours de transfert. L'événement 'error' peut également être émis si http2stream.destroy() a été appelé avec une erreur passée en premier argument.

Après que Http2Stream a été détruit, la propriété http2stream.destroyed sera true et la propriété http2stream.rstCode spécifiera le code d'erreur RST_STREAM. L'instance Http2Stream n'est plus utilisable une fois détruite.

Événement : 'aborted'

Ajouté dans : v8.4.0

L'événement 'aborted' est émis chaque fois qu'une instance Http2Stream est anormalement interrompue en milieu de communication. Son auditeur n'attend aucun argument.

L'événement 'aborted' ne sera émis que si le côté inscriptible de Http2Stream n'a pas été terminé.

Événement : 'close'

Ajouté dans : v8.4.0

L'événement 'close' est émis lorsque Http2Stream est détruit. Une fois cet événement émis, l'instance Http2Stream n'est plus utilisable.

Le code d'erreur HTTP/2 utilisé lors de la fermeture du flux peut être récupéré à l'aide de la propriété http2stream.rstCode. Si le code est une valeur autre que NGHTTP2_NO_ERROR (0), un événement 'error' aura également été émis.

Événement : 'error'

Ajouté dans : v8.4.0

• error <Error>

L'événement 'error' est émis lorsqu'une erreur survient lors du traitement d'un Http2Stream.

Événement : 'frameError'

Ajouté dans : v8.4.0

• type <entier> Le type de trame.
• code <entier> Le code d’erreur.
• id <entier> L’ID du flux (ou 0 si la trame n’est pas associée à un flux).

L’événement 'frameError' est émis lorsqu’une erreur se produit lors de la tentative d’envoi d’une trame. Lorsqu’il est appelé, la fonction de gestion recevra un argument entier identifiant le type de trame et un argument entier identifiant le code d’erreur. L’instance Http2Stream sera détruite immédiatement après l’émission de l’événement 'frameError'.

Événement : 'ready'

Ajouté dans : v8.4.0

L’événement 'ready' est émis lorsque le Http2Stream a été ouvert, s’est vu attribuer un id et peut être utilisé. Le gestionnaire n’attend aucun argument.

Événement : 'timeout'

Ajouté dans : v8.4.0

L’événement 'timeout' est émis lorsqu’aucune activité n’est reçue pour ce Http2Stream dans le nombre de millisecondes défini à l’aide de http2stream.setTimeout(). Son gestionnaire n’attend aucun argument.

Événement : 'trailers'

Ajouté dans : v8.4.0

• headers <Objet en-têtes HTTP/2> Un objet décrivant les en-têtes
• flags <nombre> Les indicateurs numériques associés

L’événement 'trailers' est émis lorsqu’un bloc d’en-têtes associé à des champs d’en-têtes de fin est reçu. La fonction de rappel du gestionnaire reçoit l’objet en-têtes HTTP/2 et les indicateurs associés aux en-têtes.

Il est possible que cet événement ne soit pas émis si http2stream.end() est appelé avant la réception des en-têtes de fin et que les données entrantes ne sont pas lues ou écoutées.

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

Événement : 'wantTrailers'

Ajouté dans : v10.0.0

L'événement 'wantTrailers' est émis lorsque le Http2Stream a mis en file d'attente la dernière trame DATA à envoyer sur une trame et que le Http2Stream est prêt à envoyer les en-têtes de fin. Lors de l'initiation d'une requête ou d'une réponse, l'option waitForTrailers doit être définie pour que cet événement soit émis.

http2stream.aborted

Ajouté dans : v8.4.0

• <booléen>

Défini sur true si l'instance Http2Stream a été anormalement interrompue. Lorsqu'il est défini, l'événement 'aborted' aura été émis.

http2stream.bufferSize

Ajouté dans : v11.2.0, v10.16.0

• <nombre>

Cette propriété affiche le nombre de caractères actuellement mis en mémoire tampon pour être écrits. Voir net.Socket.bufferSize pour plus de détails.

http2stream.close(code[, callback])

[Historique]

Version	Modifications
v18.0.0	Le passage d'une fonction de rappel invalide à l'argument callback lève désormais ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v8.4.0	Ajouté dans : v8.4.0

• code <nombre> Entier non signé sur 32 bits identifiant le code d'erreur. Par défaut : http2.constants.NGHTTP2_NO_ERROR (0x00).
• callback <Fonction> Une fonction optionnelle enregistrée pour écouter l'événement 'close'.

Ferme l'instance Http2Stream en envoyant une trame RST_STREAM à l'homologue HTTP/2 connecté.

http2stream.closed

Ajouté dans : v9.4.0

• <booléen>

Défini sur true si l'instance Http2Stream a été fermée.

http2stream.destroyed

Ajouté dans : v8.4.0

• <booléen>

Défini sur true si l'instance Http2Stream a été détruite et n'est plus utilisable.

http2stream.endAfterHeaders

Ajouté dans : v10.11.0

• <booléen>

Défini sur true si l'indicateur END_STREAM a été défini dans l'en-tête de requête ou de réponse reçu, indiquant qu'aucune donnée supplémentaire ne doit être reçue et que le côté lisible de Http2Stream sera fermé.

http2stream.id

Ajouté dans : v8.4.0

• <nombre> | <indéfini>

L'identifiant de flux numérique de cette instance Http2Stream. Défini sur indéfini si l'identifiant de flux n'a pas encore été attribué.

http2stream.pending

Ajouté dans : v9.4.0

• <booléen>

Défini sur true si l'instance Http2Stream n'a pas encore reçu d'identifiant de flux numérique.

http2stream.priority(options)

Ajouté dans : v8.4.0

• options <Objet>
  • exclusive <booléen> Lorsque true et parent identifie un flux parent, ce flux devient la seule dépendance directe du parent, toutes les autres dépendances existantes devenant dépendantes de ce flux. Défaut : false.
  • parent <nombre> Spécifie l'identifiant numérique d'un flux dont ce flux dépend.
  • weight <nombre> Spécifie la dépendance relative d'un flux par rapport à d'autres flux ayant le même parent. La valeur est un nombre compris entre 1 et 256 (inclus).
  • silent <booléen> Lorsque true, modifie la priorité localement sans envoyer d'image PRIORITY au pair connecté.

Met à jour la priorité de cette instance Http2Stream.

http2stream.rstCode

Ajouté dans : v8.4.0

• <nombre>

Défini sur le code d’erreur RST_STREAM [/api/http2#error-codes-for-rst_stream-and-goaway] signalé lorsque le Http2Stream est détruit après avoir reçu une trame RST_STREAM du pair connecté, après un appel à http2stream.close(), ou http2stream.destroy(). Sera undefined si le Http2Stream n’a pas été fermé.

http2stream.sentHeaders

Ajouté dans : v9.5.0

• <Objet en-têtes HTTP/2>

Un objet contenant les en-têtes sortantes envoyées pour ce Http2Stream.

http2stream.sentInfoHeaders

Ajouté dans : v9.5.0

• <Tableau d’objets en-têtes HTTP/2>

Un tableau d’objets contenant les en-têtes informationnelles (supplémentaires) sortantes envoyées pour ce Http2Stream.

http2stream.sentTrailers

Ajouté dans : v9.5.0

• <Objet en-têtes HTTP/2>

Un objet contenant les en-têtes de fin sortantes envoyées pour ce HttpStream.

http2stream.session

Ajouté dans : v8.4.0

• <Http2Session>

Une référence à l’instance Http2Session qui possède ce Http2Stream. La valeur sera undefined après la destruction de l’instance Http2Stream.

http2stream.setTimeout(msecs, callback)

[Historique]

Version	Modifications
v18.0.0	Passer un rappel invalide à l’argument callback lève maintenant ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v8.4.0	Ajouté dans : v8.4.0

• msecs <nombre>
• callback <Fonction>

ESM

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

// Annuler le flux s’il n’y a pas d’activité après 5 secondes
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': '/' })

// Annuler le flux s’il n’y a pas d’activité après 5 secondes
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

http2stream.state

Ajouté dans : v8.4.0

Fournit des informations diverses sur l’état actuel de Http2Stream.

• <Objet>
  • localWindowSize <nombre> Le nombre d’octets que le pair connecté peut envoyer pour ce Http2Stream sans recevoir de WINDOW_UPDATE.
  • state <nombre> Un indicateur spécifiant l’état actuel de bas niveau de Http2Stream tel que déterminé par nghttp2.
  • localClose <nombre> 1 si ce Http2Stream a été fermé localement.
  • remoteClose <nombre> 1 si ce Http2Stream a été fermé à distance.
  • sumDependencyWeight <nombre> Le poids total de toutes les instances Http2Stream qui dépendent de ce Http2Stream comme spécifié à l’aide des trames PRIORITY.
  • weight <nombre> Le poids de priorité de ce Http2Stream.

Un état actuel de ce Http2Stream.

http2stream.sendTrailers(headers)

Ajouté dans : v10.0.0

• headers <Objet en-têtes HTTP/2>

Envoie une trame HEADERS finale au pair HTTP/2 connecté. Cette méthode entraînera la fermeture immédiate de Http2Stream et ne doit être appelée qu’après l’émission de l’événement 'wantTrailers'. Lors de l’envoi d’une requête ou d’une réponse, l’option options.waitForTrailers doit être définie afin de maintenir Http2Stream ouvert après la trame DATA finale afin que les trames finales puissent être envoyées.

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

La spécification HTTP/1 interdit aux trames finales de contenir des champs d’en-tête pseudo-HTTP/2 (par exemple, ':method', ':path', etc.).

Classe : ClientHttp2Stream

Ajouté dans : v8.4.0

• Étend <Http2Stream>

La classe ClientHttp2Stream est une extension de Http2Stream utilisée exclusivement sur les clients HTTP/2. Les instances Http2Stream sur le client fournissent des événements tels que 'response' et 'push' qui ne sont pertinents que sur le client.

Événement : 'continue'

Ajouté dans : v8.5.0

Émis lorsque le serveur envoie un statut 100 Continue, généralement parce que la requête contenait Expect: 100-continue. Il s'agit d'une instruction indiquant que le client doit envoyer le corps de la requête.

Événement : 'headers'

Ajouté dans : v8.4.0

• headers <Objet en-têtes HTTP/2>
• flags <nombre>

L'événement 'headers' est émis lorsqu'un bloc supplémentaire d'en-têtes est reçu pour un flux, par exemple lorsqu'un bloc d'en-têtes d'information 1xx est reçu. La fonction de rappel de l'écouteur reçoit l'objet Objet en-têtes HTTP/2 et les indicateurs associés aux en-têtes.

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

Événement : 'push'

Ajouté dans : v8.4.0

• headers <Objet en-têtes HTTP/2>
• flags <nombre>

L'événement 'push' est émis lorsque les en-têtes de réponse pour un flux Server Push sont reçus. La fonction de rappel de l'écouteur reçoit l'objet Objet en-têtes HTTP/2 et les indicateurs associés aux en-têtes.

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

Événement : 'response'

Ajouté dans : v8.4.0

• headers <Objet en-têtes HTTP/2>
• flags <nombre>

L'événement 'response' est émis lorsqu'un frame HEADERS de réponse a été reçu pour ce flux depuis le serveur HTTP/2 connecté. L'écouteur est appelé avec deux arguments : un Object contenant l'objet Objet en-têtes HTTP/2 reçu et les indicateurs associés aux en-têtes.

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

Ajouté dans : v8.4.0

• Étend : <Http2Stream>

La classe ServerHttp2Stream est une extension de Http2Stream utilisée exclusivement sur les serveurs HTTP/2. Les instances Http2Stream sur le serveur fournissent des méthodes supplémentaires telles que http2stream.pushStream() et http2stream.respond() qui ne sont pertinentes que sur le serveur.

http2stream.additionalHeaders(headers)

Ajouté dans : v8.4.0

• headers <Objet en-têtes HTTP/2>

Envoie un frame HEADERS d'information supplémentaire au pair HTTP/2 connecté.

http2stream.headersSent

Ajouté dans : v8.4.0

• <booléen>

Vrai si les en-têtes ont été envoyés, faux sinon (lecture seule).

http2stream.pushAllowed

Ajouté dans : v8.4.0

• <booléen>

Propriété en lecture seule mappée au drapeau SETTINGS_ENABLE_PUSH du frame SETTINGS le plus récent du client distant. Sera true si le pair distant accepte les flux push, false sinon. Les paramètres sont les mêmes pour chaque Http2Stream dans la même Http2Session.

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

[Historique]

Version	Modifications
v18.0.0	Passer un callback invalide à l'argument callback lève maintenant ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v8.4.0	Ajouté dans : v8.4.0

• headers <Objet en-têtes HTTP/2>

• options <Objet>

  • exclusive <booléen> Lorsque true et parent identifie un flux parent, le flux créé devient la seule dépendance directe du parent, toutes les autres dépendances existantes devenant dépendantes du flux nouvellement créé. Défaut : false.
  • parent <nombre> Spécifie l'identifiant numérique d'un flux dont le flux nouvellement créé dépend.

• callback <Fonction> Callback appelé une fois que le flux push a été initié.

  • err <Erreur>
  • pushStream <ServerHttp2Stream> L'objet pushStream renvoyé.
  • headers <Objet en-têtes HTTP/2> Objet en-têtes avec lequel pushStream a été initié.

Initie un flux push. Le callback est invoqué avec la nouvelle instance Http2Stream créée pour le flux push passé en deuxième argument, ou une Erreur passée en premier argument.

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

La définition du poids d'un flux push n'est pas autorisée dans le frame HEADERS. Passez une valeur weight à http2stream.priority avec l'option silent définie sur true pour activer l'équilibrage de la bande passante côté serveur entre les flux concurrents.

L'appel de http2stream.pushStream() depuis un flux push n'est pas autorisé et lèvera une erreur.

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

[Historique]

Version	Modifications
v14.5.0, v12.19.0	Autoriser la définition explicite des en-têtes de date.
v8.4.0	Ajouté dans : v8.4.0

• headers <Objet en-têtes HTTP/2>
• options <Objet>
  • endStream <booléen> Définir sur true pour indiquer que la réponse n'inclura pas de données de charge utile.
  • waitForTrailers <booléen> Lorsque true, Http2Stream émettra l'événement 'wantTrailers' après l'envoi de la dernière trame 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')
})

Initie une réponse. Lorsque l'option options.waitForTrailers est définie, l'événement 'wantTrailers' sera émis immédiatement après la mise en file d'attente du dernier bloc de données de charge utile à envoyer. La méthode http2stream.sendTrailers() peut ensuite être utilisée pour envoyer des champs d'en-tête de fin à l'homologue.

Lorsque options.waitForTrailers est défini, Http2Stream ne se fermera pas automatiquement lorsque la dernière trame DATA est transmise. Le code utilisateur doit appeler soit http2stream.sendTrailers(), soit http2stream.close() pour fermer 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]])

[Historique]

Version	Modifications
v14.5.0, v12.19.0	Autoriser la définition explicite des en-têtes de date.
v12.12.0	L'option fd peut maintenant être un FileHandle.
v10.0.0	Tout descripteur de fichier lisible, pas nécessairement pour un fichier régulier, est maintenant supporté.
v8.4.0	Ajouté dans : v8.4.0

• fd <nombre> | <FileHandle> Un descripteur de fichier lisible.
• headers <Objet en-têtes HTTP/2>
• options <Objet>
  • statCheck <Fonction>
  • waitForTrailers <booléen> Lorsque true, le Http2Stream émettra l'événement 'wantTrailers' après que la dernière trame DATA a été envoyée.
  • offset <nombre> La position de décalage à partir de laquelle commencer la lecture.
  • length <nombre> La quantité de données à envoyer depuis le fd.

Initie une réponse dont les données sont lues à partir du descripteur de fichier donné. Aucune validation n'est effectuée sur le descripteur de fichier donné. Si une erreur survient lors de la tentative de lecture de données à l'aide du descripteur de fichier, le Http2Stream sera fermé à l'aide d'une trame RST_STREAM utilisant le code INTERNAL_ERROR standard.

Lorsqu'il est utilisé, l'interface Duplex de l'objet Http2Stream sera automatiquement fermée.

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

La fonction options.statCheck facultative peut être spécifiée pour donner à un code utilisateur la possibilité de définir des en-têtes de contenu supplémentaires en fonction des détails fs.Stat du fd donné. Si la fonction statCheck est fournie, la méthode http2stream.respondWithFD() effectuera un appel fs.fstat() pour collecter des détails sur le descripteur de fichier fourni.

Les options offset et length peuvent être utilisées pour limiter la réponse à un sous-ensemble de plage spécifique. Cela peut être utilisé, par exemple, pour prendre en charge les requêtes HTTP Range.

Le descripteur de fichier ou FileHandle n'est pas fermé lorsque le flux est fermé, il devra donc être fermé manuellement une fois qu'il n'est plus nécessaire. L'utilisation du même descripteur de fichier simultanément pour plusieurs flux n'est pas prise en charge et peut entraîner une perte de données. La réutilisation d'un descripteur de fichier après la fin d'un flux est prise en charge.

Lorsque l'option options.waitForTrailers est définie, l'événement 'wantTrailers' sera émis immédiatement après la mise en file d'attente du dernier bloc de données de charge utile à envoyer. La méthode http2stream.sendTrailers() peut ensuite être utilisée pour envoyer des champs d'en-tête de fin à l'homologue.

Lorsque options.waitForTrailers est défini, le Http2Stream ne se fermera pas automatiquement lorsque la dernière trame DATA est transmise. Le code utilisateur doit appeler soit http2stream.sendTrailers(), soit http2stream.close() pour fermer le 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]])

[Historique]

Version	Modifications
v14.5.0, v12.19.0	Autorise la définition explicite des en-têtes de date.
v10.0.0	Tout fichier lisible, pas nécessairement un fichier régulier, est désormais pris en charge.
v8.4.0	Ajouté dans : v8.4.0

• path <string> | <Buffer> | <URL>
• headers <Objet En-têtes HTTP/2>
• options <Objet>
  • statCheck <Fonction>
  • onError <Fonction> Fonction de rappel invoquée en cas d'erreur avant l'envoi.
  • waitForTrailers <booléen> Lorsque true, le Http2Stream émettra l'événement 'wantTrailers' après l'envoi de la dernière trame DATA.
  • offset <nombre> La position de décalage à partir de laquelle commencer la lecture.
  • length <nombre> La quantité de données à envoyer depuis le descripteur de fichier.

Envoie un fichier régulier comme réponse. Le path doit spécifier un fichier régulier, sinon un événement 'error' sera émis sur l'objet Http2Stream.

Lorsqu'il est utilisé, l'interface Duplex de l'objet Http2Stream sera automatiquement fermée.

La fonction options.statCheck optionnelle peut être spécifiée pour donner au code utilisateur la possibilité de définir des en-têtes de contenu supplémentaires en fonction des détails fs.Stat du fichier donné :

Si une erreur se produit lors de la tentative de lecture des données du fichier, le Http2Stream sera fermé à l'aide d'une trame RST_STREAM utilisant le code INTERNAL_ERROR standard. Si la fonction de rappel onError est définie, elle sera appelée. Sinon, le flux sera détruit.

Exemple utilisant un chemin de fichier :

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() peut lever une exception si le flux a été détruit par
    // l'autre côté.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // Gérer réellement l'erreur.
      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() peut lever une exception si le flux a été détruit par
    // l'autre côté.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // Gérer réellement l'erreur.
      console.error(err)
    }
    stream.end()
  }

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

La fonction options.statCheck peut également être utilisée pour annuler l'opération d'envoi en retournant false. Par exemple, une requête conditionnelle peut vérifier les résultats stat pour déterminer si le fichier a été modifié afin de renvoyer une réponse 304 appropriée :

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    // Vérifier les stat ici...
    stream.respond({ ':status': 304 })
    return false // Annuler l'opération d'envoi
  }
  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) {
    // Vérifier les stat ici...
    stream.respond({ ':status': 304 })
    return false // Annuler l'opération d'envoi
  }
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck })
})

Le champ d'en-tête content-length sera automatiquement défini.

Les options offset et length peuvent être utilisées pour limiter la réponse à un sous-ensemble de plage spécifique. Cela peut être utilisé, par exemple, pour prendre en charge les requêtes HTTP Range.

La fonction options.onError peut également être utilisée pour gérer toutes les erreurs qui pourraient survenir avant le début de la livraison du fichier. Le comportement par défaut consiste à détruire le flux.

Lorsque l'option options.waitForTrailers est définie, l'événement 'wantTrailers' sera émis immédiatement après la mise en file d'attente du dernier bloc de données de charge utile à envoyer. La méthode http2stream.sendTrailers() peut ensuite être utilisée pour envoyer des champs d'en-tête de fin à l'homologue.

Lorsque options.waitForTrailers est défini, le Http2Stream ne se fermera pas automatiquement lorsque la dernière trame DATA est transmise. Le code utilisateur doit appeler http2stream.sendTrailers() ou http2stream.close() pour fermer le 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: 'some value to send' })
  })
})

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: 'some value to send' })
  })
})

Classe : Http2Server

Ajouté dans : v8.4.0

• Étend : <net.Server>

Les instances de Http2Server sont créées à l'aide de la fonction http2.createServer(). La classe Http2Server n'est pas exportée directement par le module node:http2.

Événement : 'checkContinue'

Ajouté dans : v8.5.0

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

Si un écouteur 'request' est enregistré ou si http2.createServer() se voit attribuer une fonction de rappel, l'événement 'checkContinue' est émis chaque fois qu'une requête avec un en-tête HTTP Expect: 100-continue est reçue. Si cet événement n'est pas écouté, le serveur répondra automatiquement avec le statut 100 Continue le cas échéant.

La gestion de cet événement implique d'appeler response.writeContinue() si le client doit continuer à envoyer le corps de la requête, ou de générer une réponse HTTP appropriée (par exemple, 400 Mauvaise requête) si le client ne doit pas continuer à envoyer le corps de la requête.

Lorsque cet événement est émis et traité, l'événement 'request' ne sera pas émis.

Événement : 'connection'

Ajouté dans : v8.4.0

• socket <stream.Duplex>

Cet événement est émis lorsqu'un nouveau flux TCP est établi. socket est généralement un objet de type net.Socket. Généralement, les utilisateurs ne voudront pas accéder à cet événement.

Cet événement peut également être émis explicitement par les utilisateurs pour injecter des connexions dans le serveur HTTP. Dans ce cas, tout flux Duplex peut être passé.

Événement : 'request'

Ajouté dans : v8.4.0

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

Émis à chaque requête. Il peut y avoir plusieurs requêtes par session. Voir l'API de compatibilité.

Événement : 'session'

Ajouté dans : v8.4.0

• session <ServerHttp2Session>

L'événement 'session' est émis lorsqu'un nouvel objet Http2Session est créé par le serveur Http2Server.

Événement : 'sessionError'

Ajouté dans : v8.4.0

• error <Error>
• session <ServerHttp2Session>

L'événement 'sessionError' est émis lorsqu'un événement 'error' est émis par un objet Http2Session associé au serveur Http2Server.

Événement : 'stream'

Ajouté dans : v8.4.0

• stream <Http2Stream> Une référence au flux
• headers <Objet en-têtes HTTP/2> Un objet décrivant les en-têtes
• flags <nombre> Les indicateurs numériques associés
• rawHeaders <Tableau> Un tableau contenant les noms bruts des en-têtes suivis de leurs valeurs respectives.

L'événement 'stream' est émis lorsqu'un événement 'stream' a été émis par un objet Http2Session associé au serveur.

Voir aussi l'événement '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')
})

Événement : 'timeout'

[Historique]

Version	Modifications
v13.0.0	Le délai d'expiration par défaut est passé de 120 s à 0 (pas de délai d'expiration).
v8.4.0	Ajouté dans : v8.4.0

L'événement 'timeout' est émis lorsqu'il n'y a aucune activité sur le serveur pendant un nombre donné de millisecondes défini à l'aide de http2server.setTimeout(). Défaut : 0 (pas de délai d'expiration)

server.close([callback])

Ajouté dans : v8.4.0

• callback <Function>

Empêche le serveur d'établir de nouvelles sessions. Cela n'empêche pas la création de nouveaux flux de requêtes en raison de la nature persistante des sessions HTTP/2. Pour arrêter le serveur en douceur, appelez http2session.close() sur toutes les sessions actives.

Si callback est fourni, il n'est pas appelé tant que toutes les sessions actives n'ont pas été fermées, bien que le serveur ait déjà cessé d'autoriser de nouvelles sessions. Voir net.Server.close() pour plus de détails.

server[Symbol.asyncDispose]()

Ajouté dans : v20.4.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Appelle server.close() et renvoie une promesse qui est satisfaite lorsque le serveur est fermé.

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

[Historique]

Version	Modifications
v18.0.0	La transmission d'une fonction de rappel invalide à l'argument callback lève désormais l'erreur ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v13.0.0	Le délai d'expiration par défaut est passé de 120 s à 0 (pas de délai d'expiration).
v8.4.0	Ajouté dans : v8.4.0

• msecs <number> Défaut : 0 (pas de délai d'expiration)
• callback <Function>
• Retourne : <Http2Server>

Utilisé pour définir la valeur du délai d'expiration des requêtes du serveur http2, et définit une fonction de rappel qui est appelée lorsqu'il n'y a aucune activité sur le Http2Server après msecs millisecondes.

La fonction de rappel donnée est enregistrée comme écouteur sur l'événement 'timeout'.

Si callback n'est pas une fonction, une nouvelle erreur ERR_INVALID_ARG_TYPE sera levée.

server.timeout

[Historique]

Version	Modifications
v13.0.0	Le délai d'expiration par défaut est passé de 120 s à 0 (pas de délai d'expiration).
v8.4.0	Ajouté dans : v8.4.0

• <nombre> Délai d'expiration en millisecondes. Défaut : 0 (pas de délai d'expiration)

Le nombre de millisecondes d'inactivité avant qu'un socket ne soit présumé avoir expiré.

Une valeur de 0 désactivera le comportement de délai d'expiration sur les connexions entrantes.

La logique de délai d'expiration du socket est configurée lors de la connexion. Ainsi, la modification de cette valeur n'affecte que les nouvelles connexions au serveur, et non les connexions existantes.

server.updateSettings([settings])

Ajouté dans : v15.1.0, v14.17.0

• settings <Objet de paramètres HTTP/2>

Utilisé pour mettre à jour le serveur avec les paramètres fournis.

Lève ERR_HTTP2_INVALID_SETTING_VALUE pour les valeurs settings invalides.

Lève ERR_INVALID_ARG_TYPE pour un argument settings invalide.

Classe : Http2SecureServer

Ajouté dans : v8.4.0

• Étend : <tls.Server>

Les instances de Http2SecureServer sont créées à l'aide de la fonction http2.createSecureServer(). La classe Http2SecureServer n'est pas exportée directement par le module node:http2.

Événement : 'checkContinue'

Ajouté dans : v8.5.0

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

Si un écouteur 'request' est enregistré ou si http2.createSecureServer() reçoit une fonction de rappel, l'événement 'checkContinue' est émis chaque fois qu'une requête avec un en-tête HTTP Expect: 100-continue est reçue. Si cet événement n'est pas écouté, le serveur répondra automatiquement avec le statut 100 Continue selon le cas.

La gestion de cet événement implique d'appeler response.writeContinue() si le client doit continuer à envoyer le corps de la requête, ou de générer une réponse HTTP appropriée (par exemple, 400 Mauvaise requête) si le client ne doit pas continuer à envoyer le corps de la requête.

Lorsque cet événement est émis et géré, l'événement 'request' ne sera pas émis.

Événement : 'connection'

Ajouté dans : v8.4.0

• socket <stream.Duplex>

Cet événement est émis lorsqu'un nouveau flux TCP est établi, avant le début du handshake TLS. socket est généralement un objet de type net.Socket. Habituellement, les utilisateurs ne voudront pas accéder à cet événement.

Cet événement peut également être émis explicitement par les utilisateurs pour injecter des connexions dans le serveur HTTP. Dans ce cas, tout flux Duplex peut être passé.

Événement : 'request'

Ajouté dans : v8.4.0

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

Émis à chaque requête. Il peut y avoir plusieurs requêtes par session. Voir l'API de compatibilité.

Événement : 'session'

Ajouté dans : v8.4.0

• session <ServerHttp2Session>

L'événement 'session' est émis lorsqu'une nouvelle Http2Session est créée par Http2SecureServer.

Événement : 'sessionError'

Ajouté dans : v8.4.0

• error <Error>
• session <ServerHttp2Session>

L'événement 'sessionError' est émis lorsqu'un événement 'error' est émis par un objet Http2Session associé à Http2SecureServer.

Événement : 'stream'

Ajouté dans : v8.4.0

• stream <Http2Stream> Une référence au flux
• headers <Objet en-têtes HTTP/2> Un objet décrivant les en-têtes
• flags <nombre> Les indicateurs numériques associés
• rawHeaders <Tableau> Un tableau contenant les noms d'en-têtes bruts suivis de leurs valeurs respectives.

L'événement 'stream' est émis lorsqu'un événement 'stream' a été émis par une Http2Session associée au serveur.

Voir aussi l'événement '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')
})

Événement : 'timeout'

Ajouté dans : v8.4.0

L'événement 'timeout' est émis lorsqu'il n'y a aucune activité sur le serveur pendant un nombre de millisecondes donné, défini à l'aide de http2secureServer.setTimeout(). Valeur par défaut : 2 minutes.

Événement : 'unknownProtocol'

[Historique]

Version	Modifications
v19.0.0	Cet événement ne sera émis que si le client n'a pas transmis d'extension ALPN lors de l'échange de clés TLS.
v8.4.0	Ajouté dans : v8.4.0

• socket <stream.Duplex>

L'événement 'unknownProtocol' est émis lorsqu'un client qui se connecte ne parvient pas à négocier un protocole autorisé (c'est-à-dire HTTP/2 ou HTTP/1.1). Le gestionnaire d'événements reçoit le socket pour le traitement. Si aucun écouteur n'est enregistré pour cet événement, la connexion est interrompue. Un délai d'attente peut être spécifié à l'aide de l'option 'unknownProtocolTimeout' passée à http2.createSecureServer().

Dans les versions antérieures de Node.js, cet événement était émis si allowHTTP1 est false et que, pendant l'échange de clés TLS, le client n'envoie pas d'extension ALPN ou envoie une extension ALPN qui n'inclut pas HTTP/2 (h2). Les versions plus récentes de Node.js n'émettent cet événement que si allowHTTP1 est false et que le client n'envoie pas d'extension ALPN. Si le client envoie une extension ALPN qui n'inclut pas HTTP/2 (ou HTTP/1.1 si allowHTTP1 est true), l'échange de clés TLS échouera et aucune connexion sécurisée ne sera établie.

Voir l'API de compatibilité.

server.close([callback])

Ajouté dans : v8.4.0

• callback <Function>

Empêche le serveur d'établir de nouvelles sessions. Cela n'empêche pas la création de nouveaux flux de requêtes en raison de la nature persistante des sessions HTTP/2. Pour arrêter correctement le serveur, appelez http2session.close() sur toutes les sessions actives.

Si callback est fourni, il n'est pas appelé tant que toutes les sessions actives n'ont pas été fermées, bien que le serveur ait déjà cessé d'autoriser de nouvelles sessions. Voir tls.Server.close() pour plus de détails.

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

[Historique]

Version	Modifications
v18.0.0	Le passage d'une fonction de rappel invalide à l'argument callback lève désormais l'erreur ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v8.4.0	Ajouté dans : v8.4.0

• msecs <nombre> Valeur par défaut : 120000 (2 minutes)
• callback <Fonction>
• Retourne : <Http2SecureServer>

Utilisé pour définir la valeur de délai d'expiration des requêtes du serveur sécurisé http2, et définit une fonction de rappel qui est appelée lorsqu'il n'y a aucune activité sur le Http2SecureServer après msecs millisecondes.

La fonction de rappel donnée est enregistrée comme écouteur sur l'événement 'timeout'.

Si callback n'est pas une fonction, une nouvelle erreur ERR_INVALID_ARG_TYPE sera levée.

server.timeout

[Historique]

Version	Modifications
v13.0.0	Le délai d'expiration par défaut est passé de 120 s à 0 (pas de délai d'expiration).
v8.4.0	Ajouté dans : v8.4.0

• <nombre> Délai d'expiration en millisecondes. Valeur par défaut : 0 (pas de délai d'expiration)

Le nombre de millisecondes d'inactivité avant qu'un socket ne soit présumé avoir expiré.

Une valeur de 0 désactivera le comportement de délai d'expiration sur les connexions entrantes.

La logique de délai d'expiration du socket est configurée lors de la connexion. Ainsi, la modification de cette valeur n'affecte que les nouvelles connexions au serveur, et non les connexions existantes.

server.updateSettings([settings])

Ajouté dans : v15.1.0, v14.17.0

• settings <Objet Paramètres HTTP/2>

Utilisé pour mettre à jour le serveur avec les paramètres fournis.

Lève l'erreur ERR_HTTP2_INVALID_SETTING_VALUE pour les valeurs settings invalides.

Lève l'erreur ERR_INVALID_ARG_TYPE pour l'argument settings invalide.

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

[Historique]

Version	Modifications
v23.0.0	Ajout de streamResetBurst et streamResetRate.
v13.0.0	PADDING_STRATEGY_CALLBACK est devenu équivalent à PADDING_STRATEGY_ALIGNED, et selectPadding a été supprimé.
v13.3.0, v12.16.0	Ajout de l'option maxSessionRejectedStreams avec une valeur par défaut de 100.
v13.3.0, v12.16.0	Ajout de l'option maxSessionInvalidFrames avec une valeur par défaut de 1000.
v12.4.0	Le paramètre options prend désormais en charge les options net.createServer().
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Ajout de l'option unknownProtocolTimeout avec une valeur par défaut de 10000.
v14.4.0, v12.18.0, v10.21.0	Ajout de l'option maxSettings avec une valeur par défaut de 32.
v9.6.0	Ajout des options Http1IncomingMessage et Http1ServerResponse.
v8.9.3	Ajout de l'option maxOutstandingPings avec une limite par défaut de 10.
v8.9.3	Ajout de l'option maxHeaderListPairs avec une limite par défaut de 128 paires d'en-têtes.
v8.4.0	Ajouté dans : v8.4.0

• options <Objet>

  • maxDeflateDynamicTableSize <nombre> Définit la taille maximale de la table dynamique pour la déflation des champs d'en-tête. Valeur par défaut : 4 Ko.

  • maxSettings <nombre> Définit le nombre maximal d'entrées de paramètres par trame SETTINGS. La valeur minimale autorisée est 1. Valeur par défaut : 32.

  • maxSessionMemory<nombre> Définit la mémoire maximale que le Http2Session est autorisé à utiliser. La valeur est exprimée en mégaoctets, par exemple, 1 égale 1 mégaoctet. La valeur minimale autorisée est 1. Il s'agit d'une limite basée sur le crédit. Les Http2Stream existants peuvent dépasser cette limite, mais de nouveaux instances Http2Stream seront rejetées tant que cette limite est dépassée. Le nombre actuel de sessions Http2Stream, l'utilisation actuelle de la mémoire des tables de compression d'en-tête, les données en attente d'envoi et les trames PING et SETTINGS non accusées sont toutes comptabilisées dans la limite actuelle. Valeur par défaut : 10.

  • maxHeaderListPairs <nombre> Définit le nombre maximal d'entrées d'en-tête. Ceci est similaire à server.maxHeadersCount ou request.maxHeadersCount dans le module node:http. La valeur minimale est 4. Valeur par défaut : 128.

  • maxOutstandingPings <nombre> Définit le nombre maximal de pings en attente non accusés. Valeur par défaut : 10.

  • maxSendHeaderBlockLength <nombre> Définit la taille maximale autorisée pour un bloc d'en-têtes compressés et sérialisés. Les tentatives d'envoi d'en-têtes dépassant cette limite entraîneront l'émission d'un événement 'frameError' et la fermeture et la destruction du flux. Bien que cela définisse la taille maximale autorisée pour l'ensemble du bloc d'en-têtes, nghttp2 (la bibliothèque http2 interne) a une limite de 65536 pour chaque paire clé/valeur décompressée.

  • paddingStrategy <nombre> La stratégie utilisée pour déterminer la quantité de rembourrage à utiliser pour les trames HEADERS et DATA. Valeur par défaut : http2.constants.PADDING_STRATEGY_NONE. La valeur peut être l'une des suivantes :

  • http2.constants.PADDING_STRATEGY_NONE: Aucun rembourrage n'est appliqué.

  • http2.constants.PADDING_STRATEGY_MAX: La quantité maximale de rembourrage, déterminée par l'implémentation interne, est appliquée.

  • http2.constants.PADDING_STRATEGY_ALIGNED: Tente d'appliquer suffisamment de rembourrage pour garantir que la longueur totale de la trame, y compris l'en-tête de 9 octets, est un multiple de 8. Pour chaque trame, il existe un nombre maximal d'octets de rembourrage autorisé qui est déterminé par l'état actuel du contrôle de flux et les paramètres. Si ce maximum est inférieur à la quantité calculée nécessaire pour garantir l'alignement, le maximum est utilisé et la longueur totale de la trame n'est pas nécessairement alignée sur 8 octets.

  • peerMaxConcurrentStreams <nombre> Définit le nombre maximal de flux simultanés pour le pair distant comme si une trame SETTINGS avait été reçue. Sera remplacé si le pair distant définit sa propre valeur pour maxConcurrentStreams. Valeur par défaut : 100.

  • maxSessionInvalidFrames <entier> Définit le nombre maximal de trames invalides qui seront tolérées avant que la session ne soit fermée. Valeur par défaut : 1000.

  • maxSessionRejectedStreams <entier> Définit le nombre maximal de flux rejetés lors de la création qui seront tolérés avant que la session ne soit fermée. Chaque rejet est associé à une erreur NGHTTP2_ENHANCE_YOUR_CALM qui devrait indiquer au pair de ne plus ouvrir de flux. Par conséquent, continuer à ouvrir des flux est considéré comme un signe de mauvais comportement du pair. Valeur par défaut : 100.

  • settings <Objet Paramètres HTTP/2> Les paramètres initiaux à envoyer au pair distant lors de la connexion.

  • streamResetBurst <nombre> et streamResetRate <nombre> Définit la limite de débit pour la réinitialisation du flux entrant (trame RST_STREAM). Les deux paramètres doivent être définis pour avoir un effet, et leurs valeurs par défaut sont respectivement 1000 et 33.

  • remoteCustomSettings <Tableau> Le tableau de valeurs entières détermine les types de paramètres inclus dans la propriété CustomSettings des remoteSettings reçus. Veuillez consulter la propriété CustomSettings de l'objet Http2Settings pour plus d'informations sur les types de paramètres autorisés.

  • Http1IncomingMessage <http.IncomingMessage> Spécifie la classe IncomingMessage à utiliser pour la solution de secours HTTP/1. Utile pour étendre le http.IncomingMessage d'origine. Valeur par défaut : http.IncomingMessage.

  • Http1ServerResponse <http.ServerResponse> Spécifie la classe ServerResponse à utiliser pour la solution de secours HTTP/1. Utile pour étendre le http.ServerResponse d'origine. Valeur par défaut : http.ServerResponse.

  • Http2ServerRequest <http2.Http2ServerRequest> Spécifie la classe Http2ServerRequest à utiliser. Utile pour étendre le Http2ServerRequest d'origine. Valeur par défaut : Http2ServerRequest.

  • Http2ServerResponse <http2.Http2ServerResponse> Spécifie la classe Http2ServerResponse à utiliser. Utile pour étendre le Http2ServerResponse d'origine. Valeur par défaut : Http2ServerResponse.

  • unknownProtocolTimeout <nombre> Spécifie un délai d'expiration en millisecondes pendant lequel un serveur doit attendre lorsqu'un événement 'unknownProtocol' est émis. Si le socket n'a pas été détruit à ce moment-là, le serveur le détruira. Valeur par défaut : 10000.

  • ... : Toute option net.createServer() peut être fournie.

• onRequestHandler <Fonction> Voir API de compatibilité

• Retourne : <Http2Server>

Retourne une instance net.Server qui crée et gère les instances Http2Session.

Comme il n'existe aucun navigateur connu qui prenne en charge le HTTP/2 non chiffré, l'utilisation de http2.createSecureServer() est nécessaire lors de la communication avec des clients de navigateur.

ESM

import { createServer } from 'node:http2'

// Création d'un serveur HTTP/2 non chiffré.
// Comme il n'existe aucun navigateur connu qui prenne en charge
// le HTTP/2 non chiffré, l'utilisation de `createSecureServer()`
// est nécessaire lors de la communication avec des clients de navigateur.
const server = createServer()

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

server.listen(8000)

CJS

const http2 = require('node:http2')

// Création d'un serveur HTTP/2 non chiffré.
// Comme il n'existe aucun navigateur connu qui prenne en charge
// le HTTP/2 non chiffré, l'utilisation de `http2.createSecureServer()`
// est nécessaire lors de la communication avec des clients de navigateur.
const server = http2.createServer()

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

server.listen(8000)

http2.createSecureServer(options[, onRequestHandler])

[Historique]

Version	Modifications
v13.0.0	PADDING_STRATEGY_CALLBACK est devenu équivalent à PADDING_STRATEGY_ALIGNED, et selectPadding a été supprimé.
v13.3.0, v12.16.0	Ajout de l'option maxSessionRejectedStreams avec une valeur par défaut de 100.
v13.3.0, v12.16.0	Ajout de l'option maxSessionInvalidFrames avec une valeur par défaut de 1000.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Ajout de l'option unknownProtocolTimeout avec une valeur par défaut de 10000.
v14.4.0, v12.18.0, v10.21.0	Ajout de l'option maxSettings avec une valeur par défaut de 32.
v10.12.0	Ajout de l'option origins pour envoyer automatiquement une trame ORIGIN au démarrage de Http2Session.
v8.9.3	Ajout de l'option maxOutstandingPings avec une limite par défaut de 10.
v8.9.3	Ajout de l'option maxHeaderListPairs avec une limite par défaut de 128 paires d'en-têtes.
v8.4.0	Ajouté dans : v8.4.0

• options <Objet>

  • allowHTTP1 <booléen> Les connexions clientes entrantes qui ne prennent pas en charge HTTP/2 seront rétrogradées à HTTP/1.x si cette option est définie sur true. Voir l'événement 'unknownProtocol'. Voir négociation ALPN. Valeur par défaut : false.

  • maxDeflateDynamicTableSize <nombre> Définit la taille maximale de la table dynamique pour la déflation des champs d'en-tête. Valeur par défaut : 4 Ko.

  • maxSettings <nombre> Définit le nombre maximal d'entrées de paramètres par trame SETTINGS. La valeur minimale autorisée est 1. Valeur par défaut : 32.

  • maxSessionMemory<nombre> Définit la mémoire maximale que Http2Session est autorisé à utiliser. La valeur est exprimée en mégaoctets, par exemple, 1 équivaut à 1 mégaoctet. La valeur minimale autorisée est 1. Il s'agit d'une limite basée sur le crédit, les Http2Stream existants peuvent dépasser cette limite, mais de nouvelles instances Http2Stream seront rejetées tant que cette limite est dépassée. Le nombre actuel de sessions Http2Stream, l'utilisation actuelle de la mémoire des tables de compression d'en-tête, les données actuellement mises en file d'attente pour être envoyées et les trames PING et SETTINGS non accusées sont toutes comptabilisées dans la limite actuelle. Valeur par défaut : 10.

  • maxHeaderListPairs <nombre> Définit le nombre maximal d'entrées d'en-tête. Ceci est similaire à server.maxHeadersCount ou request.maxHeadersCount dans le module node:http. La valeur minimale est 4. Valeur par défaut : 128.

  • maxOutstandingPings <nombre> Définit le nombre maximal de pings en attente non accusés. Valeur par défaut : 10.

  • maxSendHeaderBlockLength <nombre> Définit la taille maximale autorisée pour un bloc d'en-têtes compressé et sérialisé. Les tentatives d'envoi d'en-têtes dépassant cette limite entraîneront l'émission d'un événement 'frameError' et la fermeture et la destruction du flux.

  • paddingStrategy <nombre> Stratégie utilisée pour déterminer la quantité de rembourrage à utiliser pour les trames HEADERS et DATA. Valeur par défaut : http2.constants.PADDING_STRATEGY_NONE. La valeur peut être l'une des suivantes :

  • http2.constants.PADDING_STRATEGY_NONE : Aucun rembourrage n'est appliqué.

  • http2.constants.PADDING_STRATEGY_MAX : La quantité maximale de rembourrage, déterminée par l'implémentation interne, est appliquée.

  • http2.constants.PADDING_STRATEGY_ALIGNED : Tente d'appliquer suffisamment de rembourrage pour que la longueur totale de la trame, y compris l'en-tête de 9 octets, soit un multiple de 8. Pour chaque trame, il existe un nombre maximal d'octets de rembourrage autorisé qui est déterminé par l'état actuel du contrôle de flux et les paramètres. Si ce maximum est inférieur à la quantité calculée nécessaire pour assurer l'alignement, le maximum est utilisé et la longueur totale de la trame n'est pas nécessairement alignée sur 8 octets.

  • peerMaxConcurrentStreams <nombre> Définit le nombre maximal de flux simultanés pour le pair distant comme si une trame SETTINGS avait été reçue. Sera remplacé si le pair distant définit sa propre valeur pour maxConcurrentStreams. Valeur par défaut : 100.

  • maxSessionInvalidFrames <entier> Définit le nombre maximal de trames invalides qui seront tolérées avant la fermeture de la session. Valeur par défaut : 1000.

  • maxSessionRejectedStreams <entier> Définit le nombre maximal de flux rejetés lors de la création qui seront tolérés avant la fermeture de la session. Chaque rejet est associé à une erreur NGHTTP2_ENHANCE_YOUR_CALM qui devrait indiquer au pair de ne plus ouvrir de flux, continuer à ouvrir des flux est donc considéré comme un signe d'un pair malveillant. Valeur par défaut : 100.

  • settings <Objet Paramètres HTTP/2> Les paramètres initiaux à envoyer au pair distant lors de la connexion.

  • remoteCustomSettings <Tableau> Le tableau de valeurs entières détermine les types de paramètres, qui sont inclus dans la propriété customSettings des remoteSettings reçus. Veuillez consulter la propriété customSettings de l'objet Http2Settings pour plus d'informations sur les types de paramètres autorisés.

  • ... : Toutes les options tls.createServer() peuvent être fournies. Pour les serveurs, les options d'identité (pfx ou key/cert) sont généralement nécessaires.

  • origins <chaîne[]> Un tableau de chaînes d'origine à envoyer dans une trame ORIGIN immédiatement après la création d'un nouveau serveur Http2Session.

  • unknownProtocolTimeout <nombre> Spécifie un délai d'attente en millisecondes qu'un serveur doit attendre lorsqu'un événement 'unknownProtocol' est émis. Si le socket n'a pas été détruit à ce moment-là, le serveur le détruira. Valeur par défaut : 10000.

• onRequestHandler <Fonction> Voir API de compatibilité

• Retourne : <Http2SecureServer>

Retourne une instance tls.Server qui crée et gère les instances Http2Session.

ESM

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

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

// Créer un serveur HTTP/2 sécurisé
const server = createSecureServer(options)

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

// Créer un serveur HTTP/2 sécurisé
const server = http2.createSecureServer(options)

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

server.listen(8443)

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

[Historique]

Version	Modifications
v13.0.0	PADDING_STRATEGY_CALLBACK est devenu équivalent à PADDING_STRATEGY_ALIGNED, et selectPadding a été supprimé.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Ajout de l'option unknownProtocolTimeout avec une valeur par défaut de 10000.
v14.4.0, v12.18.0, v10.21.0	Ajout de l'option maxSettings avec une valeur par défaut de 32.
v8.9.3	Ajout de l'option maxOutstandingPings avec une limite par défaut de 10.
v8.9.3	Ajout de l'option maxHeaderListPairs avec une limite par défaut de 128 paires d'en-têtes.
v8.4.0	Ajouté dans : v8.4.0

• authority <string> | <URL> Le serveur HTTP/2 distant auquel se connecter. Ceci doit être sous la forme d'une URL minimale et valide avec le préfixe http:// ou https://, le nom d'hôte et le port IP (si un port autre que le port par défaut est utilisé). Les informations d'utilisateur (ID utilisateur et mot de passe), le chemin, la chaîne de requête et les détails du fragment dans l'URL seront ignorés.

• options <Object>

  • maxDeflateDynamicTableSize <number> Définit la taille maximale de la table dynamique pour la déflation des champs d'en-tête. Défaut : 4Kib.

  • maxSettings <number> Définit le nombre maximum d'entrées de paramètres par trame SETTINGS. La valeur minimale autorisée est 1. Défaut : 32.

  • maxSessionMemory<number> Définit la mémoire maximale que Http2Session est autorisé à utiliser. La valeur est exprimée en nombre de mégaoctets, par exemple, 1 équivaut à 1 mégaoctet. La valeur minimale autorisée est 1. Il s'agit d'une limite basée sur le crédit, les Http2Stream existants peuvent dépasser cette limite, mais les nouvelles instances Http2Stream seront rejetées tant que cette limite est dépassée. Le nombre actuel de sessions Http2Stream, l'utilisation actuelle de la mémoire des tables de compression d'en-tête, les données actuellement en attente d'envoi et les trames PING et SETTINGS non accusées sont toutes comptabilisées dans la limite actuelle. Défaut : 10.

  • maxHeaderListPairs <number> Définit le nombre maximal d'entrées d'en-tête. Ceci est similaire à server.maxHeadersCount ou request.maxHeadersCount dans le module node:http. La valeur minimale est 1. Défaut : 128.

  • maxOutstandingPings <number> Définit le nombre maximum de pings en attente et non accusés. Défaut : 10.

  • maxReservedRemoteStreams <number> Définit le nombre maximal de flux push réservés que le client acceptera à un moment donné. Une fois que le nombre actuel de flux push actuellement réservés dépasse cette limite, les nouveaux flux push envoyés par le serveur seront automatiquement rejetés. La valeur minimale autorisée est 0. La valeur maximale autorisée est 2-1. Une valeur négative définit cette option sur la valeur maximale autorisée. Défaut : 200.

  • maxSendHeaderBlockLength <number> Définit la taille maximale autorisée pour un bloc sérialisé et compressé d'en-têtes. Les tentatives d'envoi d'en-têtes dépassant cette limite entraîneront l'émission d'un événement 'frameError' et la fermeture et la destruction du flux.

  • paddingStrategy <number> Stratégie utilisée pour déterminer la quantité de rembourrage à utiliser pour les trames HEADERS et DATA. Défaut : http2.constants.PADDING_STRATEGY_NONE. La valeur peut être l'une des suivantes :

  • http2.constants.PADDING_STRATEGY_NONE: Aucun rembourrage n'est appliqué.

  • http2.constants.PADDING_STRATEGY_MAX: Le rembourrage maximal, déterminé par l'implémentation interne, est appliqué.

  • http2.constants.PADDING_STRATEGY_ALIGNED: Tente d'appliquer suffisamment de rembourrage pour que la longueur totale de la trame, y compris l'en-tête de 9 octets, soit un multiple de 8. Pour chaque trame, il existe un nombre maximal d'octets de rembourrage autorisé qui est déterminé par l'état et les paramètres actuels du contrôle de flux. Si ce maximum est inférieur à la quantité calculée nécessaire pour assurer l'alignement, le maximum est utilisé et la longueur totale de la trame n'est pas nécessairement alignée sur 8 octets.

  • peerMaxConcurrentStreams <number> Définit le nombre maximal de flux simultanés pour le pair distant comme si une trame SETTINGS avait été reçue. Sera remplacé si le pair distant définit sa propre valeur pour maxConcurrentStreams. Défaut : 100.

  • protocol <string> Le protocole à utiliser pour la connexion, s'il n'est pas défini dans authority. La valeur peut être 'http:' ou 'https:'. Défaut : 'https:'

  • settings <Objet Paramètres HTTP/2> Les paramètres initiaux à envoyer au pair distant lors de la connexion.

  • remoteCustomSettings <Array> Le tableau de valeurs entières détermine les types de paramètres, qui sont inclus dans la propriété CustomSettings des remoteSettings reçus. Veuillez consulter la propriété CustomSettings de l'objet Http2Settings pour plus d'informations sur les types de paramètres autorisés.

  • createConnection <Function> Un rappel facultatif qui reçoit l'instance URL passée à connect et l'objet options, et renvoie tout flux Duplex qui doit être utilisé comme connexion pour cette session.

  • ... : Toutes les options net.connect() ou tls.connect() peuvent être fournies.

  • unknownProtocolTimeout <number> Spécifie un délai d'expiration en millisecondes qu'un serveur doit attendre lorsqu'un événement 'unknownProtocol' est émis. Si le socket n'a pas été détruit à ce moment-là, le serveur le détruira. Défaut : 10000.

• listener <Function> Sera enregistré comme écouteur unique de l'événement 'connect'.

• Retourne : <ClientHttp2Session>

Retourne une instance ClientHttp2Session.

ESM

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

/* Utiliser le client */

client.close()

CJS

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

/* Utiliser le client */

client.close()

http2.constants

Ajouté dans : v8.4.0

Codes d’erreur pour RST_STREAM et GOAWAY

Valeur	Nom	Constante
0x00	Aucune erreur	http2.constants.NGHTTP2_NO_ERROR
0x01	Erreur de protocole	http2.constants.NGHTTP2_PROTOCOL_ERROR
0x02	Erreur interne	http2.constants.NGHTTP2_INTERNAL_ERROR
0x03	Erreur de contrôle de flux	http2.constants.NGHTTP2_FLOW_CONTROL_ERROR
0x04	Délai d’attente des paramètres	http2.constants.NGHTTP2_SETTINGS_TIMEOUT
0x05	Flux fermé	http2.constants.NGHTTP2_STREAM_CLOSED
0x06	Erreur de taille de trame	http2.constants.NGHTTP2_FRAME_SIZE_ERROR
0x07	Flux refusé	http2.constants.NGHTTP2_REFUSED_STREAM
0x08	Annulation	http2.constants.NGHTTP2_CANCEL
0x09	Erreur de compression	http2.constants.NGHTTP2_COMPRESSION_ERROR
0x0a	Erreur de connexion	http2.constants.NGHTTP2_CONNECT_ERROR
0x0b	Améliorez votre calme	http2.constants.NGHTTP2_ENHANCE_YOUR_CALM
0x0c	Sécurité inadéquate	http2.constants.NGHTTP2_INADEQUATE_SECURITY
0x0d	HTTP/1.1 requis	http2.constants.NGHTTP2_HTTP_1_1_REQUIRED

L’événement 'timeout' est émis lorsqu’il n’y a aucune activité sur le serveur pendant un nombre donné de millisecondes défini à l’aide de http2server.setTimeout().

http2.getDefaultSettings()

Ajouté dans : v8.4.0

• Retourne : <Objet Paramètres HTTP/2>

Retourne un objet contenant les paramètres par défaut pour une instance Http2Session. Cette méthode retourne une nouvelle instance d’objet à chaque appel, donc les instances retournées peuvent être modifiées en toute sécurité pour utilisation.

http2.getPackedSettings([settings])

Ajouté dans : v8.4.0

• settings <Objet Paramètres HTTP/2>
• Retourne : <Buffer>

Retourne une instance Buffer contenant la représentation serialisée des paramètres HTTP/2 donnés, comme spécifié dans la spécification HTTP/2. Ceci est destiné à être utilisé avec le champ d’en-tête HTTP2-Settings.

ESM

import { getPackedSettings } from 'node:http2'

const packed = getPackedSettings({ enablePush: false })

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

CJS

const http2 = require('node:http2')

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

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

http2.getUnpackedSettings(buf)

Ajouté dans : v8.4.0

• buf <Buffer> | <TypedArray> Les paramètres compressés.
• Retourne : <Objet Paramètres HTTP/2>

Retourne un Objet Paramètres HTTP/2 contenant les paramètres désérialisés à partir du Buffer donné, tel que généré par http2.getPackedSettings().

http2.performServerHandshake(socket[, options])

Ajouté dans : v21.7.0, v20.12.0

• socket <stream.Duplex>

• options <Object>

  • ... : Toute option http2.createServer() peut être fournie.

• Retourne : <ServerHttp2Session>

Crée une session serveur HTTP/2 à partir d’un socket existant.

http2.sensitiveHeaders

Ajouté dans : v15.0.0, v14.18.0

• <symbole>

Ce symbole peut être défini comme une propriété de l’objet d’en-têtes HTTP/2 avec une valeur de tableau afin de fournir une liste des en-têtes considérés comme sensibles. Voir En-têtes sensibles pour plus de détails.

Objet En-têtes

Les en-têtes sont représentés comme des propriétés propres sur les objets JavaScript. Les clés des propriétés seront sérialisées en minuscules. Les valeurs des propriétés doivent être des chaînes de caractères (si ce n’est pas le cas, elles seront converties en chaînes de caractères) ou un tableau de chaînes de caractères (afin d’envoyer plus d’une valeur par champ d’en-tête).

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

stream.respond(headers)

Les objets d’en-têtes passés aux fonctions de rappel auront un prototype null. Cela signifie que les méthodes d’objet JavaScript normales telles que Object.prototype.toString() et Object.prototype.hasOwnProperty() ne fonctionneront pas.

Pour les en-têtes entrants :

• L’en-tête :status est converti en number.
• Les doublons 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 sont ignorés.
• set-cookie est toujours un tableau. Les doublons sont ajoutés au tableau.
• Pour les en-têtes cookie dupliqués, les valeurs sont jointes avec '; '.
• Pour tous les autres en-têtes, les valeurs sont jointes avec ', '.

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

En-têtes sensibles

Les en-têtes HTTP2 peuvent être marqués comme sensibles, ce qui signifie que l'algorithme de compression des en-têtes HTTP/2 ne les indexera jamais. Cela peut être judicieux pour les valeurs d'en-tête à faible entropie et qui peuvent être considérées comme précieuses pour un attaquant, par exemple Cookie ou Authorization. Pour ce faire, ajoutez le nom de l'en-tête à la propriété [http2.sensitiveHeaders] sous forme de tableau :

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)

Pour certains en-têtes, tels que Authorization et les en-têtes Cookie courts, ce drapeau est défini automatiquement.

Cette propriété est également définie pour les en-têtes reçus. Elle contiendra les noms de tous les en-têtes marqués comme sensibles, y compris ceux marqués automatiquement de cette façon.

Objet de configuration

[Historique]

Version	Modifications
v12.12.0	Le paramètre maxConcurrentStreams est plus strict.
v8.9.3	Le paramètre maxHeaderListSize est maintenant strictement appliqué.
v8.4.0	Ajouté dans : v8.4.0

Les API http2.getDefaultSettings(), http2.getPackedSettings(), http2.createServer(), http2.createSecureServer(), http2session.settings(), http2session.localSettings et http2session.remoteSettings renvoient ou reçoivent en entrée un objet qui définit les paramètres de configuration d'un objet Http2Session. Ces objets sont des objets JavaScript ordinaires contenant les propriétés suivantes.

• headerTableSize <nombre> Spécifie le nombre maximal d'octets utilisés pour la compression des en-têtes. La valeur minimale autorisée est 0. La valeur maximale autorisée est 2-1. Valeur par défaut : 4096.
• enablePush <booléen> Spécifie true si les flux push HTTP/2 doivent être autorisés sur les instances Http2Session. Valeur par défaut : true.
• initialWindowSize <nombre> Spécifie la taille de fenêtre initiale de l'émetteur en octets pour le contrôle de flux au niveau du flux. La valeur minimale autorisée est 0. La valeur maximale autorisée est 2-1. Valeur par défaut : 65535.
• maxFrameSize <nombre> Spécifie la taille en octets de la plus grande charge utile de trame. La valeur minimale autorisée est 16 384. La valeur maximale autorisée est 2-1. Valeur par défaut : 16384.
• maxConcurrentStreams <nombre> Spécifie le nombre maximal de flux concurrents autorisés sur une Http2Session. Il n'y a pas de valeur par défaut, ce qui implique, au moins théoriquement, que 2-1 flux peuvent être ouverts simultanément à tout moment dans une Http2Session. La valeur minimale est 0. La valeur maximale autorisée est 2-1. Valeur par défaut : 4294967295.
• maxHeaderListSize <nombre> Spécifie la taille maximale (octets non compressés) de la liste d'en-têtes qui sera acceptée. La valeur minimale autorisée est 0. La valeur maximale autorisée est 2-1. Valeur par défaut : 65535.
• maxHeaderSize <nombre> Alias de maxHeaderListSize.
• enableConnectProtocol<booléen> Spécifie true si le « protocole Connect étendu » défini par la RFC 8441 doit être activé. Ce paramètre n'a de sens que s'il est envoyé par le serveur. Une fois que le paramètre enableConnectProtocol a été activé pour une Http2Session donnée, il ne peut plus être désactivé. Valeur par défaut : false.
• customSettings <Objet> Spécifie des paramètres supplémentaires, non encore implémentés dans Node.js et les bibliothèques sous-jacentes. La clé de l'objet définit la valeur numérique du type de paramètre (tel que défini dans le registre « Paramètres HTTP/2 » établi par la [RFC 7540]) et les valeurs, la valeur numérique réelle des paramètres. Le type de paramètre doit être un entier compris entre 1 et 2^16-1. Il ne doit pas s'agir d'un type de paramètre déjà géré par Node.js, c'est-à-dire qu'il doit actuellement être supérieur à 6, bien que ce ne soit pas une erreur. Les valeurs doivent être des entiers non signés compris entre 0 et 2^32-1. Actuellement, un maximum de 10 paramètres personnalisés est pris en charge. Il est uniquement pris en charge pour l'envoi de PARAMÈTRES, ou pour la réception de valeurs de paramètres spécifiées dans les options remoteCustomSettings de l'objet serveur ou client. Ne mélangez pas le mécanisme customSettings pour un ID de paramètre avec les interfaces pour les paramètres gérés en natif, au cas où un paramètre deviendrait géré en natif dans une future version de Node.js.

Toutes les propriétés supplémentaires de l'objet de configuration sont ignorées.

Gestion des erreurs

Plusieurs types de conditions d'erreur peuvent survenir lors de l'utilisation du module node:http2 :

Les erreurs de validation se produisent lorsqu'un argument, une option ou une valeur de paramètre incorrects sont passés. Celles-ci seront toujours signalées par un throw synchrone.

Les erreurs d'état se produisent lorsqu'une action est tentée au mauvais moment (par exemple, tenter d'envoyer des données sur un flux après sa fermeture). Elles seront signalées soit par un throw synchrone, soit via un événement 'error' sur les objets Http2Stream, Http2Session ou serveur HTTP/2, selon l'endroit et le moment où l'erreur se produit.

Les erreurs internes se produisent lorsqu'une session HTTP/2 échoue de manière inattendue. Celles-ci seront signalées via un événement 'error' sur les objets Http2Session ou serveur HTTP/2.

Les erreurs de protocole se produisent lorsque diverses contraintes du protocole HTTP/2 sont violées. Elles seront signalées soit par un throw synchrone, soit via un événement 'error' sur les objets Http2Stream, Http2Session ou serveur HTTP/2, selon l'endroit et le moment où l'erreur se produit.

Gestion des caractères invalides dans les noms et les valeurs d'en-tête

L'implémentation HTTP/2 applique une gestion plus stricte des caractères invalides dans les noms et les valeurs des en-têtes HTTP que l'implémentation HTTP/1.

Les noms de champs d'en-tête sont insensibles à la casse et sont transmis sur le réseau strictement sous forme de chaînes de caractères en minuscules. L'API fournie par Node.js permet de définir les noms d'en-tête comme des chaînes de caractères en majuscules et minuscules (par exemple, Content-Type), mais les convertira en minuscules (par exemple, content-type) lors de la transmission.

Les noms de champs d'en-tête ne doivent contenir que l'un ou plusieurs des caractères ASCII suivants : a-z, A-Z, 0-9, !, #, $, %, &, ', *, +, -, ., ^, _, ```(accent grave),|, et ~.

L'utilisation de caractères invalides dans un nom de champ d'en-tête HTTP entraînera la fermeture du flux avec une erreur de protocole signalée.

Les valeurs de champ d'en-tête sont traitées avec plus de tolérance, mais ne devraient pas contenir de caractères de nouvelle ligne ou de retour chariot et devraient être limitées aux caractères US-ASCII, conformément aux exigences de la spécification HTTP.

Flux push sur le client

Pour recevoir des flux push sur le client, définissez un écouteur pour l'événement 'stream' sur le ClientHttp2Session :

ESM

import { connect } from 'node:http2'

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

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', responseHeaders => {
    // Traiter les en-têtes de réponse
  })
  pushedStream.on('data', chunk => {
    /* gérer les données pushées */
  })
})

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 => {
    // Traiter les en-têtes de réponse
  })
  pushedStream.on('data', chunk => {
    /* gérer les données pushées */
  })
})

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

Prise en charge de la méthode CONNECT

La méthode CONNECT permet d'utiliser un serveur HTTP/2 comme proxy pour les connexions TCP/IP.

Un serveur TCP simple :

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(`hello ${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(`hello ${name}`))
})

server.listen(8000)

Un 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') {
    // Accepter uniquement les requêtes CONNECT
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // Il est fortement conseillé de vérifier que le nom d'hôte et le port
  // sont ceux auxquels ce proxy doit se connecter.
  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') {
    // Accepter uniquement les requêtes CONNECT
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // Il est fortement conseillé de vérifier que le nom d'hôte et le port
  // sont ceux auxquels ce proxy doit se connecter.
  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)

Un client HTTP/2 CONNECT :

ESM

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

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

// Ne doit pas spécifier les en-têtes ':path' et ':scheme'
// pour les requêtes CONNECT, sinon une erreur sera levée.
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(`Le serveur dit : ${data}`)
  client.close()
})
req.end('Jane')

CJS

const http2 = require('node:http2')

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

// Ne doit pas spécifier les en-têtes ':path' et ':scheme'
// pour les requêtes CONNECT, sinon une erreur sera levée.
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(`Le serveur dit : ${data}`)
  client.close()
})
req.end('Jane')

Le protocole CONNECT étendu

RFC 8441 définit une extension "Protocole CONNECT étendu" à HTTP/2 qui peut être utilisée pour bootstrapper l'utilisation d'un Http2Stream en utilisant la méthode CONNECT comme tunnel pour d'autres protocoles de communication (tels que WebSockets).

L'utilisation du protocole CONNECT étendu est activée par les serveurs HTTP/2 en utilisant le paramètre 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 })

Une fois que le client reçoit l'en-tête SETTINGS du serveur indiquant que le CONNECT étendu peut être utilisé, il peut envoyer des requêtes CONNECT qui utilisent le pseudo-en-tête 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 compatibilité

L'API de compatibilité a pour objectif de fournir une expérience développeur similaire à HTTP/1 lors de l'utilisation de HTTP/2, permettant de développer des applications compatibles à la fois avec HTTP/1 et HTTP/2. Cette API cible uniquement l'API publique de HTTP/1. Cependant, de nombreux modules utilisent des méthodes ou des états internes, et ceux-ci ne sont pas pris en charge car il s'agit d'une implémentation complètement différente.

L'exemple suivant crée un serveur HTTP/2 en utilisant l'API de compatibilité :

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

Pour créer un serveur mixte HTTPS et HTTP/2, reportez-vous à la section négociation ALPN. La mise à niveau à partir de serveurs HTTP/1 non-TLS n'est pas prise en charge.

L'API de compatibilité HTTP/2 est composée de Http2ServerRequest et Http2ServerResponse. Elles visent la compatibilité API avec HTTP/1, mais elles ne cachent pas les différences entre les protocoles. Par exemple, le message d'état pour les codes HTTP est ignoré.

Négociation ALPN

La négociation ALPN permet de prendre en charge à la fois HTTPS et HTTP/2 sur la même socket. Les objets req et res peuvent être HTTP/1 ou HTTP/2, et une application doit se restreindre à l'API publique de HTTP/1, et détecter s'il est possible d'utiliser les fonctionnalités plus avancées de HTTP/2.

L'exemple suivant crée un serveur prenant en charge les deux protocoles :

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) {
  // Détecte s'il s'agit d'une requête 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) {
  // Détecte s'il s'agit d'une requête 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,
    })
  )
}

L'événement 'request' fonctionne de manière identique sur HTTPS et HTTP/2.

Classe : http2.Http2ServerRequest

Ajouté dans : v8.4.0

• Étend : <stream.Readable>

Un objet Http2ServerRequest est créé par http2.Server ou http2.SecureServer et passé comme premier argument à l'événement 'request'. Il peut être utilisé pour accéder à l'état d'une requête, aux en-têtes et aux données.

Événement : 'aborted'

Ajouté dans : v8.4.0

L'événement 'aborted' est émis lorsqu'une instance Http2ServerRequest est anormalement interrompue en milieu de communication.

L'événement 'aborted' ne sera émis que si le côté inscriptible de Http2ServerRequest n'a pas été terminé.

Événement : 'close'

Ajouté dans : v8.4.0

Indique que le Http2Stream sous-jacent a été fermé. Tout comme 'end', cet événement ne se produit qu'une seule fois par réponse.

request.aborted

Ajouté dans : v10.1.0

• <boolean>

La propriété request.aborted sera true si la requête a été interrompue.

request.authority

Ajouté dans : v8.4.0

• <string>

Le champ d'en-tête pseudo-autorité de la requête. Comme HTTP/2 permet aux requêtes de définir soit :authority soit host, cette valeur est dérivée de req.headers[':authority'] si elle est présente. Sinon, elle est dérivée de req.headers['host'].

request.complete

Ajouté dans : v12.10.0

• <boolean>

La propriété request.complete sera true si la requête a été complétée, interrompue ou détruite.

request.connection

Ajouté dans : v8.4.0

Déprécié depuis : v13.0.0

[Stable : 0 - Déprécié]

Stable : 0 Stabilité : 0 - Déprécié. Utilisez request.socket.

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

Voir request.socket.

request.destroy([error])

Ajouté dans : v8.4.0

• error <Error>

Appelle destroy() sur le Http2Stream qui a reçu le Http2ServerRequest. Si error est fourni, un événement 'error' est émis et error est passé comme argument à tous les écouteurs de l'événement.

Il ne fait rien si le flux a déjà été détruit.

request.headers

Ajouté dans : v8.4.0

• <Object>

L'objet des en-têtes de requête/réponse.

Paires clé-valeur de noms et de valeurs d'en-têtes. Les noms d'en-têtes sont en minuscules.

// Affiche quelque chose comme :
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers)

Voir Objet En-têtes HTTP/2.

En HTTP/2, le chemin de la requête, le nom d'hôte, le protocole et la méthode sont représentés comme des en-têtes spéciaux préfixés par le caractère : (par exemple, ':path'). Ces en-têtes spéciaux seront inclus dans l'objet request.headers. Il faut veiller à ne pas modifier par inadvertance ces en-têtes spéciaux, sans quoi des erreurs peuvent se produire. Par exemple, supprimer toutes les en-têtes de la requête provoquera des erreurs :

removeAllHeaders(request.headers)
assert(request.url) // Échoue car l'en-tête :path a été supprimé

request.httpVersion

Ajouté dans : v8.4.0

• <string>

En cas de requête serveur, la version HTTP envoyée par le client. Dans le cas d'une réponse client, la version HTTP du serveur connecté. Retourne '2.0'.

Aussi message.httpVersionMajor est le premier entier et message.httpVersionMinor est le second.

request.method

Ajouté dans : v8.4.0

• <string>

La méthode de requête sous forme de chaîne de caractères. Lecture seule. Exemples : 'GET', 'DELETE'.

request.rawHeaders

Ajouté dans : v8.4.0

• <string[]>

La liste brute des en-têtes de requête/réponse exactement telle qu'elle a été reçue.

Les clés et les valeurs sont dans la même liste. Ce n'est pas une liste de tuples. Ainsi, les décalages pairs sont des valeurs clés, et les décalages impairs sont les valeurs associées.

Les noms d'en-têtes ne sont pas en minuscules, et les doublons ne sont pas fusionnés.

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

request.rawTrailers

Ajouté dans : v8.4.0

• <string[]>

Les clés et valeurs brutes des en-têtes de fin de requête/réponse, telles qu'elles ont été reçues. Uniquement renseigné lors de l'événement 'end'.

request.scheme

Ajouté dans : v8.4.0

• <string>

Le champ d'en-tête pseudo-requête indiquant la partie schème de l'URL cible.

request.setTimeout(msecs, callback)

Ajouté dans : v8.4.0

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

Définit la valeur de délai d'expiration du Http2Stream à msecs. Si une fonction de rappel est fournie, elle est ajoutée comme écouteur de l'événement 'timeout' sur l'objet de réponse.

Si aucun écouteur 'timeout' n'est ajouté à la requête, à la réponse ou au serveur, les Http2Stream sont détruits lorsqu'ils expirent. Si un gestionnaire est affecté aux événements 'timeout' de la requête, de la réponse ou du serveur, les sockets expirés doivent être gérés explicitement.

request.socket

Ajouté dans : v8.4.0

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

Retourne un objet Proxy qui agit comme un net.Socket (ou tls.TLSSocket) mais applique des accesseurs, des mutateurs et des méthodes basés sur la logique HTTP/2.

Les propriétés destroyed, readable et writable seront récupérées et définies sur request.stream.

Les méthodes destroy, emit, end, on et once seront appelées sur request.stream.

La méthode setTimeout sera appelée sur request.stream.session.

pause, read, resume et write déclencheront une erreur avec le code ERR_HTTP2_NO_SOCKET_MANIPULATION. Voir Http2Session et Sockets pour plus d'informations.

Toutes les autres interactions seront routées directement vers le socket. Avec la prise en charge de TLS, utilisez request.socket.getPeerCertificate() pour obtenir les détails d'authentification du client.

request.stream

Ajouté dans : v8.4.0

• <Http2Stream>

L'objet Http2Stream qui supporte la requête.

request.trailers

Ajouté dans : v8.4.0

• <Object>

L'objet des en-têtes de fin de requête/réponse. Uniquement peuplé lors de l'événement 'end'.

request.url

Ajouté dans : v8.4.0

• <string>

Chaîne d'URL de la requête. Cela contient uniquement l'URL présente dans la requête HTTP réelle. Si la requête est :

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

Alors request.url sera :

'/status?name=ryan'

Pour analyser l'URL en ses parties, new URL() peut être utilisé :

$ 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

Ajouté dans : v8.4.0

• Étend : <Stream>

Cet objet est créé en interne par un serveur HTTP, et non par l'utilisateur. Il est passé en second paramètre à l'événement 'request'.

Événement : 'close'

Ajouté dans : v8.4.0

Indique que le Http2Stream sous-jacent a été terminé avant que response.end() ne soit appelé ou capable de purger.

Événement : 'finish'

Ajouté dans : v8.4.0

Émis lorsque la réponse a été envoyée. Plus précisément, cet événement est émis lorsque le dernier segment des en-têtes et du corps de la réponse a été remis au multiplexage HTTP/2 pour la transmission sur le réseau. Cela n'implique pas que le client ait encore reçu quoi que ce soit.

Après cet événement, aucun autre événement ne sera émis sur l'objet de réponse.

response.addTrailers(headers)

Ajouté dans : v8.4.0

• headers <Objet>

Cette méthode ajoute des en-têtes HTTP de fin (une en-tête, mais à la fin du message) à la réponse.

Toute tentative de définir un nom ou une valeur de champ d'en-tête contenant des caractères invalides entraînera le lancement d'une exception TypeError.

response.appendHeader(name, value)

Ajouté dans : v21.7.0, v20.12.0

• name <chaîne de caractères>
• value <chaîne de caractères> | <tableau de chaînes de caractères>

Ajoute une seule valeur d'en-tête à l'objet d'en-tête.

Si la valeur est un tableau, cela équivaut à appeler cette méthode plusieurs fois.

S'il n'y avait aucune valeur précédente pour l'en-tête, cela équivaut à appeler response.setHeader().

Toute tentative de définir un nom ou une valeur de champ d'en-tête contenant des caractères invalides entraînera le lancement d'une exception TypeError.

// Renvoie les en-têtes, y compris "set-cookie : a" et "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

Ajouté dans : v8.4.0

Déprécié depuis : v13.0.0

[Stable : 0 - Déprécié]

Stable : 0 Stabilité : 0 - Déprécié. Utilisez response.socket.

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

Voir response.socket.

response.createPushResponse(headers, callback)

[Historique]

Version	Modifications
v18.0.0	Le passage d'une fonction de rappel invalide à l'argument callback lève maintenant ERR_INVALID_ARG_TYPE au lieu de ERR_INVALID_CALLBACK.
v8.4.0	Ajouté dans : v8.4.0

• headers <Objet d'en-têtes HTTP/2> Un objet décrivant les en-têtes
• callback <Fonction> Appelée une fois que http2stream.pushStream() est terminé, ou bien lorsque la tentative de création du Http2Stream poussé a échoué ou a été rejetée, ou que l'état de Http2ServerRequest est fermé avant l'appel de la méthode http2stream.pushStream()
  • err <Erreur>
  • res <http2.Http2ServerResponse> L'objet Http2ServerResponse nouvellement créé

Appelez http2stream.pushStream() avec les en-têtes données, et encapsulez le Http2Stream donné sur un Http2ServerResponse nouvellement créé comme paramètre de rappel en cas de succès. Lorsque Http2ServerRequest est fermé, la fonction de rappel est appelée avec une erreur ERR_HTTP2_INVALID_STREAM.

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

[Historique]

Version	Modifications
v10.0.0	Cette méthode renvoie maintenant une référence à ServerResponse.
v8.4.0	Ajouté dans : v8.4.0

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

Cette méthode signale au serveur que tous les en-têtes et le corps de la réponse ont été envoyés ; le serveur doit considérer ce message comme complet. La méthode response.end() DOIT être appelée pour chaque réponse.

Si data est spécifié, cela équivaut à appeler response.write(data, encoding) suivi de response.end(callback).

Si callback est spécifié, il sera appelé lorsque le flux de réponse sera terminé.

response.finished

Ajouté dans : v8.4.0

Déprécié depuis : v13.4.0, v12.16.0

[Stable : 0 - Déprécié]

Stable : 0 Stabilité : 0 - Déprécié. Utilisez response.writableEnded.

• <boolean>

Valeur booléenne indiquant si la réponse est terminée. Commence à false. Après l'exécution de response.end(), la valeur sera true.

response.getHeader(name)

Ajouté dans : v8.4.0

• name <string>
• Retourne : <string>

Lit un en-tête qui a déjà été mis en file d'attente mais pas envoyé au client. Le nom ne respecte pas la casse.

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

response.getHeaderNames()

Ajouté dans : v8.4.0

• Retourne : <string[]>

Retourne un tableau contenant les noms uniques des en-têtes sortantes actuelles. Tous les noms d'en-têtes sont en minuscules.

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

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

response.getHeaders()

Ajouté dans : v8.4.0

• Retourne : <Object>

Retourne une copie superficielle des en-têtes sortantes actuelles. Comme une copie superficielle est utilisée, les valeurs de tableau peuvent être mutées sans appels supplémentaires aux diverses méthodes du module http liées aux en-têtes. Les clés de l'objet retourné sont les noms des en-têtes et les valeurs sont les valeurs des en-têtes respectives. Tous les noms d'en-têtes sont en minuscules.

L'objet retourné par la méthode response.getHeaders() n'hérite pas prototypiquement de l'objet JavaScript Object. Cela signifie que les méthodes Object typiques telles que obj.toString(), obj.hasOwnProperty(), et d'autres ne sont pas définies et ne fonctionneront pas.

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)

Ajouté dans : v8.4.0

• name <string>
• Retourne : <boolean>

Retourne true si l'en-tête identifié par name est actuellement défini dans les en-têtes sortantes. La correspondance du nom de l'en-tête ne tient pas compte de la casse.

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

response.headersSent

Ajouté dans : v8.4.0

• <boolean>

true si les en-têtes ont été envoyées, false sinon (en lecture seule).

response.removeHeader(name)

Ajouté dans : v8.4.0

• name <string>

Supprime un en-tête qui a été mis en file d'attente pour une envoi implicite.

response.removeHeader('Content-Encoding')

response.req

Ajouté dans : v15.7.0

• <http2.Http2ServerRequest>

Une référence à l'objet request HTTP2 original.

response.sendDate

Ajouté dans : v8.4.0

• <boolean>

Lorsqu'il est vrai, l'en-tête Date sera automatiquement généré et envoyé dans la réponse s'il n'est pas déjà présent dans les en-têtes. La valeur par défaut est true.

Cela ne devrait être désactivé que pour les tests ; HTTP nécessite l'en-tête Date dans les réponses.

response.setHeader(name, value)

Ajouté dans : v8.4.0

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

Définit une seule valeur d'en-tête pour les en-têtes implicites. Si cet en-tête existe déjà dans les en-têtes à envoyer, sa valeur sera remplacée. Utilisez un tableau de chaînes ici pour envoyer plusieurs en-têtes avec le même nom.

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

ou

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

Toute tentative de définir un nom ou une valeur de champ d'en-tête contenant des caractères invalides entraînera le lancement d'une exception TypeError.

Lorsque les en-têtes ont été définis avec response.setHeader(), ils seront fusionnés avec tous les en-têtes passés à response.writeHead(), les en-têtes passés à response.writeHead() ayant la priorité.

// Renvoie 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])

Ajouté dans : v8.4.0

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

Définit la valeur de délai d'expiration du Http2Stream à msecs. Si un rappel est fourni, il est ajouté comme écouteur à l'événement 'timeout' sur l'objet de réponse.

Si aucun écouteur 'timeout' n'est ajouté à la requête, à la réponse ou au serveur, les Http2Stream sont détruits lorsqu'ils expirent. Si un gestionnaire est affecté aux événements 'timeout' de la requête, de la réponse ou du serveur, les sockets expirés doivent être gérés explicitement.

response.socket

Ajouté dans : v8.4.0

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

Retourne un objet Proxy qui agit comme un net.Socket (ou tls.TLSSocket) mais applique des accesseurs, des mutateurs et des méthodes basés sur la logique HTTP/2.

Les propriétés destroyed, readable et writable seront récupérées et définies sur response.stream.

Les méthodes destroy, emit, end, on et once seront appelées sur response.stream.

La méthode setTimeout sera appelée sur response.stream.session.

pause, read, resume et write lèveront une erreur avec le code ERR_HTTP2_NO_SOCKET_MANIPULATION. Consultez Http2Session et les sockets pour plus d'informations.

Toutes les autres interactions seront routées directement vers la socket.

ESM

import { createServer } from 'node:http2'
const server = createServer((req, res) => {
  const ip = req.socket.remoteAddress
  const port = req.socket.remotePort
  res.end(`Votre adresse IP est ${ip} et votre port source est ${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(`Votre adresse IP est ${ip} et votre port source est ${port}.`)
  })
  .listen(3000)

response.statusCode

Ajouté dans : v8.4.0

• <nombre>

Lors de l'utilisation d'en-têtes implicites (sans appel explicite à response.writeHead()), cette propriété contrôle le code de statut qui sera envoyé au client lorsque les en-têtes seront vidées.

response.statusCode = 404

Une fois l'en-tête de réponse envoyée au client, cette propriété indique le code de statut qui a été envoyé.

response.statusMessage

Ajouté dans : v8.4.0

• <chaîne de caractères>

Le message d'état n'est pas pris en charge par HTTP/2 (RFC 7540 8.1.2.4). Il renvoie une chaîne de caractères vide.

response.stream

Ajouté dans : v8.4.0

• <Http2Stream>

L'objet Http2Stream qui supporte la réponse.

response.writableEnded

Ajouté dans : v12.9.0

• <booléen>

Est égal à true après l'appel de response.end(). Cette propriété n'indique pas si les données ont été vidées ; utilisez plutôt writable.writableFinished.

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

Ajouté dans : v8.4.0

• chunk <chaîne de caractères> | <Buffer> | <Uint8Array>
• encoding <chaîne de caractères>
• callback <Fonction>
• Retourne : <booléen>

Si cette méthode est appelée et que response.writeHead() n'a pas été appelée, elle passera en mode d'en-tête implicite et videra les en-têtes implicites.

Ceci envoie un fragment du corps de la réponse. Cette méthode peut être appelée plusieurs fois pour fournir des parties successives du corps.

Dans le module node:http, le corps de la réponse est omis lorsque la requête est une requête HEAD. De même, les réponses 204 et 304 ne doivent pas inclure de corps de message.

chunk peut être une chaîne de caractères ou une mémoire tampon. Si chunk est une chaîne de caractères, le second paramètre spécifie comment l'encoder en un flux d'octets. Par défaut, l'encodage est 'utf8'. callback sera appelé lorsque ce fragment de données sera vidé.

Il s'agit du corps HTTP brut et n'a rien à voir avec les encodages de corps multi-parties de niveau supérieur qui peuvent être utilisés.

La première fois que response.write() est appelée, elle enverra les informations d'en-tête mises en mémoire tampon et le premier fragment du corps au client. La deuxième fois que response.write() est appelée, Node.js suppose que les données seront transmises en continu et envoie les nouvelles données séparément. C'est-à-dire que la réponse est mise en mémoire tampon jusqu'au premier fragment du corps.

Retourne true si toutes les données ont été vidées avec succès dans la mémoire tampon du noyau. Retourne false si tout ou partie des données ont été mises en file d'attente dans la mémoire utilisateur. 'drain' sera émis lorsque la mémoire tampon sera à nouveau libre.

response.writeContinue()

Ajouté dans : v8.4.0

Envoie le statut 100 Continue au client, indiquant que le corps de la requête doit être envoyé. Voir l'événement 'checkContinue' sur Http2Server et Http2SecureServer.

response.writeEarlyHints(hints)

Ajouté dans : v18.11.0

• hints <Objet>

Envoie le statut 103 Early Hints au client avec un en-tête Link, indiquant que l'agent utilisateur peut précharger/préconnecter les ressources liées. hints est un objet contenant les valeurs des en-têtes à envoyer avec le message d'indications anticipées.

Exemple

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])

[Historique]

Version	Modifications
v11.10.0, v10.17.0	Retourne this depuis writeHead() pour permettre l'enchaînement avec end().
v8.4.0	Ajouté dans : v8.4.0

• statusCode <nombre>
• statusMessage <chaîne de caractères>
• headers <Objet> | <Tableau>
• Retourne : <http2.Http2ServerResponse>

Envoie un en-tête de réponse à la requête. Le code de statut est un code de statut HTTP à 3 chiffres, comme 404. Le dernier argument, headers, sont les en-têtes de réponse.

Retourne une référence à Http2ServerResponse, afin que les appels puissent être enchaînés.

Pour la compatibilité avec HTTP/1, un statusMessage lisible par l'homme peut être passé en deuxième argument. Cependant, comme le statusMessage n'a aucune signification dans HTTP/2, l'argument n'aura aucun effet et un avertissement de processus sera émis.

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

Content-Length est donné en octets et non en caractères. L'API Buffer.byteLength() peut être utilisée pour déterminer le nombre d'octets dans un encodage donné. Sur les messages sortants, Node.js ne vérifie pas si Content-Length et la longueur du corps transmis sont égaux ou non. Cependant, lors de la réception de messages, Node.js rejettera automatiquement les messages lorsque Content-Length ne correspond pas à la taille de la charge utile réelle.

Cette méthode peut être appelée au maximum une fois sur un message avant que response.end() ne soit appelé.

Si response.write() ou response.end() sont appelés avant d'appeler ceci, les en-têtes implicites/mutables seront calculés et appelleront cette fonction.

Lorsque les en-têtes ont été définis avec response.setHeader(), ils seront fusionnés avec tous les en-têtes passés à response.writeHead(), les en-têtes passés à response.writeHead() ayant la priorité.

// Retourne 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')
})

Tenter de définir un nom de champ d'en-tête ou une valeur contenant des caractères invalides entraînera le lancement d'une exception TypeError.

Collecte des métriques de performance HTTP/2

L'API Performance Observer peut être utilisée pour collecter des métriques de performance de base pour chaque instance Http2Session et Http2Stream.

ESM

import { PerformanceObserver } from 'node:perf_hooks'

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // affiche 'http2'
  if (entry.name === 'Http2Session') {
    // L'entrée contient des statistiques sur la Http2Session
  } else if (entry.name === 'Http2Stream') {
    // L'entrée contient des statistiques sur la 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) // affiche 'http2'
  if (entry.name === 'Http2Session') {
    // L'entrée contient des statistiques sur la Http2Session
  } else if (entry.name === 'Http2Stream') {
    // L'entrée contient des statistiques sur la Http2Stream
  }
})
obs.observe({ entryTypes: ['http2'] })

La propriété entryType de PerformanceEntry sera égale à 'http2'.

La propriété name de PerformanceEntry sera égale à 'Http2Stream' ou 'Http2Session'.

Si name est égal à Http2Stream, PerformanceEntry contiendra les propriétés supplémentaires suivantes :

• bytesRead <number> Le nombre d'octets de trame DATA reçus pour ce Http2Stream.
• bytesWritten <number> Le nombre d'octets de trame DATA envoyés pour ce Http2Stream.
• id <number> L'identifiant du Http2Stream associé.
• timeToFirstByte <number> Le nombre de millisecondes écoulées entre le startTime de PerformanceEntry et la réception de la première trame DATA.
• timeToFirstByteSent <number> Le nombre de millisecondes écoulées entre le startTime de PerformanceEntry et l'envoi de la première trame DATA.
• timeToFirstHeader <number> Le nombre de millisecondes écoulées entre le startTime de PerformanceEntry et la réception du premier en-tête.

Si name est égal à Http2Session, PerformanceEntry contiendra les propriétés supplémentaires suivantes :

• bytesRead <number> Le nombre d'octets reçus pour cette Http2Session.
• bytesWritten <number> Le nombre d'octets envoyés pour cette Http2Session.
• framesReceived <number> Le nombre de trames HTTP/2 reçues par la Http2Session.
• framesSent <number> Le nombre de trames HTTP/2 envoyées par la Http2Session.
• maxConcurrentStreams <number> Le nombre maximal de flux ouverts simultanément pendant la durée de vie de la Http2Session.
• pingRTT <number> Le nombre de millisecondes écoulées depuis la transmission d'une trame PING et la réception de son accusé de réception. Présent uniquement si une trame PING a été envoyée sur la Http2Session.
• streamAverageDuration <number> La durée moyenne (en millisecondes) pour toutes les instances Http2Stream.
• streamCount <number> Le nombre d'instances Http2Stream traitées par la Http2Session.
• type <string> Soit 'server' soit 'client' pour identifier le type de Http2Session.

Note sur :authority et host

HTTP/2 requiert que les requêtes possèdent soit le pseudo-en-tête :authority, soit l'en-tête host. Privilégiez :authority lors de la construction directe d'une requête HTTP/2, et host lors de la conversion depuis HTTP/1 (dans les proxies, par exemple).

L'API de compatibilité utilise host par défaut si :authority est absent. Voir request.authority pour plus d'informations. Cependant, si vous n'utilisez pas l'API de compatibilité (ou utilisez req.headers directement), vous devez implémenter vous-même tout comportement de repli.