HTTP/2

[Versionsverlauf]

Version	Änderungen
v15.0.0	Anfragen mit dem host-Header (mit oder ohne :authority) können jetzt gesendet/empfangen werden.
v15.3.0, v14.17.0	Es ist möglich, eine Anfrage mit einem AbortSignal abzubrechen.
v10.10.0	HTTP/2 ist jetzt stabil. Zuvor war es experimentell.
v8.4.0	Hinzugefügt in: v8.4.0

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/http2.js

Das Modul node:http2 stellt eine Implementierung des HTTP/2-Protokolls bereit. Es kann wie folgt verwendet werden:

const http2 = require('node:http2')

Feststellung, ob Krypto-Unterstützung nicht verfügbar ist

Node.js kann ohne Unterstützung für das Modul node:crypto kompiliert werden. In solchen Fällen führt der Versuch, aus node:http2 zu importieren oder require('node:http2') aufzurufen, zu einem Fehler.

Bei Verwendung von CommonJS kann der ausgegebene Fehler mit try/catch abgefangen werden:

let http2
try {
  http2 = require('node:http2')
} catch (err) {
  console.error('http2-Unterstützung ist deaktiviert!')
}

Bei Verwendung des lexikalischen ESM import-Schlüsselworts kann der Fehler nur abgefangen werden, wenn ein Handler für process.on('uncaughtException') bevor jedem Versuch, das Modul zu laden (z. B. mit einem Preload-Modul), registriert wird.

Bei Verwendung von ESM, wenn die Möglichkeit besteht, dass der Code auf einem Build von Node.js ausgeführt wird, bei dem die Krypto-Unterstützung nicht aktiviert ist, sollten Sie die Funktion import() anstelle des lexikalischen import-Schlüsselworts verwenden:

let http2
try {
  http2 = await import('node:http2')
} catch (err) {
  console.error('http2-Unterstützung ist deaktiviert!')
}

Core-API

Die Core-API bietet eine Low-Level-Schnittstelle, die speziell für die Unterstützung von HTTP/2-Protokollfunktionen entwickelt wurde. Sie ist nicht für die Kompatibilität mit der bestehenden API des HTTP/1-Moduls konzipiert. Die Kompatibilitäts-API hingegen schon.

Die http2 Core-API ist viel symmetrischer zwischen Client und Server als die http-API. Beispielsweise können die meisten Ereignisse wie 'error', 'connect' und 'stream' entweder von Client-seitigem oder Server-seitigem Code emittiert werden.

Server-seitiges Beispiel

Das Folgende veranschaulicht einen einfachen HTTP/2-Server unter Verwendung der Core-API. Da keine Browser bekannt sind, die unverschlüsseltes HTTP/2 unterstützen, ist die Verwendung von http2.createSecureServer() bei der Kommunikation mit Browser-Clients erforderlich.

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

server.listen(8443)

Um das Zertifikat und den Schlüssel für dieses Beispiel zu generieren, führen Sie folgenden Befehl aus:

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

Client-seitiges Beispiel

Das Folgende veranschaulicht einen HTTP/2-Client:

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

Klasse: Http2Session

Hinzugefügt in: v8.4.0

• Erweitert: <EventEmitter>

Instanzen der Klasse http2.Http2Session repräsentieren eine aktive Kommunikationssitzung zwischen einem HTTP/2-Client und -Server. Instanzen dieser Klasse sollen nicht direkt vom Benutzercode erstellt werden.

Jede Http2Session-Instanz weist ein leicht unterschiedliches Verhalten auf, je nachdem, ob sie als Server oder Client arbeitet. Die Eigenschaft http2session.type kann verwendet werden, um den Modus zu bestimmen, in dem eine Http2Session arbeitet. Auf der Serverseite sollte der Benutzercode selten Anlass haben, direkt mit dem Http2Session-Objekt zu arbeiten, wobei die meisten Aktionen typischerweise durch Interaktionen mit den Objekten Http2Server oder Http2Stream durchgeführt werden.

Benutzercode erstellt keine Http2Session-Instanzen direkt. Serverseitige Http2Session-Instanzen werden von der Http2Server-Instanz erstellt, wenn eine neue HTTP/2-Verbindung empfangen wird. Clientseitige Http2Session-Instanzen werden mit der Methode http2.connect() erstellt.

Http2Session und Sockets

Jede Http2Session-Instanz ist bei ihrer Erstellung mit genau einem net.Socket oder tls.TLSSocket verbunden. Wenn entweder das Socket oder die Http2Session zerstört werden, werden beide zerstört.

Aufgrund der spezifischen Serialisierungs- und Verarbeitungsanforderungen des HTTP/2-Protokolls wird es nicht empfohlen, dass Benutzercode Daten von einer Socket-Instanz liest, die an eine Http2Session gebunden ist, oder Daten in diese schreibt. Dies kann die HTTP/2-Sitzung in einen unbestimmten Zustand versetzen, wodurch die Sitzung und das Socket unbrauchbar werden.

Sobald ein Socket an eine Http2Session gebunden wurde, sollte sich der Benutzercode ausschließlich auf die API der Http2Session verlassen.

Ereignis: 'close'

Hinzugefügt in: v8.4.0

Das Ereignis 'close' wird ausgegeben, sobald die Http2Session zerstört wurde. Sein Listener erwartet keine Argumente.

Ereignis: 'connect'

Hinzugefügt in: v8.4.0

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

Das Ereignis 'connect' wird ausgegeben, sobald die Http2Session erfolgreich mit dem Remote-Peer verbunden wurde und die Kommunikation beginnen kann.

Benutzercode wird dieses Ereignis normalerweise nicht direkt abhören.

Ereignis: 'error'

Hinzugefügt in: v8.4.0

• error <Error>

Das Ereignis 'error' wird ausgelöst, wenn während der Verarbeitung einer Http2Session ein Fehler auftritt.

Ereignis: 'frameError'

Hinzugefügt in: v8.4.0

• type <integer> Der Frame-Typ.
• code <integer> Der Fehlercode.
• id <integer> Die Stream-ID (oder 0, wenn der Frame keinem Stream zugeordnet ist).

Das Ereignis 'frameError' wird ausgelöst, wenn beim Versuch, einen Frame in der Sitzung zu senden, ein Fehler auftritt. Wenn der nicht gesendete Frame einem spezifischen Http2Stream zugeordnet ist, wird versucht, ein 'frameError'-Ereignis auf dem Http2Stream auszulösen.

Wenn das 'frameError'-Ereignis mit einem Stream verknüpft ist, wird der Stream unmittelbar nach dem 'frameError'-Ereignis geschlossen und zerstört. Wenn das Ereignis nicht mit einem Stream verknüpft ist, wird die Http2Session unmittelbar nach dem 'frameError'-Ereignis heruntergefahren.

Ereignis: 'goaway'

Hinzugefügt in: v8.4.0

• errorCode <number> Der im GOAWAY-Frame angegebene HTTP/2-Fehlercode.
• lastStreamID <number> Die ID des letzten Streams, den der entfernte Peer erfolgreich verarbeitet hat (oder 0, wenn keine ID angegeben ist).
• opaqueData <Buffer> Wenn zusätzliche opake Daten im GOAWAY-Frame enthalten waren, wird eine Buffer-Instanz übergeben, die diese Daten enthält.

Das Ereignis 'goaway' wird ausgelöst, wenn ein GOAWAY-Frame empfangen wird.

Die Http2Session-Instanz wird automatisch heruntergefahren, wenn das Ereignis 'goaway' ausgelöst wird.

Event: 'localSettings'

Hinzugefügt in: v8.4.0

• settings <HTTP/2 Settings Objekt> Eine Kopie des empfangenen SETTINGS Frames.

Das Ereignis 'localSettings' wird ausgelöst, wenn ein Bestätigungs-SETTINGS-Frame empfangen wurde.

Bei Verwendung von http2session.settings() zum Übermitteln neuer Einstellungen werden die geänderten Einstellungen erst wirksam, wenn das Ereignis 'localSettings' ausgelöst wird.

session.settings({ enablePush: false })

session.on('localSettings', settings => {
  /* Neue Einstellungen verwenden */
})

Event: 'ping'

Hinzugefügt in: v10.12.0

• payload <Buffer> Die 8-Byte-Payload des PING Frames

Das Ereignis 'ping' wird immer dann ausgelöst, wenn ein PING-Frame vom verbundenen Peer empfangen wird.

Event: 'remoteSettings'

Hinzugefügt in: v8.4.0

• settings <HTTP/2 Settings Objekt> Eine Kopie des empfangenen SETTINGS Frames.

Das Ereignis 'remoteSettings' wird ausgelöst, wenn ein neuer SETTINGS-Frame vom verbundenen Peer empfangen wird.

session.on('remoteSettings', settings => {
  /* Neue Einstellungen verwenden */
})

Event: 'stream'

Hinzugefügt in: v8.4.0

• stream <Http2Stream> Ein Verweis auf den Stream
• headers <HTTP/2 Headers Objekt> Ein Objekt, das die Header beschreibt
• flags <number> Die zugehörigen numerischen Flags
• rawHeaders <Array> Ein Array, das die Rohheadernamen gefolgt von ihren jeweiligen Werten enthält.

Das Ereignis 'stream' wird ausgelöst, wenn ein neuer Http2Stream erstellt wird.

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

Auf der Serverseite wird der Benutzercode dieses Ereignis normalerweise nicht direkt abhören, sondern stattdessen einen Handler für das Ereignis 'stream' registrieren, das von den net.Server- oder tls.Server-Instanzen ausgegeben wird, die von http2.createServer() bzw. http2.createSecureServer() zurückgegeben werden, wie im folgenden Beispiel gezeigt:

ESM

import { createServer } from 'node:http2'

// Erstellen eines unverschlüsselten HTTP/2-Servers
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')

// Erstellen eines unverschlüsselten HTTP/2-Servers
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)

Obwohl HTTP/2-Streams und Netzwerksockets nicht in einer 1:1-Beziehung stehen, zerstört ein Netzwerkfehler jeden einzelnen Stream und muss wie oben gezeigt auf Stream-Ebene behandelt werden.

Ereignis: 'timeout'

Hinzugefügt in: v8.4.0

Nachdem die Methode http2session.setTimeout() verwendet wurde, um die Timeout-Periode für diese Http2Session festzulegen, wird das Ereignis 'timeout' ausgelöst, wenn nach der konfigurierten Anzahl von Millisekunden keine Aktivität auf der Http2Session besteht. Sein Listener erwartet keine Argumente.

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

http2session.alpnProtocol

Hinzugefügt in: v9.4.0

• <string> | <undefined>

Der Wert ist undefined, wenn die Http2Session noch nicht mit einem Socket verbunden ist, h2c, wenn die Http2Session nicht mit einem TLSSocket verbunden ist, oder gibt den Wert der Eigenschaft alpnProtocol des verbundenen TLSSocket zurück.

http2session.close([callback])

Hinzugefügt in: v9.4.0

• callback <Function>

Schließt die Http2Session elegant ab, sodass alle bestehenden Streams selbstständig abgeschlossen werden können und verhindert, dass neue Http2Stream-Instanzen erstellt werden. Nach dem Schließen wird http2session.destroy() möglicherweise aufgerufen, wenn keine offenen Http2Stream-Instanzen vorhanden sind.

Falls angegeben, wird die callback-Funktion als Handler für das Ereignis 'close' registriert.

http2session.closed

Hinzugefügt in: v9.4.0

• <boolean>

Ist true, wenn diese Http2Session-Instanz geschlossen wurde, andernfalls false.

http2session.connecting

Hinzugefügt in: v10.0.0

• <boolean>

Ist true, wenn diese Http2Session-Instanz noch eine Verbindung herstellt, wird auf false gesetzt, bevor das connect-Ereignis ausgelöst und/oder der http2.connect-Callback aufgerufen wird.

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

Hinzugefügt in: v8.4.0

• error <Error> Ein Error-Objekt, wenn die Http2Session aufgrund eines Fehlers zerstört wird.
• code <number> Der HTTP/2-Fehlercode, der im letzten GOAWAY-Frame gesendet werden soll. Wenn nicht angegeben und error nicht undefiniert ist, ist der Standardwert INTERNAL_ERROR, andernfalls standardmäßig NO_ERROR.

Beendet die Http2Session und den zugehörigen net.Socket oder tls.TLSSocket sofort.

Nach der Zerstörung löst die Http2Session das Ereignis 'close' aus. Wenn error nicht undefiniert ist, wird unmittelbar vor dem Ereignis 'close' ein Ereignis 'error' ausgelöst.

Wenn noch offene Http2Streams vorhanden sind, die der Http2Session zugeordnet sind, werden diese ebenfalls zerstört.

http2session.destroyed

Hinzugefügt in: v8.4.0

• <boolean>

Ist true, wenn diese Http2Session-Instanz zerstört wurde und nicht mehr verwendet werden darf, andernfalls false.

http2session.encrypted

Hinzugefügt in: v9.4.0

• <boolean> | <undefined>

Der Wert ist undefined, wenn die Http2Session-Socketsitzung noch nicht verbunden wurde, true, wenn die Http2Session mit einem TLSSocket verbunden ist, und false, wenn die Http2Session mit einer anderen Art von Socket oder Stream verbunden ist.

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

Hinzugefügt in: v9.4.0

• code <number> Ein HTTP/2-Fehlercode
• lastStreamID <number> Die numerische ID des zuletzt verarbeiteten Http2Stream
• opaqueData <Buffer> | <TypedArray> | <DataView> Eine TypedArray- oder DataView-Instanz, die zusätzliche Daten enthält, die im GOAWAY-Frame übertragen werden sollen.

Überträgt einen GOAWAY-Frame an den verbundenen Peer, ohne die Http2Session herunterzufahren.

http2session.localSettings

Hinzugefügt in: v8.4.0

• <HTTP/2 Settings Object>

Ein prototypenloses Objekt, das die aktuellen lokalen Einstellungen dieser Http2Session beschreibt. Die lokalen Einstellungen sind lokal für diese Http2Session-Instanz.

http2session.originSet

Hinzugefügt in: v9.4.0

• <string[]> | <undefined>

Wenn die Http2Session mit einem TLSSocket verbunden ist, gibt die Eigenschaft originSet ein Array von Ursprüngen zurück, für die die Http2Session als autoritativ betrachtet werden kann.

Die Eigenschaft originSet ist nur bei Verwendung einer sicheren TLS-Verbindung verfügbar.

http2session.pendingSettingsAck

Hinzugefügt in: v8.4.0

• <boolean>

Gibt an, ob die Http2Session derzeit auf die Bestätigung eines gesendeten SETTINGS-Frames wartet. Wird nach dem Aufruf der Methode http2session.settings() true sein. Wird false sein, sobald alle gesendeten SETTINGS-Frames bestätigt wurden.

http2session.ping([payload, ]callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v8.9.3	Hinzugefügt in: v8.9.3

• payload <Buffer> | <TypedArray> | <DataView> Optionale Ping-Nutzlast.
• callback <Function>
• Rückgabewert: <boolean>

Sendet einen PING-Frame an den verbundenen HTTP/2-Peer. Eine callback-Funktion muss bereitgestellt werden. Die Methode gibt true zurück, wenn der PING gesendet wurde, andernfalls false.

Die maximale Anzahl ausstehender (unbestätigter) Pings wird durch die Konfigurationsoption maxOutstandingPings bestimmt. Der Standardwert ist 10.

Falls angegeben, muss die payload ein Buffer, TypedArray oder DataView sein, der 8 Bytes an Daten enthält, die mit dem PING übertragen und mit der Ping-Bestätigung zurückgegeben werden.

Der Callback wird mit drei Argumenten aufgerufen: einem Fehlerargument, das null ist, wenn der PING erfolgreich bestätigt wurde, einem duration-Argument, das die Anzahl der seit dem Senden des Pings und dem Empfang der Bestätigung verstrichenen Millisekunden angibt, und einem Buffer, der die 8-Byte PING-Nutzlast enthält.

session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`Ping bestätigt in ${duration} Millisekunden`)
    console.log(`Mit Nutzlast '${payload.toString()}'`)
  }
})

Wenn das Argument payload nicht angegeben ist, ist die Standardnutzlast der 64-Bit-Zeitstempel (Little Endian), der den Beginn der PING-Dauer markiert.

http2session.ref()

Hinzugefügt in: v9.4.0

Ruft ref() auf der zugrunde liegenden net.Socket Instanz dieser Http2Session auf.

http2session.remoteSettings

Hinzugefügt in: v8.4.0

• <HTTP/2 Settings Objekt>

Ein prototypenloses Objekt, das die aktuellen Remote-Einstellungen dieser Http2Session beschreibt. Die Remote-Einstellungen werden vom verbundenen HTTP/2-Peer festgelegt.

http2session.setLocalWindowSize(windowSize)

Hinzugefügt in: v15.3.0, v14.18.0

• windowSize <number>

Legt die Fenstergröße des lokalen Endpunkts fest. windowSize ist die Gesamtfenstergröße, die gesetzt werden soll, nicht das Delta.

ESM

import { createServer } from 'node:http2'

const server = createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // Setze lokale Fenstergröße auf 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // Setze lokale Fenstergröße auf 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

Für http2-Clients ist das richtige Ereignis entweder 'connect' oder 'remoteSettings'.

http2session.setTimeout(msecs, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v8.4.0	Hinzugefügt in: v8.4.0

• msecs <number>
• callback <Function>

Wird verwendet, um eine Callback-Funktion festzulegen, die aufgerufen wird, wenn nach msecs Millisekunden keine Aktivität auf der Http2Session vorhanden ist. Der angegebene callback wird als Listener für das Ereignis 'timeout' registriert.

http2session.socket

Hinzugefügt in: v8.4.0

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

Gibt ein Proxy-Objekt zurück, das als net.Socket (oder tls.TLSSocket) fungiert, aber die verfügbaren Methoden auf solche beschränkt, die für die Verwendung mit HTTP/2 sicher sind.

destroy, emit, end, pause, read, resume und write lösen einen Fehler mit dem Code ERR_HTTP2_NO_SOCKET_MANIPULATION aus. Weitere Informationen finden Sie unter Http2Session und Sockets.

Die setTimeout-Methode wird auf dieser Http2Session aufgerufen.

Alle anderen Interaktionen werden direkt an das Socket weitergeleitet.

http2session.state

Hinzugefügt in: v8.4.0

Liefert verschiedene Informationen über den aktuellen Zustand der Http2Session.

• <Object>
  • effectiveLocalWindowSize <number> Die aktuelle lokale (empfangene) Flow-Control-Fenstergröße für die Http2Session.
  • effectiveRecvDataLength <number> Die aktuelle Anzahl der Bytes, die seit dem letzten Flow-Control WINDOW_UPDATE empfangen wurden.
  • nextStreamID <number> Die numerische Kennung, die beim nächsten Erstellen eines neuen Http2Stream von dieser Http2Session verwendet wird.
  • localWindowSize <number> Die Anzahl der Bytes, die der Remote-Peer senden kann, ohne ein WINDOW_UPDATE zu erhalten.
  • lastProcStreamID <number> Die numerische ID des Http2Stream, für den zuletzt ein HEADERS- oder DATA-Frame empfangen wurde.
  • remoteWindowSize <number> Die Anzahl der Bytes, die diese Http2Session senden darf, ohne ein WINDOW_UPDATE zu erhalten.
  • outboundQueueSize <number> Die Anzahl der Frames, die sich derzeit in der ausgehenden Warteschlange für diese Http2Session befinden.
  • deflateDynamicTableSize <number> Die aktuelle Größe in Bytes der ausgehenden Header-Kompressions-Zustandstabelle.
  • inflateDynamicTableSize <number> Die aktuelle Größe in Bytes der eingehenden Header-Kompressions-Zustandstabelle.

Ein Objekt, das den aktuellen Status dieser Http2Session beschreibt.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v8.4.0	Hinzugefügt in: v8.4.0

• settings <HTTP/2 Settings Objekt>
• callback <Funktion> Callback-Funktion, die aufgerufen wird, sobald die Sitzung verbunden ist oder sofort, wenn die Sitzung bereits verbunden ist.
  • err <Error> | <null>
  • settings <HTTP/2 Settings Objekt> Das aktualisierte settings-Objekt.
  • duration <Ganzzahl>

Aktualisiert die aktuellen lokalen Einstellungen für diese Http2Session und sendet einen neuen SETTINGS-Frame an den verbundenen HTTP/2-Peer.

Nach dem Aufruf ist die Eigenschaft http2session.pendingSettingsAck true, während die Sitzung auf die Bestätigung der neuen Einstellungen durch den Remote-Peer wartet.

Die neuen Einstellungen werden erst wirksam, nachdem die SETTINGS-Bestätigung empfangen wurde und das Ereignis 'localSettings' emittiert wurde. Es ist möglich, mehrere SETTINGS-Frames zu senden, während die Bestätigung noch aussteht.

http2session.type

Hinzugefügt in: v8.4.0

• <Zahl>

Der Wert von http2session.type ist http2.constants.NGHTTP2_SESSION_SERVER, wenn diese Http2Session-Instanz ein Server ist, und http2.constants.NGHTTP2_SESSION_CLIENT, wenn die Instanz ein Client ist.

http2session.unref()

Hinzugefügt in: v9.4.0

Ruft unref() für die zugrunde liegende net.Socket-Instanz dieser Http2Session auf.

Klasse: ServerHttp2Session

Hinzugefügt in: v8.4.0

• Erweitert: <Http2Session>

serverhttp2session.altsvc(alt, originOrStream)

Hinzugefügt in: v9.4.0

• alt <string> Eine Beschreibung der alternativen Dienstkonfiguration gemäß RFC 7838.
• originOrStream <number> | <string> | <URL> | <Object> Entweder eine URL-Zeichenkette, die den Ursprung angibt (oder ein Object mit einer origin-Eigenschaft) oder die numerische Kennung eines aktiven Http2Stream, wie durch die http2stream.id-Eigenschaft angegeben.

Sendet einen ALTSVC-Frame (gemäß RFC 7838) an den verbundenen Client.

ESM

import { createServer } from 'node:http2'

const server = createServer()
server.on('session', session => {
  // Setze altsvc für Ursprung https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // Setze altsvc für einen spezifischen Stream
  stream.session.altsvc('h2=":8000"', stream.id)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
server.on('session', session => {
  // Setze altsvc für Ursprung https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // Setze altsvc für einen spezifischen Stream
  stream.session.altsvc('h2=":8000"', stream.id)
})

Das Senden eines ALTSVC-Frames mit einer spezifischen Stream-ID zeigt an, dass der alternative Dienst mit dem Ursprung des gegebenen Http2Stream assoziiert ist.

Die Zeichenkette alt und die Ursprungszzeichenkette müssen nur ASCII-Bytes enthalten und werden strikt als Folge von ASCII-Bytes interpretiert. Der Sonderwert 'clear' kann übergeben werden, um jeden zuvor für eine gegebene Domain festgelegten alternativen Dienst zu löschen.

Wenn eine Zeichenkette für das Argument originOrStream übergeben wird, wird sie als URL analysiert und der Ursprung wird abgeleitet. Beispielsweise ist der Ursprung für die HTTP-URL 'https://example.org/foo/bar' die ASCII-Zeichenkette 'https://example.org'. Es wird ein Fehler ausgegeben, wenn die angegebene Zeichenkette entweder nicht als URL analysiert werden kann oder wenn kein gültiger Ursprung abgeleitet werden kann.

Ein URL-Objekt oder jedes Objekt mit einer origin-Eigenschaft kann als originOrStream übergeben werden. In diesem Fall wird der Wert der origin-Eigenschaft verwendet. Der Wert der origin-Eigenschaft muss ein korrekt serialisierter ASCII-Ursprung sein.

Angabe alternativer Dienste

Das Format des alt-Parameters ist streng durch RFC 7838 als eine ASCII-Zeichenkette definiert, die eine kommagetrennte Liste von „alternativen“ Protokollen enthält, die einem bestimmten Host und Port zugeordnet sind.

Beispielsweise zeigt der Wert 'h2="example.org:81"' an, dass das HTTP/2-Protokoll auf dem Host 'example.org' am TCP/IP-Port 81 verfügbar ist. Host und Port müssen innerhalb der Anführungszeichen (") stehen.

Es können mehrere Alternativen angegeben werden, z. B.: 'h2="example.org:81", h2=":82"'.

Die Protokollkennung ('h2' in den Beispielen) kann eine beliebige gültige ALPN-Protokoll-ID sein.

Die Syntax dieser Werte wird von der Node.js-Implementierung nicht validiert und wird so weitergegeben, wie sie vom Benutzer bereitgestellt oder vom Peer empfangen wurde.

serverhttp2session.origin(...origins)

Hinzugefügt in: v10.12.0

• origins <string> | <URL> | <Object> Eine oder mehrere URL-Zeichenketten, die als separate Argumente übergeben werden.

Sendet einen ORIGIN-Frame (wie in RFC 8336 definiert) an den verbundenen Client, um die Menge der Ursprünge bekannt zu geben, für die der Server autoritative Antworten liefern kann.

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

Wenn eine Zeichenkette als origin übergeben wird, wird sie als URL analysiert und der Ursprung wird abgeleitet. Beispielsweise ist der Ursprung für die HTTP-URL 'https://example.org/foo/bar' die ASCII-Zeichenkette 'https://example.org'. Es wird ein Fehler ausgegeben, wenn die angegebene Zeichenkette entweder nicht als URL analysiert werden kann oder wenn kein gültiger Ursprung abgeleitet werden kann.

Ein URL-Objekt oder jedes Objekt mit einer origin-Eigenschaft kann als origin übergeben werden. In diesem Fall wird der Wert der origin-Eigenschaft verwendet. Der Wert der origin-Eigenschaft muss ein korrekt serialisierter ASCII-Ursprung sein.

Alternativ kann die Option origins verwendet werden, wenn ein neuer HTTP/2-Server mit der Methode http2.createSecureServer() erstellt wird:

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

Klasse: ClientHttp2Session

Hinzugefügt in: v8.4.0

• Erweitert: <Http2Session>

Ereignis: 'altsvc'

Hinzugefügt in: v9.4.0

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

Das Ereignis 'altsvc' wird immer dann ausgelöst, wenn ein ALTSVC-Frame vom Client empfangen wird. Das Ereignis wird mit dem ALTSVC-Wert, dem Ursprung und der Stream-ID ausgelöst. Wenn im ALTSVC-Frame kein origin angegeben ist, ist origin eine leere Zeichenkette.

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

Ereignis: 'origin'

Hinzugefügt in: v10.12.0

• origins <string[]>

Das Ereignis 'origin' wird immer dann ausgelöst, wenn ein ORIGIN-Frame vom Client empfangen wird. Das Ereignis wird mit einem Array von origin-Zeichenketten ausgelöst. Die http2session.originSet wird aktualisiert, um die empfangenen Ursprünge einzuschließen.

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

Das Ereignis 'origin' wird nur bei Verwendung einer sicheren TLS-Verbindung ausgelöst.

clienthttp2session.request(headers[, options])

Hinzugefügt in: v8.4.0

• headers <HTTP/2-Header-Objekt>

• options <Objekt>

  • endStream <boolean> true, wenn die schreibbare Seite des Http2Stream anfänglich geschlossen werden soll, z. B. beim Senden einer GET-Anfrage, die keinen Payload-Body erwarten sollte.
  • exclusive <boolean> Wenn true und parent einen übergeordneten Stream identifiziert, wird der erstellte Stream zur alleinigen direkten Abhängigkeit des übergeordneten Streams, wobei alle anderen bestehenden Abhängigen zu Abhängigen des neu erstellten Streams werden. Standardwert: false.
  • parent <number> Gibt die numerische Kennung eines Streams an, von dem der neu erstellte Stream abhängig ist.
  • weight <number> Gibt die relative Abhängigkeit eines Streams in Bezug auf andere Streams mit demselben parent an. Der Wert ist eine Zahl zwischen 1 und 256 (einschließlich).
  • waitForTrailers <boolean> Wenn true, sendet der Http2Stream das Ereignis 'wantTrailers' nach dem Senden des letzten DATA-Frames.
  • signal <AbortSignal> Ein AbortSignal, das verwendet werden kann, um eine laufende Anfrage abzubrechen.

• Gibt zurück: <ClientHttp2Stream>

Nur für HTTP/2-Client-Http2Session-Instanzen erstellt http2session.request() eine Http2Stream-Instanz und gibt sie zurück, mit der eine HTTP/2-Anfrage an den verbundenen Server gesendet werden kann.

Wenn eine ClientHttp2Session zum ersten Mal erstellt wird, ist die Socketverbindung möglicherweise noch nicht hergestellt. Wenn clienthttp2session.request() während dieser Zeit aufgerufen wird, wird die eigentliche Anfrage verschoben, bis die Socketverbindung bereit ist. Wenn die session geschlossen wird, bevor die eigentliche Anfrage ausgeführt wird, wird ein ERR_HTTP2_GOAWAY_SESSION ausgelöst.

Diese Methode ist nur verfügbar, wenn http2session.type gleich http2.constants.NGHTTP2_SESSION_CLIENT ist.

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', () => {
    /* .. */
  })
})

Wenn die Option options.waitForTrailers gesetzt ist, wird das Ereignis 'wantTrailers' unmittelbar nach dem Einfügen des letzten zu sendenden Payload-Datenstücks ausgegeben. Die Methode http2stream.sendTrailers() kann dann aufgerufen werden, um dem Peer nachlaufende Header zu senden.

Wenn options.waitForTrailers gesetzt ist, schließt der Http2Stream nicht automatisch, wenn der letzte DATA-Frame übertragen wird. Der Benutzercode muss entweder http2stream.sendTrailers() oder http2stream.close() aufrufen, um den Http2Stream zu schließen.

Wenn options.signal mit einem AbortSignal gesetzt und dann abort für den entsprechenden AbortController aufgerufen wird, sendet die Anfrage ein 'error'-Ereignis mit einem AbortError.

Die Pseudo-Header :method und :path werden nicht in headers angegeben, sie haben standardmäßig die folgenden Werte:

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

Klasse: Http2Stream

Hinzugefügt in: v8.4.0

• Erweitert: <stream.Duplex>

Jede Instanz der Klasse Http2Stream repräsentiert einen bidirektionalen HTTP/2-Kommunikationsstrom über eine Http2Session-Instanz. Eine einzelne Http2Session kann während ihrer Lebensdauer bis zu 2³¹-1 Http2Stream-Instanzen haben.

Benutzercode erstellt keine Http2Stream-Instanzen direkt. Diese werden vielmehr von der Http2Session-Instanz erstellt, verwaltet und dem Benutzercode bereitgestellt. Auf dem Server werden Http2Stream-Instanzen entweder als Antwort auf eine eingehende HTTP-Anfrage erstellt (und über das Ereignis 'stream' an den Benutzercode übergeben) oder als Antwort auf einen Aufruf der Methode http2stream.pushStream(). Auf dem Client werden Http2Stream-Instanzen erstellt und zurückgegeben, wenn entweder die Methode http2session.request() aufgerufen wird oder als Antwort auf ein eingehendes Ereignis 'push'.

Die Klasse Http2Stream ist eine Basis für die Klassen ServerHttp2Stream und ClientHttp2Stream, die jeweils spezifisch von der Server- bzw. Client-Seite verwendet werden.

Alle Http2Stream-Instanzen sind Duplex-Streams. Die Writable-Seite des Duplex wird verwendet, um Daten an den verbundenen Peer zu senden, während die Readable-Seite verwendet wird, um Daten zu empfangen, die vom verbundenen Peer gesendet werden.

Die Standardzeichencodierung für Text für einen Http2Stream ist UTF-8. Verwenden Sie bei der Verwendung eines Http2Stream zum Senden von Text den Header 'content-type', um die Zeichencodierung festzulegen.

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

Http2Stream-Lebenszyklus

Erstellung

Auf der Serverseite werden Instanzen von ServerHttp2Stream erstellt, wenn:

• Ein neuer HTTP/2 HEADERS-Frame mit einer zuvor nicht verwendeten Stream-ID empfangen wird;
• Die Methode http2stream.pushStream() aufgerufen wird.

Auf der Clientseite werden Instanzen von ClientHttp2Stream erstellt, wenn die Methode http2session.request() aufgerufen wird.

Auf dem Client ist die von http2session.request() zurückgegebene Http2Stream-Instanz möglicherweise nicht sofort einsatzbereit, wenn die übergeordnete Http2Session noch nicht vollständig eingerichtet wurde. In solchen Fällen werden Operationen, die auf dem Http2Stream aufgerufen werden, gepuffert, bis das Ereignis 'ready' emittiert wird. Benutzercode sollte das Ereignis 'ready' selten, wenn überhaupt, direkt behandeln müssen. Der Bereitschaftsstatus eines Http2Stream kann durch Überprüfung des Werts von http2stream.id bestimmt werden. Wenn der Wert undefined ist, ist der Stream noch nicht einsatzbereit.

Zerstörung

Alle Http2Stream-Instanzen werden zerstört, wenn:

• Ein RST_STREAM-Frame für den Stream vom verbundenen Peer empfangen wird und (nur für Client-Streams) ausstehende Daten gelesen wurden.
• Die Methode http2stream.close() aufgerufen wird und (nur für Client-Streams) ausstehende Daten gelesen wurden.
• Die Methoden http2stream.destroy() oder http2session.destroy() aufgerufen werden.

Wenn eine Http2Stream-Instanz zerstört wird, wird versucht, einen RST_STREAM-Frame an den verbundenen Peer zu senden.

Wenn die Http2Stream-Instanz zerstört wird, wird das Ereignis 'close' emittiert. Da Http2Stream eine Instanz von stream.Duplex ist, wird auch das Ereignis 'end' emittiert, wenn die Stream-Daten gerade übertragen werden. Das Ereignis 'error' kann auch emittiert werden, wenn http2stream.destroy() mit einem als erstes Argument übergebenen Error aufgerufen wurde.

Nachdem der Http2Stream zerstört wurde, ist die Eigenschaft http2stream.destroyed true und die Eigenschaft http2stream.rstCode gibt den RST_STREAM-Fehlercode an. Die Http2Stream-Instanz ist nach der Zerstörung nicht mehr verwendbar.

Ereignis: 'aborted'

Hinzugefügt in: v8.4.0

Das Ereignis 'aborted' wird immer dann emittiert, wenn eine Http2Stream-Instanz während der Kommunikation abnormal abgebrochen wird. Sein Listener erwartet keine Argumente.

Das Ereignis 'aborted' wird nur emittiert, wenn die beschreibbare Seite von Http2Stream nicht beendet wurde.

Ereignis: 'close'

Hinzugefügt in: v8.4.0

Das Ereignis 'close' wird emittiert, wenn der Http2Stream zerstört wird. Sobald dieses Ereignis emittiert wurde, ist die Http2Stream-Instanz nicht mehr verwendbar.

Der HTTP/2-Fehlercode, der beim Schließen des Streams verwendet wurde, kann über die Eigenschaft http2stream.rstCode abgerufen werden. Wenn der Code ein anderer Wert als NGHTTP2_NO_ERROR (0) ist, wurde auch ein 'error'-Ereignis emittiert.

Ereignis: 'error'

Hinzugefügt in: v8.4.0

• error <Error>

Das Ereignis 'error' wird emittiert, wenn während der Verarbeitung eines Http2Stream ein Fehler auftritt.

Ereignis: 'frameError'

Hinzugefügt in: v8.4.0

• type <Ganzzahl> Der Frame-Typ.
• code <Ganzzahl> Der Fehlercode.
• id <Ganzzahl> Die Stream-ID (oder 0, wenn der Frame keinem Stream zugeordnet ist).

Das Ereignis 'frameError' wird ausgelöst, wenn beim Versuch, einen Frame zu senden, ein Fehler auftritt. Beim Aufruf erhält die Handler-Funktion ein ganzzahliges Argument, das den Frame-Typ identifiziert, und ein ganzzahliges Argument, das den Fehlercode identifiziert. Die Http2Stream-Instanz wird unmittelbar nach dem Auslösen des Ereignisses 'frameError' zerstört.

Ereignis: 'ready'

Hinzugefügt in: v8.4.0

Das Ereignis 'ready' wird ausgelöst, wenn der Http2Stream geöffnet wurde, eine id zugewiesen bekommen hat und verwendet werden kann. Der Listener erwartet keine Argumente.

Ereignis: 'timeout'

Hinzugefügt in: v8.4.0

Das Ereignis 'timeout' wird ausgelöst, nachdem innerhalb der mit http2stream.setTimeout() eingestellten Millisekunden keine Aktivität für diesen Http2Stream empfangen wurde. Sein Listener erwartet keine Argumente.

Ereignis: 'trailers'

Hinzugefügt in: v8.4.0

• headers <HTTP/2-Header-Objekt> Ein Objekt, das die Header beschreibt.
• flags <Zahl> Die zugehörigen numerischen Flags.

Das Ereignis 'trailers' wird ausgelöst, wenn ein Block von Headern, der mit nachfolgenden Header-Feldern verknüpft ist, empfangen wird. Der Listener-Callback erhält das HTTP/2-Header-Objekt und die mit den Headern verknüpften Flags.

Dieses Ereignis wird möglicherweise nicht ausgelöst, wenn http2stream.end() aufgerufen wird, bevor Trailer empfangen werden und die eingehenden Daten nicht gelesen oder überwacht werden.

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

Ereignis: 'wantTrailers'

Hinzugefügt in: v10.0.0

Das Ereignis 'wantTrailers' wird ausgelöst, wenn der Http2Stream den letzten zu sendenden DATA-Frame in einen Frame eingereiht hat und der Http2Stream bereit ist, Trailing-Header zu senden. Bei der Initiierung einer Anfrage oder Antwort muss die Option waitForTrailers gesetzt sein, damit dieses Ereignis ausgelöst wird.

http2stream.aborted

Hinzugefügt in: v8.4.0

• <boolean>

Wird auf true gesetzt, wenn die Http2Stream-Instanz anormal abgebrochen wurde. Wenn dies gesetzt ist, wurde das Ereignis 'aborted' ausgelöst.

http2stream.bufferSize

Hinzugefügt in: v11.2.0, v10.16.0

• <number>

Diese Eigenschaft zeigt die Anzahl der aktuell gepufferten Zeichen an, die geschrieben werden sollen. Siehe net.Socket.bufferSize für Details.

http2stream.close(code[, callback])

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v8.4.0	Hinzugefügt in: v8.4.0

• code <number> Unsignierte 32-Bit-Ganzzahl, die den Fehlercode identifiziert. Standard: http2.constants.NGHTTP2_NO_ERROR (0x00).
• callback <Function> Eine optionale Funktion, die registriert wird, um auf das Ereignis 'close' zu hören.

Schließt die Http2Stream-Instanz, indem ein RST_STREAM-Frame an den verbundenen HTTP/2-Peer gesendet wird.

http2stream.closed

Hinzugefügt in: v9.4.0

• <boolean>

Wird auf true gesetzt, wenn die Http2Stream-Instanz geschlossen wurde.

http2stream.destroyed

Hinzugefügt in: v8.4.0

• <boolean>

Wird auf true gesetzt, wenn die Http2Stream-Instanz zerstört wurde und nicht mehr verwendbar ist.

http2stream.endAfterHeaders

Hinzugefügt in: v10.11.0

• <boolean>

Auf true setzen, wenn das END_STREAM-Flag im empfangenen HEADERS-Frame der Anfrage oder Antwort gesetzt wurde, was anzeigt, dass keine zusätzlichen Daten empfangen werden sollten und die lesbare Seite des Http2Stream geschlossen wird.

http2stream.id

Hinzugefügt in: v8.4.0

• <number> | <undefined>

Die numerische Stream-ID dieser Http2Stream-Instanz. Auf undefined gesetzt, wenn die Stream-ID noch nicht zugewiesen wurde.

http2stream.pending

Hinzugefügt in: v9.4.0

• <boolean>

Auf true gesetzt, wenn der Http2Stream-Instanz noch keine numerische Stream-ID zugewiesen wurde.

http2stream.priority(options)

Hinzugefügt in: v8.4.0

• options <Object>
  • exclusive <boolean> Wenn true und parent einen übergeordneten Stream identifiziert, wird dieser Stream zur alleinigen direkten Abhängigkeit des übergeordneten Streams gemacht, wobei alle anderen bestehenden Abhängigen zu Abhängigen dieses Streams gemacht werden. Standardwert: false.
  • parent <number> Gibt die numerische ID eines Streams an, von dem dieser Stream abhängig ist.
  • weight <number> Gibt die relative Abhängigkeit eines Streams in Bezug auf andere Streams mit demselben parent an. Der Wert ist eine Zahl zwischen 1 und 256 (inklusive).
  • silent <boolean> Wenn true, ändert die Priorität lokal, ohne einen PRIORITY-Frame an den verbundenen Peer zu senden.

Aktualisiert die Priorität für diese Http2Stream-Instanz.

http2stream.rstCode

Hinzugefügt in: v8.4.0

• <number>

Wird auf den RST_STREAM Fehlercode gesetzt, der gemeldet wird, wenn der Http2Stream zerstört wird, nachdem entweder ein RST_STREAM-Frame vom verbundenen Peer empfangen wurde, http2stream.close() oder http2stream.destroy() aufgerufen wurde. Wird undefined sein, wenn der Http2Stream nicht geschlossen wurde.

http2stream.sentHeaders

Hinzugefügt in: v9.5.0

• <HTTP/2 Headers Object>

Ein Objekt, das die ausgehenden Header enthält, die für diesen Http2Stream gesendet wurden.

http2stream.sentInfoHeaders

Hinzugefügt in: v9.5.0

• <HTTP/2 Headers Object[]>

Ein Array von Objekten, die die ausgehenden Informations- (zusätzlichen) Header enthalten, die für diesen Http2Stream gesendet wurden.

http2stream.sentTrailers

Hinzugefügt in: v9.5.0

• <HTTP/2 Headers Object>

Ein Objekt, das die ausgehenden Trailer enthält, die für diesen HttpStream gesendet wurden.

http2stream.session

Hinzugefügt in: v8.4.0

• <Http2Session>

Ein Verweis auf die Http2Session-Instanz, der diesen Http2Stream besitzt. Der Wert wird undefined sein, nachdem die Http2Stream-Instanz zerstört wurde.

http2stream.setTimeout(msecs, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v8.4.0	Hinzugefügt in: v8.4.0

• msecs <number>
• callback <Function>

ESM

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

// Den Stream abbrechen, wenn innerhalb von 5 Sekunden keine Aktivität stattfindet
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': '/' })

// Den Stream abbrechen, wenn innerhalb von 5 Sekunden keine Aktivität stattfindet
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

http2stream.state

Hinzugefügt in: v8.4.0

Stellt verschiedene Informationen über den aktuellen Zustand des Http2Stream bereit.

• <Objekt>
  • localWindowSize <Zahl> Die Anzahl der Bytes, die der verbundene Peer für diesen Http2Stream senden darf, ohne ein WINDOW_UPDATE zu erhalten.
  • state <Zahl> Ein Flag, das den Low-Level-Zustand des Http2Stream, wie von nghttp2 bestimmt, angibt.
  • localClose <Zahl> 1, wenn dieser Http2Stream lokal geschlossen wurde.
  • remoteClose <Zahl> 1, wenn dieser Http2Stream remote geschlossen wurde.
  • sumDependencyWeight <Zahl> Die Summe der Gewichte aller Http2Stream-Instanzen, die von diesem Http2Stream abhängen, wie mit PRIORITY-Frames angegeben.
  • weight <Zahl> Das Prioritätsgewicht dieses Http2Stream.

Ein aktueller Zustand dieses Http2Stream.

http2stream.sendTrailers(headers)

Hinzugefügt in: v10.0.0

• headers <HTTP/2 Header-Objekt>

Sendet einen nachträglichen HEADERS-Frame an den verbundenen HTTP/2-Peer. Diese Methode führt zum sofortigen Schließen des Http2Stream und darf nur aufgerufen werden, nachdem das Ereignis 'wantTrailers' emittiert wurde. Beim Senden einer Anfrage oder einer Antwort muss die Option options.waitForTrailers gesetzt werden, um den Http2Stream nach dem letzten DATA-Frame offen zu halten, damit Trailer gesendet werden können.

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

Die HTTP/1-Spezifikation verbietet es, dass Trailer HTTP/2-Pseudo-Header-Felder (z. B. ':method', ':path', usw.) enthalten.

Klasse: ClientHttp2Stream

Hinzugefügt in: v8.4.0

• Erweitert <Http2Stream>

Die Klasse ClientHttp2Stream ist eine Erweiterung von Http2Stream, die ausschließlich bei HTTP/2-Clients verwendet wird. Http2Stream-Instanzen auf dem Client liefern Ereignisse wie 'response' und 'push', die nur auf dem Client relevant sind.

Ereignis: 'continue'

Hinzugefügt in: v8.5.0

Wird ausgegeben, wenn der Server einen Status 100 Continue sendet, in der Regel, weil die Anfrage Expect: 100-continue enthielt. Dies ist eine Anweisung, dass der Client den Anforderungstext senden soll.

Ereignis: 'headers'

Hinzugefügt in: v8.4.0

• headers <HTTP/2-Header-Objekt>
• flags <number>

Das Ereignis 'headers' wird ausgegeben, wenn ein zusätzlicher Header-Block für einen Stream empfangen wird, z. B. wenn ein Block von 1xx-Informationsheadern empfangen wird. Der Listener-Callback erhält das HTTP/2-Header-Objekt und die mit den Headern verknüpften Flags.

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

Ereignis: 'push'

Hinzugefügt in: v8.4.0

• headers <HTTP/2-Header-Objekt>
• flags <number>

Das Ereignis 'push' wird ausgegeben, wenn Response-Header für einen Server-Push-Stream empfangen werden. Der Listener-Callback erhält das HTTP/2-Header-Objekt und die mit den Headern verknüpften Flags.

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

Ereignis: 'response'

Hinzugefügt in: v8.4.0

• headers <HTTP/2-Header-Objekt>
• flags <number>

Das Ereignis 'response' wird ausgegeben, wenn ein Response-HEADERS-Frame für diesen Stream vom verbundenen HTTP/2-Server empfangen wurde. Der Listener wird mit zwei Argumenten aufgerufen: einem Object, das das empfangene HTTP/2-Header-Objekt enthält, und den mit den Headern verknüpften Flags.

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

Klasse: ServerHttp2Stream

Hinzugefügt in: v8.4.0

• Erweitert: <Http2Stream>

Die Klasse ServerHttp2Stream ist eine Erweiterung von Http2Stream, die ausschließlich auf HTTP/2-Servern verwendet wird. Http2Stream-Instanzen auf dem Server bieten zusätzliche Methoden wie http2stream.pushStream() und http2stream.respond(), die nur auf dem Server relevant sind.

http2stream.additionalHeaders(headers)

Hinzugefügt in: v8.4.0

• headers <HTTP/2-Header-Objekt>

Sendet einen zusätzlichen informativen HEADERS-Frame an den verbundenen HTTP/2-Peer.

http2stream.headersSent

Hinzugefügt in: v8.4.0

• <boolean>

true, wenn Header gesendet wurden, andernfalls false (schreibgeschützt).

http2stream.pushAllowed

Hinzugefügt in: v8.4.0

• <boolean>

Schreibgeschützte Eigenschaft, die dem Flag SETTINGS_ENABLE_PUSH des letzten SETTINGS-Frames des Remote-Clients zugeordnet ist. Ist true, wenn der Remote-Peer Push-Streams akzeptiert, andernfalls false. Die Einstellungen sind für jeden Http2Stream in der gleichen Http2Session gleich.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v8.4.0	Hinzugefügt in: v8.4.0

• headers <HTTP/2-Header-Objekt>

• options <Object>

  • exclusive <boolean> Wenn true und parent einen übergeordneten Stream identifiziert, wird der erstellte Stream zur alleinigen direkten Abhängigkeit des übergeordneten Streams gemacht, wobei alle anderen bestehenden Abhängigen zu einer Abhängigkeit des neu erstellten Streams werden. Standardwert: false.
  • parent <number> Gibt die numerische Kennung eines Streams an, von dem der neu erstellte Stream abhängig ist.

• callback <Function> Callback, der aufgerufen wird, sobald der Push-Stream initiiert wurde.

  • err <Error>
  • pushStream <ServerHttp2Stream> Das zurückgegebene pushStream-Objekt.
  • headers <HTTP/2-Header-Objekt> Header-Objekt, mit dem der pushStream initiiert wurde.

Initiiert einen Push-Stream. Der Callback wird mit der neuen Http2Stream-Instanz aufgerufen, die für den als zweites Argument übergebenen Push-Stream erstellt wurde, oder mit einem als erstes Argument übergebenen Error.

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

Das Setzen des Gewichts eines Push-Streams ist im HEADERS-Frame nicht zulässig. Geben Sie einen weight-Wert an http2stream.priority mit der auf true gesetzten Option silent weiter, um die serverseitige Bandbreitenverteilung zwischen gleichzeitigen Streams zu ermöglichen.

Das Aufrufen von http2stream.pushStream() innerhalb eines Push-Streams ist nicht zulässig und löst einen Fehler aus.

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

[Historie]

Version	Änderungen
v14.5.0, v12.19.0	Ermöglicht das explizite Setzen von Datums-Headern.
v8.4.0	Hinzugefügt in: v8.4.0

• headers <HTTP/2 Header-Objekt>
• options <Objekt>
  • endStream <boolean> Auf true setzen, um anzugeben, dass die Antwort keine Nutzdaten enthalten wird.
  • waitForTrailers <boolean> Wenn true, emittiert der Http2Stream das Ereignis 'wantTrailers', nachdem der letzte DATA-Frame gesendet wurde.

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

Initiiert eine Antwort. Wenn die Option options.waitForTrailers gesetzt ist, wird das Ereignis 'wantTrailers' unmittelbar nach dem Einreihen des letzten zu sendenden Nutzdaten-Chunks emittiert. Die Methode http2stream.sendTrailers() kann dann verwendet werden, um dem Peer nachfolgende Header-Felder zu senden.

Wenn options.waitForTrailers gesetzt ist, schließt der Http2Stream nicht automatisch, wenn der letzte DATA-Frame übertragen wurde. Der Benutzercode muss entweder http2stream.sendTrailers() oder http2stream.close() aufrufen, um den Http2Stream zu schließen.

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

[Verlauf]

Version	Änderungen
v14.5.0, v12.19.0	Ermöglicht das explizite Setzen von Datums-Headern.
v12.12.0	Die Option fd kann jetzt ein FileHandle sein.
v10.0.0	Jeder lesbare File Descriptor, nicht unbedingt für eine reguläre Datei, wird jetzt unterstützt.
v8.4.0	Hinzugefügt in: v8.4.0

• fd <number> | <FileHandle> Ein lesbarer File Descriptor.
• headers <HTTP/2 Header-Objekt>
• options <Object>
  • statCheck <Function>
  • waitForTrailers <boolean> Wenn true, sendet der Http2Stream das Ereignis 'wantTrailers' nach dem Senden des letzten DATA-Frames.
  • offset <number> Die Offset-Position, an der mit dem Lesen begonnen werden soll.
  • length <number> Die Datenmenge aus dem fd, die gesendet werden soll.

Initiiert eine Antwort, deren Daten aus dem angegebenen File Descriptor gelesen werden. Es wird keine Validierung des angegebenen File Descriptors durchgeführt. Wenn beim Versuch, Daten mit dem File Descriptor zu lesen, ein Fehler auftritt, wird der Http2Stream mit einem RST_STREAM-Frame unter Verwendung des Standardcodes INTERNAL_ERROR geschlossen.

Bei Verwendung wird die Duplex-Schnittstelle des Http2Stream-Objekts automatisch geschlossen.

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

Die optionale Funktion options.statCheck kann angegeben werden, um dem Benutzercode die Möglichkeit zu geben, zusätzliche Content-Header basierend auf den fs.Stat-Details des angegebenen fd zu setzen. Wenn die Funktion statCheck bereitgestellt wird, führt die Methode http2stream.respondWithFD() einen fs.fstat()-Aufruf durch, um Details zum bereitgestellten File Descriptor zu sammeln.

Die Optionen offset und length können verwendet werden, um die Antwort auf eine bestimmte Bereichsuntermenge zu beschränken. Dies kann beispielsweise verwendet werden, um HTTP-Range-Anforderungen zu unterstützen.

Der File Descriptor oder FileHandle wird nicht geschlossen, wenn der Stream geschlossen wird, daher muss er manuell geschlossen werden, sobald er nicht mehr benötigt wird. Die gleichzeitige Verwendung desselben File Descriptors für mehrere Streams wird nicht unterstützt und kann zu Datenverlust führen. Die Wiederverwendung eines File Descriptors nach Abschluss eines Streams wird unterstützt.

Wenn die Option options.waitForTrailers gesetzt ist, wird das Ereignis 'wantTrailers' unmittelbar nach dem Einfügen des letzten Datenstücks der zu sendenden Nutzlast ausgelöst. Die Methode http2stream.sendTrailers() kann dann verwendet werden, um nachfolgende Headerfelder an den Peer zu senden.

Wenn options.waitForTrailers gesetzt ist, schließt der Http2Stream nicht automatisch, wenn der letzte DATA-Frame übertragen wird. Der Benutzercode muss entweder http2stream.sendTrailers() oder http2stream.close() aufrufen, um den Http2Stream zu schließen.

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

[Versionsverlauf]

Version	Änderungen
v14.5.0, v12.19.0	Ermöglicht das explizite Setzen von Datumsheadern.
v10.0.0	Jetzt wird jede lesbare Datei unterstützt, nicht nur reguläre Dateien.
v8.4.0	Hinzugefügt in: v8.4.0

• path <string> | <Buffer> | <URL>
• headers <HTTP/2-Header-Objekt>
• options <Object>
  • statCheck <Function>
  • onError <Function> Callback-Funktion, die im Fehlerfall vor dem Senden aufgerufen wird.
  • waitForTrailers <boolean> Wenn true, sendet der Http2Stream das Ereignis 'wantTrailers' nach dem Senden des letzten DATA-Frames.
  • offset <number> Die Offset-Position, an der mit dem Lesen begonnen werden soll.
  • length <number> Die Datenmenge aus dem fd, die gesendet werden soll.

Sendet eine reguläre Datei als Antwort. path muss eine reguläre Datei angeben, andernfalls wird ein 'error'-Ereignis für das Http2Stream-Objekt emittiert.

Bei Verwendung wird die Duplex-Schnittstelle des Http2Stream-Objekts automatisch geschlossen.

Die optionale Funktion options.statCheck kann angegeben werden, um dem Benutzercode die Möglichkeit zu geben, zusätzliche Content-Header basierend auf den fs.Stat-Details der angegebenen Datei zu setzen:

Wenn beim Versuch, die Dateidaten zu lesen, ein Fehler auftritt, wird der Http2Stream mit einem RST_STREAM-Frame unter Verwendung des Standardcodes INTERNAL_ERROR geschlossen. Wenn der onError-Callback definiert ist, wird dieser aufgerufen. Andernfalls wird der Stream zerstört.

Beispiel mit einem Dateipfad:

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() kann einen Fehler auslösen, wenn der Stream von
    // der anderen Seite zerstört wurde.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // Tatsächliche Fehlerbehandlung durchführen.
      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() kann einen Fehler auslösen, wenn der Stream von
    // der anderen Seite zerstört wurde.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // Tatsächliche Fehlerbehandlung durchführen.
      console.error(err)
    }
    stream.end()
  }

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

Die Funktion options.statCheck kann auch verwendet werden, um den Sendevorgang durch Rückgabe von false abzubrechen. Beispielsweise kann eine bedingte Anfrage die Stat-Ergebnisse überprüfen, um festzustellen, ob die Datei geändert wurde, um eine entsprechende 304-Antwort zurückzugeben:

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    // Stat hier überprüfen...
    stream.respond({ ':status': 304 })
    return false // Sendevorgang abbrechen
  }
  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) {
    // Stat hier überprüfen...
    stream.respond({ ':status': 304 })
    return false // Sendevorgang abbrechen
  }
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck })
})

Das Header-Feld content-length wird automatisch gesetzt.

Die Optionen offset und length können verwendet werden, um die Antwort auf eine bestimmte Bereichsuntermenge zu beschränken. Dies kann beispielsweise verwendet werden, um HTTP-Bereichsanforderungen zu unterstützen.

Die Funktion options.onError kann auch verwendet werden, um alle Fehler zu behandeln, die vor dem Beginn der Bereitstellung der Datei auftreten können. Das Standardverhalten besteht darin, den Stream zu zerstören.

Wenn die Option options.waitForTrailers gesetzt ist, wird das Ereignis 'wantTrailers' unmittelbar nach dem Einfügen des letzten zu sendenden Nutzlastdatenstücks ausgelöst. Die Methode http2stream.sendTrailers() kann dann verwendet werden, um dem Peer nachfolgende Header-Felder zu senden.

Wenn options.waitForTrailers gesetzt ist, schließt der Http2Stream nicht automatisch, wenn der letzte DATA-Frame übertragen wird. Der Benutzercode muss entweder http2stream.sendTrailers() oder http2stream.close() aufrufen, um den Http2Stream zu schließen.

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

Klasse: Http2Server

Hinzugefügt in: v8.4.0

• Erweitert: <net.Server>

Instanzen von Http2Server werden mit der Funktion http2.createServer() erstellt. Die Klasse Http2Server wird nicht direkt vom Modul node:http2 exportiert.

Ereignis: 'checkContinue'

Hinzugefügt in: v8.5.0

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

Wenn ein 'request'-Listener registriert ist oder http2.createServer() eine Callback-Funktion erhält, wird das Ereignis 'checkContinue' jedes Mal ausgelöst, wenn eine Anfrage mit einem HTTP Expect: 100-continue empfangen wird. Wenn dieses Ereignis nicht abgehört wird, antwortet der Server automatisch mit dem Status 100 Continue, falls zutreffend.

Die Behandlung dieses Ereignisses beinhaltet den Aufruf von response.writeContinue(), wenn der Client den Request-Body weiter senden soll, oder die Generierung einer entsprechenden HTTP-Antwort (z. B. 400 Bad Request), wenn der Client den Request-Body nicht weiter senden soll.

Wenn dieses Ereignis ausgelöst und behandelt wird, wird das Ereignis 'request' nicht ausgelöst.

Ereignis: 'connection'

Hinzugefügt in: v8.4.0

• socket <stream.Duplex>

Dieses Ereignis wird ausgelöst, wenn ein neuer TCP-Stream hergestellt wird. socket ist typischerweise ein Objekt vom Typ net.Socket. Normalerweise möchten Benutzer auf dieses Ereignis nicht zugreifen.

Dieses Ereignis kann auch explizit von Benutzern ausgelöst werden, um Verbindungen in den HTTP-Server einzuschleusen. In diesem Fall kann jeder Duplex-Stream übergeben werden.

Ereignis: 'request'

Hinzugefügt in: v8.4.0

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

Wird jedes Mal ausgelöst, wenn eine Anfrage vorliegt. Es kann mehrere Anfragen pro Sitzung geben. Siehe die Kompatibilitäts-API.

Ereignis: 'session'

Hinzugefügt in: v8.4.0

• session <ServerHttp2Session>

Das Ereignis 'session' wird ausgelöst, wenn ein neuer Http2Session vom Http2Server erstellt wird.

Ereignis: 'sessionError'

Hinzugefügt in: v8.4.0

• error <Error>
• session <ServerHttp2Session>

Das Ereignis 'sessionError' wird ausgelöst, wenn ein 'error'-Ereignis von einem Http2Session-Objekt ausgelöst wird, das dem Http2Server zugeordnet ist.

Ereignis: 'stream'

Hinzugefügt in: v8.4.0

• stream <Http2Stream> Ein Verweis auf den Stream
• headers <HTTP/2-Header-Objekt> Ein Objekt, das die Header beschreibt
• flags <number> Die zugehörigen numerischen Flags
• rawHeaders <Array> Ein Array, das die Rohheadernamen gefolgt von ihren jeweiligen Werten enthält.

Das Ereignis 'stream' wird ausgelöst, wenn ein 'stream'-Ereignis von einer Http2Session ausgelöst wurde, die dem Server zugeordnet ist.

Siehe auch Http2Session's 'stream'-Ereignis.

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

Ereignis: 'timeout'

[Verlauf]

Version	Änderungen
v13.0.0	Das Standard-Timeout wurde von 120s auf 0 (kein Timeout) geändert.
v8.4.0	Hinzugefügt in: v8.4.0

Das Ereignis 'timeout' wird ausgelöst, wenn für eine bestimmte Anzahl von Millisekunden, die mit http2server.setTimeout() festgelegt werden, keine Aktivität auf dem Server besteht. Standardwert: 0 (kein Timeout)

server.close([callback])

Hinzugefügt in: v8.4.0

• callback <Funktion>

Stoppt den Server daran, neue Sitzungen zu etablieren. Dies verhindert nicht, dass aufgrund der persistenten Natur von HTTP/2-Sitzungen neue Anforderungsströme erstellt werden. Um den Server ordnungsgemäß herunterzufahren, rufen Sie http2session.close() für alle aktiven Sitzungen auf.

Wenn callback bereitgestellt wird, wird es erst aufgerufen, wenn alle aktiven Sitzungen geschlossen wurden, obwohl der Server bereits keine neuen Sitzungen mehr zulässt. Weitere Details finden Sie unter net.Server.close().

server[Symbol.asyncDispose]()

Hinzugefügt in: v20.4.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Ruft server.close() auf und gibt ein Promise zurück, das erfüllt wird, wenn der Server geschlossen wurde.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v13.0.0	Das Standard-Timeout wurde von 120s auf 0 (kein Timeout) geändert.
v8.4.0	Hinzugefügt in: v8.4.0

• msecs <Zahl> Standardwert: 0 (kein Timeout)
• callback <Funktion>
• Gibt zurück: <Http2Server>

Wird verwendet, um den Timeout-Wert für HTTP2-Serveranforderungen festzulegen und eine Callback-Funktion festzulegen, die aufgerufen wird, wenn nach msecs Millisekunden keine Aktivität auf dem Http2Server vorliegt.

Der angegebene Callback wird als Listener für das Ereignis 'timeout' registriert.

Falls callback keine Funktion ist, wird ein neuer ERR_INVALID_ARG_TYPE-Fehler ausgelöst.

server.timeout

[Verlauf]

Version	Änderungen
v13.0.0	Das Standard-Timeout wurde von 120s auf 0 (kein Timeout) geändert.
v8.4.0	Hinzugefügt in: v8.4.0

• <number> Timeout in Millisekunden. Standard: 0 (kein Timeout)

Die Anzahl der Millisekunden Inaktivität, bevor eine Socket-Verbindung als zeitüberschritten gilt.

Ein Wert von 0 deaktiviert das Timeout-Verhalten bei eingehenden Verbindungen.

Die Socket-Timeout-Logik wird bei der Verbindung eingerichtet. Daher wirkt sich die Änderung dieses Werts nur auf neue Verbindungen zum Server aus, nicht auf bestehende Verbindungen.

server.updateSettings([settings])

Hinzugefügt in: v15.1.0, v14.17.0

• settings <HTTP/2 Settings Object>

Wird verwendet, um den Server mit den angegebenen Einstellungen zu aktualisieren.

Wirft ERR_HTTP2_INVALID_SETTING_VALUE für ungültige settings-Werte.

Wirft ERR_INVALID_ARG_TYPE für ein ungültiges settings-Argument.

Klasse: Http2SecureServer

Hinzugefügt in: v8.4.0

• Erweitert: <tls.Server>

Instanzen von Http2SecureServer werden mit der Funktion http2.createSecureServer() erstellt. Die Klasse Http2SecureServer wird nicht direkt vom Modul node:http2 exportiert.

Ereignis: 'checkContinue'

Hinzugefügt in: v8.5.0

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

Wenn ein 'request' -Listener registriert ist oder http2.createSecureServer() eine Callback-Funktion erhält, wird das Ereignis 'checkContinue' jedes Mal ausgelöst, wenn eine Anfrage mit einem HTTP Expect: 100-continue empfangen wird. Wenn dieses Ereignis nicht abgehört wird, antwortet der Server automatisch mit dem Status 100 Continue, falls zutreffend.

Die Behandlung dieses Ereignisses beinhaltet den Aufruf von response.writeContinue(), wenn der Client den Request-Body weiter senden soll, oder die Generierung einer entsprechenden HTTP-Antwort (z. B. 400 Bad Request), wenn der Client den Request-Body nicht weiter senden soll.

Wenn dieses Ereignis ausgelöst und behandelt wird, wird das Ereignis 'request' nicht ausgelöst.

Ereignis: 'connection'

Hinzugefügt in: v8.4.0

• socket <stream.Duplex>

Dieses Ereignis wird ausgelöst, wenn ein neuer TCP-Stream hergestellt wird, bevor der TLS-Handshake beginnt. socket ist typischerweise ein Objekt vom Typ net.Socket. Normalerweise möchten Benutzer nicht auf dieses Ereignis zugreifen.

Dieses Ereignis kann auch explizit von Benutzern ausgelöst werden, um Verbindungen in den HTTP-Server einzubringen. In diesem Fall kann jeder Duplex-Stream übergeben werden.

Ereignis: 'request'

Hinzugefügt in: v8.4.0

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

Wird bei jeder Anfrage ausgelöst. Es kann mehrere Anfragen pro Sitzung geben. Siehe die Kompatibilitäts-API.

Ereignis: 'session'

Hinzugefügt in: v8.4.0

• session <ServerHttp2Session>

Das Ereignis 'session' wird ausgelöst, wenn eine neue Http2Session von Http2SecureServer erstellt wird.

Ereignis: 'sessionError'

Hinzugefügt in: v8.4.0

• error <Error>
• session <ServerHttp2Session>

Das Ereignis 'sessionError' wird ausgelöst, wenn ein 'error'-Ereignis von einem Http2Session-Objekt ausgelöst wird, das dem Http2SecureServer zugeordnet ist.

Ereignis: 'stream'

Hinzugefügt in: v8.4.0

• stream <Http2Stream> Ein Verweis auf den Stream
• headers <HTTP/2-Header-Objekt> Ein Objekt, das die Header beschreibt
• flags <number> Die zugehörigen numerischen Flags
• rawHeaders <Array> Ein Array, das die Rohheadernamen gefolgt von ihren jeweiligen Werten enthält.

Das Ereignis 'stream' wird ausgelöst, wenn ein 'stream'-Ereignis von einer Http2Session ausgelöst wurde, die dem Server zugeordnet ist.

Siehe auch das Ereignis Http2Session's 'stream'.

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

Ereignis: 'timeout'

Hinzugefügt in: v8.4.0

Das Ereignis 'timeout' wird ausgelöst, wenn für eine bestimmte Anzahl von Millisekunden, die mit http2secureServer.setTimeout() festgelegt werden, keine Aktivität auf dem Server stattfindet. Standard: 2 Minuten.

Ereignis: 'unknownProtocol'

[Verlauf]

Version	Änderungen
v19.0.0	Dieses Ereignis wird nur ausgelöst, wenn der Client während des TLS-Handshakes keine ALPN-Erweiterung übertragen hat.
v8.4.0	Hinzugefügt in: v8.4.0

• socket <stream.Duplex>

Das Ereignis 'unknownProtocol' wird ausgelöst, wenn ein verbindungsaufbauender Client kein zulässiges Protokoll (d. h. HTTP/2 oder HTTP/1.1) aushandeln kann. Der Ereignishandler empfängt die Socket zur Behandlung. Wenn kein Listener für dieses Ereignis registriert ist, wird die Verbindung beendet. Ein Timeout kann mithilfe der Option 'unknownProtocolTimeout' angegeben werden, die an http2.createSecureServer() übergeben wird.

In früheren Versionen von Node.js wurde dieses Ereignis ausgelöst, wenn allowHTTP1 auf false gesetzt ist und der Client während des TLS-Handshakes entweder keine ALPN-Erweiterung sendet oder eine ALPN-Erweiterung sendet, die nicht HTTP/2 (h2) enthält. Neuere Versionen von Node.js lösen dieses Ereignis nur aus, wenn allowHTTP1 auf false gesetzt ist und der Client keine ALPN-Erweiterung sendet. Wenn der Client eine ALPN-Erweiterung sendet, die nicht HTTP/2 (oder HTTP/1.1, wenn allowHTTP1 auf true gesetzt ist) enthält, schlägt der TLS-Handshake fehl und es wird keine sichere Verbindung hergestellt.

Siehe die Kompatibilitäts-API.

server.close([callback])

Hinzugefügt in: v8.4.0

• callback <Function>

Hält den Server davon ab, neue Sitzungen zu erstellen. Dies verhindert nicht, dass aufgrund der persistenten Natur von HTTP/2-Sitzungen neue Anforderungsströme erstellt werden. Um den Server ordnungsgemäß herunterzufahren, rufen Sie http2session.close() für alle aktiven Sitzungen auf.

Wenn callback bereitgestellt wird, wird es erst aufgerufen, nachdem alle aktiven Sitzungen geschlossen wurden, obwohl der Server bereits keine neuen Sitzungen mehr zulässt. Siehe tls.Server.close() für weitere Details.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben einer ungültigen Callback-Funktion an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v8.4.0	Hinzugefügt in: v8.4.0

• msecs <number> Standardwert: 120000 (2 Minuten)
• callback <Function>
• Rückgabewert: <Http2SecureServer>

Wird verwendet, um den Timeout-Wert für sichere HTTP/2-Serveranforderungen festzulegen und eine Callback-Funktion zu setzen, die aufgerufen wird, wenn nach msecs Millisekunden keine Aktivität auf dem Http2SecureServer vorliegt.

Die angegebene Callback-Funktion wird als Listener für das Ereignis 'timeout' registriert.

Falls callback keine Funktion ist, wird ein neuer ERR_INVALID_ARG_TYPE-Fehler ausgelöst.

server.timeout

[Historie]

Version	Änderungen
v13.0.0	Der Standard-Timeout wurde von 120 Sekunden auf 0 (kein Timeout) geändert.
v8.4.0	Hinzugefügt in: v8.4.0

• <number> Timeout in Millisekunden. Standardwert: 0 (kein Timeout)

Die Anzahl der Millisekunden Inaktivität, bevor eine Socket-Verbindung als zeitüberschritten gilt.

Ein Wert von 0 deaktiviert das Timeout-Verhalten für eingehende Verbindungen.

Die Socket-Timeout-Logik wird bei der Verbindung eingerichtet. Daher wirkt sich eine Änderung dieses Werts nur auf neue Verbindungen zum Server aus, nicht auf bestehende Verbindungen.

server.updateSettings([settings])

Hinzugefügt in: v15.1.0, v14.17.0

• settings <HTTP/2 Settings Object>

Wird verwendet, um den Server mit den angegebenen Einstellungen zu aktualisieren.

Wirft ERR_HTTP2_INVALID_SETTING_VALUE für ungültige settings-Werte.

Wirft ERR_INVALID_ARG_TYPE für ein ungültiges settings-Argument.

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

[Historie]

Version	Änderungen
v23.0.0	streamResetBurst und streamResetRate hinzugefügt.
v13.0.0	PADDING_STRATEGY_CALLBACK wurde als äquivalent zu PADDING_STRATEGY_ALIGNED definiert und selectPadding wurde entfernt.
v13.3.0, v12.16.0	Option maxSessionRejectedStreams mit einem Standardwert von 100 hinzugefügt.
v13.3.0, v12.16.0	Option maxSessionInvalidFrames mit einem Standardwert von 1000 hinzugefügt.
v12.4.0	Der Parameter options unterstützt jetzt Optionen von net.createServer().
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Option unknownProtocolTimeout mit einem Standardwert von 10000 hinzugefügt.
v14.4.0, v12.18.0, v10.21.0	Option maxSettings mit einem Standardwert von 32 hinzugefügt.
v9.6.0	Die Optionen Http1IncomingMessage und Http1ServerResponse hinzugefügt.
v8.9.3	Die Option maxOutstandingPings mit einer Standardgrenze von 10 hinzugefügt.
v8.9.3	Die Option maxHeaderListPairs mit einer Standardgrenze von 128 Header-Paaren hinzugefügt.
v8.4.0	Hinzugefügt in: v8.4.0

• options <Object>

  • maxDeflateDynamicTableSize <number> Legt die maximale dynamische Tabellen Größe für das Deflatieren von Header-Feldern fest. Standardwert: 4Kib.

  • maxSettings <number> Legt die maximale Anzahl von Einstellungseinträgen pro SETTINGS-Frame fest. Der zulässige Minimalwert ist 1. Standardwert: 32.

  • maxSessionMemory<number> Legt den maximalen Speicher fest, den die Http2Session verwenden darf. Der Wert wird in Megabyte ausgedrückt, z. B. entspricht 1 1 Megabyte. Der zulässige Minimalwert ist 1. Dies ist eine kreditbasierte Grenze. Bestehende Http2Streams können dazu führen, dass diese Grenze überschritten wird, aber neue Http2Stream-Instanzen werden abgelehnt, solange diese Grenze überschritten wird. Die aktuelle Anzahl der Http2Stream-Sitzungen, die aktuelle Speichernutzung der Header-Kompressionstabellen, die aktuell zum Senden gepufferten Daten und unbestätigte PING- und SETTINGS-Frames werden alle auf die aktuelle Grenze angerechnet. Standardwert: 10.

  • maxHeaderListPairs <number> Legt die maximale Anzahl von Header-Einträgen fest. Dies ähnelt server.maxHeadersCount oder request.maxHeadersCount im Modul node:http. Der Minimalwert ist 4. Standardwert: 128.

  • maxOutstandingPings <number> Legt die maximale Anzahl ausstehender, unbestätigter Pings fest. Standardwert: 10.

  • maxSendHeaderBlockLength <number> Legt die maximal zulässige Größe für einen serialisierten, komprimierten Block von Headern fest. Versuche, Header zu senden, die diese Grenze überschreiten, führen dazu, dass ein Ereignis 'frameError' ausgelöst und der Stream geschlossen und zerstört wird. Obwohl dies die maximal zulässige Größe für den gesamten Header-Block festlegt, hat nghttp2 (die interne HTTP/2-Bibliothek) eine Grenze von 65536 für jedes dekomprimierte Schlüssel-Wert-Paar.

  • paddingStrategy <number> Die Strategie, die verwendet wird, um die Menge der zu verwendenden Auffüllung für HEADERS- und DATA-Frames zu bestimmen. Standardwert: http2.constants.PADDING_STRATEGY_NONE. Der Wert kann einer der folgenden sein:

  • http2.constants.PADDING_STRATEGY_NONE: Es wird keine Auffüllung angewendet.

  • http2.constants.PADDING_STRATEGY_MAX: Es wird die maximale Auffüllmenge angewendet, die von der internen Implementierung bestimmt wird.

  • http2.constants.PADDING_STRATEGY_ALIGNED: Versucht, genügend Auffüllung anzuwenden, um sicherzustellen, dass die Gesamtlänge des Frames, einschließlich der 9-Byte-Header, ein Vielfaches von 8 ist. Für jeden Frame gibt es eine maximal zulässige Anzahl von Auffüllbytes, die durch den aktuellen Flow-Control-Zustand und die Einstellungen bestimmt wird. Wenn dieses Maximum kleiner ist als die berechnete Menge, die erforderlich ist, um die Ausrichtung sicherzustellen, wird das Maximum verwendet und die Gesamtlänge des Frames ist nicht unbedingt auf 8 Byte ausgerichtet.

  • peerMaxConcurrentStreams <number> Legt die maximale Anzahl gleichzeitiger Streams für den Remote-Peer fest, als ob ein SETTINGS-Frame empfangen worden wäre. Wird überschrieben, wenn der Remote-Peer seinen eigenen Wert für maxConcurrentStreams festlegt. Standardwert: 100.

  • maxSessionInvalidFrames <integer> Legt die maximale Anzahl ungültiger Frames fest, die toleriert werden, bevor die Sitzung geschlossen wird. Standardwert: 1000.

  • maxSessionRejectedStreams <integer> Legt die maximale Anzahl von Streams fest, die bei der Erstellung abgelehnt werden und toleriert werden, bevor die Sitzung geschlossen wird. Jede Ablehnung ist mit einem NGHTTP2_ENHANCE_YOUR_CALM-Fehler verbunden, der dem Peer mitteilen sollte, keine weiteren Streams zu öffnen. Das fortgesetzte Öffnen von Streams wird daher als Zeichen eines fehlerhaften Peers angesehen. Standardwert: 100.

  • settings <HTTP/2 Settings Object> Die anfänglichen Einstellungen, die beim Herstellen der Verbindung an den Remote-Peer gesendet werden sollen.

  • streamResetBurst <number> und streamResetRate <number> Legt die Ratenbegrenzung für das eingehende Zurücksetzen des Streams (RST_STREAM-Frame) fest. Beide Einstellungen müssen gesetzt sein, um eine Wirkung zu haben, und haben standardmäßig 1000 bzw. 33.

  • remoteCustomSettings <Array> Das Array von ganzzahligen Werten bestimmt die Einstellungstypen, die in der Eigenschaft CustomSettings der empfangenen remoteSettings enthalten sind. Weitere Informationen zu den zulässigen Einstellungstypen finden Sie in der Eigenschaft CustomSettings des Objekts Http2Settings.

  • Http1IncomingMessage <http.IncomingMessage> Gibt die IncomingMessage-Klasse an, die für das HTTP/1-Fallback verwendet werden soll. Nützlich zum Erweitern der ursprünglichen http.IncomingMessage. Standardwert: http.IncomingMessage.

  • Http1ServerResponse <http.ServerResponse> Gibt die ServerResponse-Klasse an, die für das HTTP/1-Fallback verwendet werden soll. Nützlich zum Erweitern der ursprünglichen http.ServerResponse. Standardwert: http.ServerResponse.

  • Http2ServerRequest <http2.Http2ServerRequest> Gibt die Http2ServerRequest-Klasse an, die verwendet werden soll. Nützlich zum Erweitern der ursprünglichen Http2ServerRequest. Standardwert: Http2ServerRequest.

  • Http2ServerResponse <http2.Http2ServerResponse> Gibt die Http2ServerResponse-Klasse an, die verwendet werden soll. Nützlich zum Erweitern der ursprünglichen Http2ServerResponse. Standardwert: Http2ServerResponse.

  • unknownProtocolTimeout <number> Gibt ein Timeout in Millisekunden an, das ein Server warten soll, wenn ein 'unknownProtocol' ausgelöst wird. Wenn die Socket-Verbindung bis zu diesem Zeitpunkt nicht zerstört wurde, wird sie vom Server zerstört. Standardwert: 10000.

  • ...: Jede beliebige Option von net.createServer() kann angegeben werden.

• onRequestHandler <Function> Siehe Kompatibilitäts-API

• Rückgabewert: <Http2Server>

Gibt eine net.Server-Instanz zurück, die Http2Session-Instanzen erstellt und verwaltet.

Da keine Browser bekannt sind, die unverschlüsseltes HTTP/2 unterstützen, ist die Verwendung von http2.createSecureServer() erforderlich, wenn mit Browser-Clients kommuniziert wird.

ESM

import { createServer } from 'node:http2'

// Ein unverschlüsselter HTTP/2-Server wird erstellt.
// Da keine Browser bekannt sind, die unverschlüsseltes HTTP/2 unterstützen,
// ist die Verwendung von `createSecureServer()`
// bei der Kommunikation mit Browser-Clients erforderlich.
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')

// Ein unverschlüsselter HTTP/2-Server wird erstellt.
// Da keine Browser bekannt sind, die unverschlüsseltes HTTP/2 unterstützen,
// ist die Verwendung von `http2.createSecureServer()`
// bei der Kommunikation mit Browser-Clients erforderlich.
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])

[Versionsgeschichte]

Version	Änderungen
v13.0.0	PADDING_STRATEGY_CALLBACK wurde als äquivalent zu PADDING_STRATEGY_ALIGNED definiert und selectPadding wurde entfernt.
v13.3.0, v12.16.0	Option maxSessionRejectedStreams mit Standardwert 100 hinzugefügt.
v13.3.0, v12.16.0	Option maxSessionInvalidFrames mit Standardwert 1000 hinzugefügt.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Option unknownProtocolTimeout mit Standardwert 10000 hinzugefügt.
v14.4.0, v12.18.0, v10.21.0	Option maxSettings mit Standardwert 32 hinzugefügt.
v10.12.0	Option origins hinzugefügt, um beim Start von Http2Session automatisch einen ORIGIN-Frame zu senden.
v8.9.3	Option maxOutstandingPings mit Standardgrenze von 10 hinzugefügt.
v8.9.3	Option maxHeaderListPairs mit Standardgrenze von 128 Header-Paaren hinzugefügt.
v8.4.0	Hinzugefügt in: v8.4.0

• options <Objekt>

  • allowHTTP1 <boolean> Eingehende Client-Verbindungen, die HTTP/2 nicht unterstützen, werden bei true auf HTTP/1.x herabgestuft. Siehe das Ereignis 'unknownProtocol'. Siehe ALPN-Verhandlung. Standard: false.

  • maxDeflateDynamicTableSize <number> Legt die maximale dynamische Tabellengröße zum Deflatern von Header-Feldern fest. Standard: 4Kib.

  • maxSettings <number> Legt die maximale Anzahl von Einstellungseinträgen pro SETTINGS-Frame fest. Der zulässige Mindestwert ist 1. Standard: 32.

  • maxSessionMemory<number> Legt den maximalen Speicher fest, den die Http2Session verwenden darf. Der Wert wird in Megabyte angegeben, z. B. 1 entspricht 1 Megabyte. Der zulässige Mindestwert ist 1. Dies ist eine kreditbasierte Grenze; vorhandene Http2Streams können diese Grenze überschreiten, aber neue Http2Stream-Instanzen werden abgelehnt, solange diese Grenze überschritten wird. Die aktuelle Anzahl der Http2Stream-Sitzungen, die aktuelle Speichernutzung der Header-Kompressionstabellen, die aktuell zum Senden gepufferten Daten und unbestätigte PING- und SETTINGS-Frames werden alle auf die aktuelle Grenze angerechnet. Standard: 10.

  • maxHeaderListPairs <number> Legt die maximale Anzahl von Header-Einträgen fest. Dies ähnelt server.maxHeadersCount oder request.maxHeadersCount im Modul node:http. Der Mindestwert ist 4. Standard: 128.

  • maxOutstandingPings <number> Legt die maximale Anzahl ausstehender, unbestätigter Pings fest. Standard: 10.

  • maxSendHeaderBlockLength <number> Legt die maximal zulässige Größe für einen serialisierten, komprimierten Header-Block fest. Versuche, Header zu senden, die diese Grenze überschreiten, führen dazu, dass ein 'frameError'-Ereignis ausgelöst und der Stream geschlossen und zerstört wird.

  • paddingStrategy <number> Strategie zur Bestimmung der zu verwendenden Padding-Menge für HEADERS- und DATA-Frames. Standard: http2.constants.PADDING_STRATEGY_NONE. Der Wert kann einer der folgenden sein:

  • http2.constants.PADDING_STRATEGY_NONE: Es wird kein Padding angewendet.

  • http2.constants.PADDING_STRATEGY_MAX: Es wird die maximale Padding-Menge angewendet, die von der internen Implementierung bestimmt wird.

  • http2.constants.PADDING_STRATEGY_ALIGNED: Versucht, genügend Padding anzuwenden, um sicherzustellen, dass die Gesamtlänge des Frames, einschließlich der 9-Byte-Header, ein Vielfaches von 8 ist. Für jeden Frame gibt es eine maximal zulässige Anzahl von Padding-Bytes, die durch den aktuellen Flusssteuerungszustand und die Einstellungen bestimmt wird. Wenn dieses Maximum kleiner ist als die berechnete Menge, die benötigt wird, um die Ausrichtung sicherzustellen, wird das Maximum verwendet und die Gesamtlänge des Frames ist nicht unbedingt auf 8 Bytes ausgerichtet.

  • peerMaxConcurrentStreams <number> Legt die maximale Anzahl gleichzeitiger Streams für den Remote-Peer fest, als ob ein SETTINGS-Frame empfangen worden wäre. Wird überschrieben, wenn der Remote-Peer seinen eigenen Wert für maxConcurrentStreams festlegt. Standard: 100.

  • maxSessionInvalidFrames <integer> Legt die maximale Anzahl ungültiger Frames fest, die toleriert werden, bevor die Sitzung geschlossen wird. Standard: 1000.

  • maxSessionRejectedStreams <integer> Legt die maximale Anzahl von beim Erstellen abgelehnten Streams fest, die toleriert werden, bevor die Sitzung geschlossen wird. Jede Ablehnung ist mit einem NGHTTP2_ENHANCE_YOUR_CALM-Fehler verbunden, der dem Peer mitteilen sollte, keine weiteren Streams zu öffnen. Das fortgesetzte Öffnen von Streams wird daher als Zeichen für einen fehlerhaften Peer angesehen. Standard: 100.

  • settings <HTTP/2-Einstellungsobjekt> Die anfänglichen Einstellungen, die beim Herstellen einer Verbindung an den Remote-Peer gesendet werden sollen.

  • remoteCustomSettings <Array> Das Array von ganzzahligen Werten bestimmt die Einstellungstypen, die in der Eigenschaft customSettings der empfangenen remoteSettings enthalten sind. Weitere Informationen zu den zulässigen Einstellungstypen finden Sie in der Eigenschaft customSettings des Objekts Http2Settings.

  • ...: Es können beliebige Optionen von tls.createServer() angegeben werden. Für Server sind die Identitätsoptionen (pfx oder key/cert) in der Regel erforderlich.

  • origins <string[]> Ein Array von Origin-Strings, die unmittelbar nach dem Erstellen einer neuen Server-Http2Session in einem ORIGIN-Frame gesendet werden sollen.

  • unknownProtocolTimeout <number> Gibt ein Timeout in Millisekunden an, das ein Server warten soll, wenn ein Ereignis 'unknownProtocol' ausgelöst wird. Wenn der Socket bis zu diesem Zeitpunkt nicht zerstört wurde, wird der Server ihn zerstören. Standard: 10000.

• onRequestHandler <Funktion> Siehe Kompatibilitäts-API

• Rückgabewert: <Http2SecureServer>

Gibt eine tls.Server-Instanz zurück, die Http2Session-Instanzen erstellt und verwaltet.

ESM

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

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

// Erstellt einen sicheren HTTP/2-Server
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'),
}

// Erstellt einen sicheren HTTP/2-Server
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])

[Historie]

Version	Änderungen
v13.0.0	PADDING_STRATEGY_CALLBACK wurde mit PADDING_STRATEGY_ALIGNED gleichgesetzt, und selectPadding wurde entfernt.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Option unknownProtocolTimeout mit einem Standardwert von 10000 hinzugefügt.
v14.4.0, v12.18.0, v10.21.0	Option maxSettings mit einem Standardwert von 32 hinzugefügt.
v8.9.3	Option maxOutstandingPings mit einem Standardlimit von 10 hinzugefügt.
v8.9.3	Option maxHeaderListPairs mit einem Standardlimit von 128 Header-Paaren hinzugefügt.
v8.4.0	Hinzugefügt in: v8.4.0

• authority <string> | <URL> Der zu verbindende entfernte HTTP/2-Server. Dies muss die Form einer minimalen, gültigen URL mit dem Präfix http:// oder https://, Hostnamen und IP-Port (wenn ein nicht standardmäßiger Port verwendet wird) haben. Benutzerinformationen (Benutzer-ID und Passwort), Pfad, Querystring und Fragmentdetails in der URL werden ignoriert.

• options <Object>

  • maxDeflateDynamicTableSize <number> Legt die maximale dynamische Tabellen­größe für das Deflaten von Header-Feldern fest. Standard: 4Kib.

  • maxSettings <number> Legt die maximale Anzahl von Einstellungseinträgen pro SETTINGS-Frame fest. Der zulässige Minimalwert ist 1. Standard: 32.

  • maxSessionMemory<number> Legt den maximalen Speicher fest, den die Http2Session verwenden darf. Der Wert wird in Megabyte angegeben, z. B. entspricht 1 1 Megabyte. Der zulässige Minimalwert ist 1. Dies ist ein kreditbasiertes Limit. Bestehende Http2Streams können dazu führen, dass dieses Limit überschritten wird, aber neue Http2Stream-Instanzen werden abgelehnt, solange dieses Limit überschritten wird. Die aktuelle Anzahl der Http2Stream-Sitzungen, die aktuelle Speichernutzung der Header-Kompressionstabellen, die aktuell zum Senden gepufferten Daten und nicht bestätigten PING- und SETTINGS-Frames werden alle auf das aktuelle Limit angerechnet. Standard: 10.

  • maxHeaderListPairs <number> Legt die maximale Anzahl von Headereinträgen fest. Dies ähnelt server.maxHeadersCount oder request.maxHeadersCount im Modul node:http. Der Minimalwert ist 1. Standard: 128.

  • maxOutstandingPings <number> Legt die maximale Anzahl ausstehender, nicht bestätigter Pings fest. Standard: 10.

  • maxReservedRemoteStreams <number> Legt die maximale Anzahl reservierter Push-Streams fest, die der Client zu einem beliebigen Zeitpunkt akzeptiert. Sobald die aktuelle Anzahl der aktuell reservierten Push-Streams dieses Limit erreicht, werden neue vom Server gesendete Push-Streams automatisch abgelehnt. Der zulässige Minimalwert ist 0. Der zulässige Maximalwert ist 2³¹-1. Ein negativer Wert setzt diese Option auf den maximal zulässigen Wert. Standard: 200.

  • maxSendHeaderBlockLength <number> Legt die maximal zulässige Größe für einen serialisierten, komprimierten Block von Headern fest. Versuche, Header zu senden, die dieses Limit überschreiten, führen dazu, dass ein Ereignis 'frameError' ausgelöst und der Stream geschlossen und zerstört wird.

  • paddingStrategy <number> Strategie zur Bestimmung der zu verwendenden Füllmenge für HEADERS- und DATA-Frames. Standard: http2.constants.PADDING_STRATEGY_NONE. Der Wert kann einer der folgenden sein:

  • http2.constants.PADDING_STRATEGY_NONE: Es wird keine Füllung angewendet.

  • http2.constants.PADDING_STRATEGY_MAX: Es wird die maximale Füllmenge angewendet, die von der internen Implementierung bestimmt wird.

  • http2.constants.PADDING_STRATEGY_ALIGNED: Versucht, genügend Füllung anzuwenden, um sicherzustellen, dass die Gesamtlänge des Frames, einschließlich der 9-Byte-Header, ein Vielfaches von 8 ist. Für jeden Frame gibt es eine maximal zulässige Anzahl von Füllbytes, die durch den aktuellen Flow-Control-Status und die Einstellungen bestimmt wird. Wenn dieses Maximum kleiner ist als die berechnete Menge, die zur Sicherstellung der Ausrichtung benötigt wird, wird das Maximum verwendet und die Gesamtlänge des Frames ist nicht unbedingt auf 8 Bytes ausgerichtet.

  • peerMaxConcurrentStreams <number> Legt die maximale Anzahl gleichzeitiger Streams für den Remote-Peer fest, als ob ein SETTINGS-Frame empfangen worden wäre. Wird überschrieben, wenn der Remote-Peer seinen eigenen Wert für maxConcurrentStreams festlegt. Standard: 100.

  • protocol <string> Das Protokoll, mit dem verbunden werden soll, falls nicht in authority festgelegt. Der Wert kann entweder 'http:' oder 'https:' sein. Standard: 'https:'

  • settings <HTTP/2 Settings Object> Die anfänglichen Einstellungen, die beim Herstellen der Verbindung an den Remote-Peer gesendet werden sollen.

  • remoteCustomSettings <Array> Das Array mit ganzzahligen Werten bestimmt die Einstellungstypen, die in der Eigenschaft CustomSettings der empfangenen remoteSettings enthalten sind. Weitere Informationen zu den zulässigen Einstellungstypen finden Sie in der Eigenschaft CustomSettings des Objekts Http2Settings.

  • createConnection <Function> Ein optionaler Rückruf, der die an connect übergebene URL-Instanz und das options-Objekt empfängt und einen beliebigen Duplex-Stream zurückgibt, der als Verbindung für diese Sitzung verwendet werden soll.

  • ...: Es können beliebige Optionen von net.connect() oder tls.connect() angegeben werden.

  • unknownProtocolTimeout <number> Gibt ein Timeout in Millisekunden an, das ein Server warten sollte, wenn ein Ereignis 'unknownProtocol' ausgelöst wird. Wenn die Socket innerhalb dieser Zeit nicht zerstört wurde, zerstört der Server sie. Standard: 10000.

• listener <Function> Wird als einmaliger Listener für das Ereignis 'connect' registriert.

• Gibt zurück: <ClientHttp2Session>

Gibt eine ClientHttp2Session-Instanz zurück.

ESM

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

/* Client verwenden */

client.close()

CJS

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

/* Client verwenden */

client.close()

http2.constants

Hinzugefügt in: v8.4.0

Fehlercodes für RST_STREAM und GOAWAY

Wert	Name	Konstante
0x00	Kein Fehler	http2.constants.NGHTTP2_NO_ERROR
0x01	Protokollfehler	http2.constants.NGHTTP2_PROTOCOL_ERROR
0x02	Interner Fehler	http2.constants.NGHTTP2_INTERNAL_ERROR
0x03	Flusskontrollfehler	http2.constants.NGHTTP2_FLOW_CONTROL_ERROR
0x04	Einstellungen Timeout	http2.constants.NGHTTP2_SETTINGS_TIMEOUT
0x05	Stream geschlossen	http2.constants.NGHTTP2_STREAM_CLOSED
0x06	Frame-Größenfehler	http2.constants.NGHTTP2_FRAME_SIZE_ERROR
0x07	Stream abgelehnt	http2.constants.NGHTTP2_REFUSED_STREAM
0x08	Abbrechen	http2.constants.NGHTTP2_CANCEL
0x09	Komprimierungsfehler	http2.constants.NGHTTP2_COMPRESSION_ERROR
0x0a	Verbindungsfehler	http2.constants.NGHTTP2_CONNECT_ERROR
0x0b	Beruhige dich	http2.constants.NGHTTP2_ENHANCE_YOUR_CALM
0x0c	Unzureichende Sicherheit	http2.constants.NGHTTP2_INADEQUATE_SECURITY
0x0d	HTTP/1.1 erforderlich	http2.constants.NGHTTP2_HTTP_1_1_REQUIRED

Das Ereignis 'timeout' wird ausgegeben, wenn für eine bestimmte Anzahl von Millisekunden, die mit http2server.setTimeout() festgelegt wurden, keine Aktivität auf dem Server stattfindet.

http2.getDefaultSettings()

Hinzugefügt in: v8.4.0

• Rückgabewert: <HTTP/2 Settings Objekt>

Gibt ein Objekt zurück, das die Standardeinstellungen für eine Http2Session-Instanz enthält. Diese Methode gibt jedes Mal eine neue Objektinstanz zurück, sodass die zurückgegebenen Instanzen sicher modifiziert werden können.

http2.getPackedSettings([settings])

Hinzugefügt in: v8.4.0

• settings <HTTP/2 Settings Objekt>
• Rückgabewert: <Buffer>

Gibt eine Buffer-Instanz zurück, die die serialisierte Darstellung der gegebenen HTTP/2-Einstellungen enthält, wie in der HTTP/2-Spezifikation angegeben. Dies ist für die Verwendung mit dem Header-Feld HTTP2-Settings vorgesehen.

ESM

import { getPackedSettings } from 'node:http2'

const packed = getPackedSettings({ enablePush: false })

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

CJS

const http2 = require('node:http2')

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

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

http2.getUnpackedSettings(buf)

Hinzugefügt in: v8.4.0

• buf <Buffer> | <TypedArray> Die gepackten Einstellungen.
• Rückgabewert: <HTTP/2 Settings Object>

Gibt ein HTTP/2 Settings Object zurück, das die deserialisierten Einstellungen aus dem gegebenen Buffer, wie von http2.getPackedSettings() erzeugt, enthält.

http2.performServerHandshake(socket[, options])

Hinzugefügt in: v21.7.0, v20.12.0

• socket <stream.Duplex>

• options <Object>

  • ...: Jede Option von http2.createServer() kann bereitgestellt werden.

• Rückgabewert: <ServerHttp2Session>

Erstellt eine HTTP/2-Serversitzung aus einer bestehenden Socketverbindung.

http2.sensitiveHeaders

Hinzugefügt in: v15.0.0, v14.18.0

• <symbol>

Dieses Symbol kann als Eigenschaft des HTTP/2-Header-Objekts mit einem Array-Wert gesetzt werden, um eine Liste von als sensibel betrachteten Headern bereitzustellen. Siehe Sensitive Header für weitere Details.

Header-Objekt

Header werden als eigene Eigenschaften in JavaScript-Objekten dargestellt. Die Eigenschaftsschlüssel werden in Kleinbuchstaben serialisiert. Eigenschaftswerte sollten Zeichenketten sein (wenn sie keine Zeichenketten sind, werden sie in Zeichenketten umgewandelt) oder ein Array von Zeichenketten (um mehr als einen Wert pro Header-Feld zu senden).

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

stream.respond(headers)

Header-Objekte, die an Callback-Funktionen übergeben werden, haben einen null-Prototypen. Das bedeutet, dass normale JavaScript-Objektmethoden wie Object.prototype.toString() und Object.prototype.hasOwnProperty() nicht funktionieren.

Für eingehende Header:

• Der :status-Header wird in eine number umgewandelt.
• Duplikate von :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 oder x-content-type-options werden verworfen.
• set-cookie ist immer ein Array. Duplikate werden dem Array hinzugefügt.
• Bei doppelten cookie-Headern werden die Werte mit '; ' verbunden.
• Bei allen anderen Headern werden die Werte mit ', ' verbunden.

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

Sensible Header

HTTP2-Header können als sensibel markiert werden. Dies bedeutet, dass der HTTP/2-Header-Komprimierungsalgorithmus sie niemals indiziert. Dies kann für Header-Werte mit niedriger Entropie sinnvoll sein, die für einen Angreifer als wertvoll angesehen werden könnten, z. B. Cookie oder Authorization. Um dies zu erreichen, fügen Sie den Header-Namen als Array zur Eigenschaft [http2.sensitiveHeaders] hinzu:

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)

Für einige Header, wie z. B. Authorization und kurze Cookie-Header, wird dieses Flag automatisch gesetzt.

Diese Eigenschaft wird auch für empfangene Header gesetzt. Sie enthält die Namen aller als sensibel markierten Header, einschließlich derjenigen, die automatisch so markiert wurden.

Einstellungsobjekt

[Historie]

Version	Änderungen
v12.12.0	Die Einstellung maxConcurrentStreams ist strenger.
v8.9.3	Die Einstellung maxHeaderListSize wird jetzt strikt durchgesetzt.
v8.4.0	Hinzugefügt in: v8.4.0

Die APIs http2.getDefaultSettings(), http2.getPackedSettings(), http2.createServer(), http2.createSecureServer(), http2session.settings(), http2session.localSettings und http2session.remoteSettings geben entweder ein Objekt zurück oder empfangen es als Eingabe, das Konfigurationseinstellungen für ein Http2Session-Objekt definiert. Diese Objekte sind gewöhnliche JavaScript-Objekte, die die folgenden Eigenschaften enthalten.

• headerTableSize <number> Gibt die maximale Anzahl von Bytes an, die für die Header-Komprimierung verwendet werden. Der zulässige Mindestwert ist 0. Der zulässige Maximalwert ist 2-1. Standard: 4096.
• enablePush <boolean> Gibt true an, wenn HTTP/2 Push Streams für die Http2Session-Instanzen zulässig sein sollen. Standard: true.
• initialWindowSize <number> Gibt die anfängliche Fenstergröße des Senders in Bytes für die Stream-Ebene der Flusskontrolle an. Der zulässige Mindestwert ist 0. Der zulässige Maximalwert ist 2-1. Standard: 65535.
• maxFrameSize <number> Gibt die Größe der größten Frame-Nutzlast in Bytes an. Der zulässige Mindestwert ist 16.384. Der zulässige Maximalwert ist 2-1. Standard: 16384.
• maxConcurrentStreams <number> Gibt die maximale Anzahl gleichzeitiger Streams an, die auf einer Http2Session zulässig sind. Es gibt keinen Standardwert, was impliziert, dass theoretisch mindestens 2-1 Streams gleichzeitig in einer Http2Session geöffnet sein können. Der Mindestwert ist 0. Der zulässige Maximalwert ist 2-1. Standard: 4294967295.
• maxHeaderListSize <number> Gibt die maximale Größe (unkomprimierte Oktette) der Header-Liste an, die akzeptiert wird. Der zulässige Mindestwert ist 0. Der zulässige Maximalwert ist 2-1. Standard: 65535.
• maxHeaderSize <number> Alias für maxHeaderListSize.
• enableConnectProtocol<boolean> Gibt true an, wenn das in RFC 8441 definierte "Extended Connect Protocol" aktiviert werden soll. Diese Einstellung ist nur sinnvoll, wenn sie vom Server gesendet wird. Sobald die Einstellung enableConnectProtocol für eine gegebene Http2Session aktiviert wurde, kann sie nicht mehr deaktiviert werden. Standard: false.
• customSettings <Object> Gibt zusätzliche Einstellungen an, die noch nicht in Node und den zugrunde liegenden Bibliotheken implementiert sind. Der Schlüssel des Objekts definiert den numerischen Wert des Einstellungstyps (wie im "HTTP/2 SETTINGS"-Register definiert, das von [RFC 7540] festgelegt wurde) und die Werte den tatsächlichen numerischen Wert der Einstellungen. Der Einstellungstyp muss eine ganze Zahl im Bereich von 1 bis 2^16-1 sein. Es sollte kein Einstellungstyp sein, der bereits von Node verarbeitet wird, d. h. derzeit sollte er größer als 6 sein, obwohl dies kein Fehler ist. Die Werte müssen vorzeichenlose ganze Zahlen im Bereich von 0 bis 2^32-1 sein. Derzeit werden maximal 10 benutzerdefinierte Einstellungen unterstützt. Es wird nur für das Senden von EINSTELLUNGEN oder für das Empfangen von Einstellungswerten unterstützt, die in den Optionen remoteCustomSettings des Server- oder Clientobjekts angegeben sind. Mischen Sie nicht den customSettings-Mechanismus für eine Einstellungs-ID mit Schnittstellen für die nativ verarbeiteten Einstellungen, falls eine Einstellung in einer zukünftigen Node-Version nativ unterstützt wird.

Alle zusätzlichen Eigenschaften des Einstellungsobjekts werden ignoriert.

Fehlerbehandlung

Es können verschiedene Arten von Fehlerbedingungen auftreten, wenn das Modul node:http2 verwendet wird:

Validierungsfehler treten auf, wenn ein falsches Argument, eine falsche Option oder ein falscher Einstellungswert übergeben wird. Diese werden immer durch einen synchronen throw gemeldet.

Zustandsfehler treten auf, wenn eine Aktion zum falschen Zeitpunkt versucht wird (z. B. der Versuch, Daten an einen Stream zu senden, nachdem dieser geschlossen wurde). Diese werden entweder durch einen synchronen throw oder über ein 'error'-Ereignis an den Objekten Http2Stream, Http2Session oder HTTP/2-Server gemeldet, abhängig davon, wo und wann der Fehler auftritt.

Interne Fehler treten auf, wenn eine HTTP/2-Sitzung unerwartet fehlschlägt. Diese werden über ein 'error'-Ereignis an den Objekten Http2Session oder HTTP/2-Server gemeldet.

Protokollfehler treten auf, wenn verschiedene HTTP/2-Protokollbeschränkungen verletzt werden. Diese werden entweder durch einen synchronen throw oder über ein 'error'-Ereignis an den Objekten Http2Stream, Http2Session oder HTTP/2-Server gemeldet, abhängig davon, wo und wann der Fehler auftritt.

Behandlung ungültiger Zeichen in Header-Namen und -Werten

Die HTTP/2-Implementierung wendet eine strengere Behandlung ungültiger Zeichen in HTTP-Header-Namen und -Werten an als die HTTP/1-Implementierung.

Header-Feldnamen sind nicht zwischen Groß- und Kleinschreibung zu unterscheiden und werden strikt als Kleinbuchstaben über die Leitung übertragen. Die von Node.js bereitgestellte API erlaubt es, Header-Namen als Zeichenfolgen mit gemischter Groß-/Kleinschreibung (z. B. Content-Type) festzulegen, konvertiert diese jedoch bei der Übertragung in Kleinbuchstaben (z. B. content-type).

Header-Feldnamen dürfen nur eines oder mehrere der folgenden ASCII-Zeichen enthalten: a-z, A-Z, 0-9, !, #, $, %, &, ', *, +, -, ., ^, _, ```(Backtick),|und~.

Die Verwendung ungültiger Zeichen in einem HTTP-Header-Feldnamen führt dazu, dass der Stream geschlossen wird und ein Protokollfehler gemeldet wird.

Header-Feldwerte werden nachsichtiger behandelt, sollten aber keine Zeilenumbruch- oder Wagenrücklaufzeichen enthalten und sollten gemäß den Anforderungen der HTTP-Spezifikation auf US-ASCII-Zeichen beschränkt sein.

Push-Streams auf dem Client

Um Push-Streams auf dem Client zu empfangen, setzen Sie einen Listener für das Ereignis 'stream' auf der ClientHttp2Session:

ESM

import { connect } from 'node:http2'

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

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', responseHeaders => {
    // Response-Header verarbeiten
  })
  pushedStream.on('data', chunk => {
    /* pushed Daten verarbeiten */
  })
})

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 => {
    // Response-Header verarbeiten
  })
  pushedStream.on('data', chunk => {
    /* pushed Daten verarbeiten */
  })
})

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

Unterstützung der CONNECT-Methode

Die CONNECT-Methode wird verwendet, um einen HTTP/2-Server als Proxy für TCP/IP-Verbindungen zu verwenden.

Ein einfacher TCP-Server:

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)

Ein HTTP/2 CONNECT-Proxy:

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') {
    // Nur CONNECT-Anfragen akzeptieren
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // Es ist sehr ratsam zu überprüfen, ob Hostname und Port
  // Dinge sind, mit denen sich dieser Proxy verbinden sollte.
  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') {
    // Nur CONNECT-Anfragen akzeptieren
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // Es ist sehr ratsam zu überprüfen, ob Hostname und Port
  // Dinge sind, mit denen sich dieser Proxy verbinden sollte.
  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)

Ein HTTP/2 CONNECT-Client:

ESM

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

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

//  `:path` und `:scheme` Header dürfen für CONNECT-Anfragen nicht
//  angegeben werden, sonst wird ein Fehler geworfen.
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(`Der Server sagt: ${data}`)
  client.close()
})
req.end('Jane')

CJS

const http2 = require('node:http2')

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

//  `:path` und `:scheme` Header dürfen für CONNECT-Anfragen nicht
//  angegeben werden, sonst wird ein Fehler geworfen.
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(`Der Server sagt: ${data}`)
  client.close()
})
req.end('Jane')

Das erweiterte CONNECT-Protokoll

RFC 8441 definiert eine Erweiterung namens "Extended CONNECT Protocol" für HTTP/2, die verwendet werden kann, um die Verwendung eines Http2Stream mit der CONNECT-Methode als Tunnel für andere Kommunikationsprotokolle (wie WebSockets) zu bootstrappen.

Die Verwendung des Extended CONNECT-Protokolls wird von HTTP/2-Servern durch die Einstellung enableConnectProtocol aktiviert:

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

Sobald der Client den SETTINGS-Frame vom Server empfängt, der angibt, dass das erweiterte CONNECT verwendet werden kann, kann er CONNECT-Anforderungen senden, die den HTTP/2-Pseudo-Header ':protocol' verwenden:

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

Kompatibilitäts-API

Die Kompatibilitäts-API hat das Ziel, eine ähnliche Entwicklererfahrung von HTTP/1 bei der Verwendung von HTTP/2 zu bieten, wodurch die Entwicklung von Anwendungen ermöglicht wird, die sowohl HTTP/1 als auch HTTP/2 unterstützen. Diese API zielt nur auf die öffentliche API von HTTP/1 ab. Viele Module verwenden jedoch interne Methoden oder Zustände, und diese werden nicht unterstützt, da es sich um eine völlig andere Implementierung handelt.

Das folgende Beispiel erstellt einen HTTP/2-Server mit der Kompatibilitäts-API:

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

Um einen gemischten HTTPS- und HTTP/2-Server zu erstellen, lesen Sie den Abschnitt zur ALPN-Verhandlung. Ein Upgrade von Nicht-TLS-HTTP/1-Servern wird nicht unterstützt.

Die HTTP/2-Kompatibilitäts-API besteht aus Http2ServerRequest und Http2ServerResponse. Sie zielen auf API-Kompatibilität mit HTTP/1 ab, verbergen jedoch nicht die Unterschiede zwischen den Protokollen. Beispielsweise wird die Statusmeldung für HTTP-Codes ignoriert.

ALPN-Verhandlung

Die ALPN-Verhandlung ermöglicht die Unterstützung von sowohl HTTPS als auch HTTP/2 über dieselbe Socketverbindung. Die Objekte req und res können entweder HTTP/1 oder HTTP/2 sein, und eine Anwendung muss sich auf die öffentliche API von HTTP/1 beschränken und erkennen, ob die Verwendung der erweiterten Funktionen von HTTP/2 möglich ist.

Das folgende Beispiel erstellt einen Server, der beide Protokolle unterstützt:

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) {
  // Erkennt, ob es sich um eine HTTPS- oder HTTP/2-Anfrage handelt
  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) {
  // Erkennt, ob es sich um eine HTTPS- oder HTTP/2-Anfrage handelt
  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,
    })
  )
}

Das Ereignis 'request' funktioniert sowohl bei HTTPS als auch bei HTTP/2 identisch.

Klasse: http2.Http2ServerRequest

Hinzugefügt in: v8.4.0

• Erweitert: <stream.Readable>

Ein Http2ServerRequest-Objekt wird von http2.Server oder http2.SecureServer erstellt und als erstes Argument an das Ereignis 'request' übergeben. Es kann verwendet werden, um auf den Anfragestatus, Header und Daten zuzugreifen.

Ereignis: 'aborted'

Hinzugefügt in: v8.4.0

Das Ereignis 'aborted' wird immer dann emittiert, wenn eine Http2ServerRequest-Instanz während der Kommunikation anormal abgebrochen wird.

Das Ereignis 'aborted' wird nur emittiert, wenn die beschreibbare Seite von Http2ServerRequest nicht beendet wurde.

Ereignis: 'close'

Hinzugefügt in: v8.4.0

Gibt an, dass der zugrunde liegende Http2Stream geschlossen wurde. Genau wie 'end' tritt dieses Ereignis nur einmal pro Antwort auf.

request.aborted

Hinzugefügt in: v10.1.0

• <boolean>

Die Eigenschaft request.aborted ist true, wenn die Anfrage abgebrochen wurde.

request.authority

Hinzugefügt in: v8.4.0

• <string>

Das Pseudo-Headerfeld authority der Anfrage. Da HTTP/2 es Anfragen erlaubt, entweder :authority oder host zu setzen, wird dieser Wert aus req.headers[':authority'] abgeleitet, falls vorhanden. Andernfalls wird er aus req.headers['host'] abgeleitet.

request.complete

Hinzugefügt in: v12.10.0

• <boolean>

Die Eigenschaft request.complete ist true, wenn die Anfrage abgeschlossen, abgebrochen oder zerstört wurde.

request.connection

Hinzugefügt in: v8.4.0

Seit v13.0.0 veraltet

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet. Verwenden Sie request.socket.

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

Siehe request.socket.

request.destroy([error])

Hinzugefügt in: v8.4.0

• error <Error>

Ruft destroy() auf dem Http2Stream auf, der die Http2ServerRequest empfangen hat. Wenn error angegeben wird, wird ein 'error'-Ereignis emittiert und error als Argument an alle Listener des Ereignisses übergeben.

Es tut nichts, wenn der Stream bereits zerstört wurde.

request.headers

Hinzugefügt in: v8.4.0

• <Object>

Das Objekt der Request-/Response-Header.

Schlüssel-Wert-Paare von Header-Namen und -Werten. Header-Namen werden in Kleinbuchstaben umgewandelt.

// Gibt etwas Ähnliches aus:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers)

Siehe HTTP/2 Headers Object.

In HTTP/2 werden der Request-Pfad, der Hostname, das Protokoll und die Methode als spezielle Header dargestellt, die mit dem Zeichen : versehen sind (z. B. ':path'). Diese speziellen Header werden im Objekt request.headers enthalten sein. Es ist darauf zu achten, diese speziellen Header nicht versehentlich zu modifizieren, da sonst Fehler auftreten können. Beispielsweise führt das Entfernen aller Header aus der Anfrage zu Fehlern:

removeAllHeaders(request.headers)
assert(request.url) // Fehlschlägt, weil der :path-Header entfernt wurde

request.httpVersion

Hinzugefügt in: v8.4.0

• <string>

Bei einer Serveranfrage die vom Client gesendete HTTP-Version. Bei einer Client-Antwort die HTTP-Version des verbundenen Servers. Gibt '2.0' zurück.

Auch message.httpVersionMajor ist die erste ganze Zahl und message.httpVersionMinor die zweite.

request.method

Hinzugefügt in: v8.4.0

• <string>

Die Request-Methode als Zeichenkette. Schreibgeschützt. Beispiele: 'GET', 'DELETE'.

request.rawHeaders

Hinzugefügt in: v8.4.0

• <string[]>

Die Liste der Rohdaten der Request-/Response-Header genau so, wie sie empfangen wurden.

Die Schlüssel und Werte befinden sich in derselben Liste. Es ist keine Liste von Tupeln. Daher sind die geraden Offsets Schlüsselwerte und die ungeraden Offsets die zugehörigen Werte.

Header-Namen werden nicht in Kleinbuchstaben umgewandelt, und Duplikate werden nicht zusammengeführt.

// Gibt etwas Ähnliches aus:
//
// [ '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

Hinzugefügt in: v8.4.0

• <string[]>

Die Rohdaten der Trailer-Schlüssel und -Werte der Anfrage/Antwort, genau so wie sie empfangen wurden. Nur beim Ereignis 'end' gefüllt.

request.scheme

Hinzugefügt in: v8.4.0

• <string>

Das Pseudo-Headerfeld des Anforderungsschemas, das den Schema-Anteil der Ziel-URL angibt.

request.setTimeout(msecs, callback)

Hinzugefügt in: v8.4.0

• msecs <number>
• callback <Function>
• Rückgabewert: <http2.Http2ServerRequest>

Setzt den Timeout-Wert des Http2Stream auf msecs. Wenn ein Callback angegeben wird, wird dieser als Listener für das Ereignis 'timeout' am Antwort-Objekt hinzugefügt.

Wenn kein 'timeout'-Listener zur Anfrage, der Antwort oder dem Server hinzugefügt wird, werden Http2Streams bei Timeout zerstört. Wenn ein Handler den Ereignissen 'timeout' der Anfrage, der Antwort oder des Servers zugewiesen ist, müssen zeitüberschreitende Sockets explizit behandelt werden.

request.socket

Hinzugefügt in: v8.4.0

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

Gibt ein Proxy-Objekt zurück, das als net.Socket (oder tls.TLSSocket) fungiert, aber Getter, Setter und Methoden basierend auf HTTP/2-Logik anwendet.

Die Eigenschaften destroyed, readable und writable werden von request.stream abgerufen und auf diesem gesetzt.

Die Methoden destroy, emit, end, on und once werden auf request.stream aufgerufen.

Die Methode setTimeout wird auf request.stream.session aufgerufen.

pause, read, resume und write lösen einen Fehler mit dem Code ERR_HTTP2_NO_SOCKET_MANIPULATION aus. Siehe Http2Session und Sockets für weitere Informationen.

Alle anderen Interaktionen werden direkt an das Socket weitergeleitet. Bei TLS-Unterstützung verwenden Sie request.socket.getPeerCertificate(), um die Authentifizierungsdetails des Clients zu erhalten.

request.stream

Hinzugefügt in: v8.4.0

• <Http2Stream>

Das Http2Stream-Objekt, das der Anfrage zugrunde liegt.

request.trailers

Hinzugefügt in: v8.4.0

• <Object>

Das Objekt für die Trailer der Anfrage/Antwort. Nur beim Ereignis 'end' gefüllt.

request.url

Hinzugefügt in: v8.4.0

• <string>

Anfrage-URL-Zeichenkette. Diese enthält nur die URL, die in der eigentlichen HTTP-Anfrage vorhanden ist. Wenn die Anfrage lautet:

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

Dann ist request.url:

'/status?name=ryan'

Um die URL in ihre Bestandteile zu zerlegen, kann new URL() verwendet werden:

$ 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: ''
}

Klasse: http2.Http2ServerResponse

Hinzugefügt in: v8.4.0

• Erweitert: <Stream>

Dieses Objekt wird intern von einem HTTP-Server erstellt, nicht vom Benutzer. Es wird als zweiter Parameter an das Ereignis 'request' übergeben.

Ereignis: 'close'

Hinzugefügt in: v8.4.0

Gibt an, dass der zugrunde liegende Http2Stream beendet wurde, bevor response.end() aufgerufen oder den Flush durchführen konnte.

Ereignis: 'finish'

Hinzugefügt in: v8.4.0

Wird ausgegeben, wenn die Antwort gesendet wurde. Genauer gesagt, wird dieses Ereignis ausgegeben, wenn das letzte Segment der Antwort-Header und des Antwortkörpers an das HTTP/2-Multiplexing für die Übertragung über das Netzwerk übergeben wurde. Es bedeutet nicht, dass der Client bereits etwas empfangen hat.

Nach diesem Ereignis werden keine weiteren Ereignisse für das Antwort-Objekt ausgegeben.

response.addTrailers(headers)

Hinzugefügt in: v8.4.0

• headers <Objekt>

Diese Methode fügt der Antwort HTTP-Trailer-Header (ein Header, aber am Ende der Nachricht) hinzu.

Der Versuch, einen Header-Feldnamen oder -wert zu setzen, der ungültige Zeichen enthält, führt zu einem geworfenen TypeError.

response.appendHeader(name, value)

Hinzugefügt in: v21.7.0, v20.12.0

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

Fügt dem Header-Objekt einen einzelnen Header-Wert hinzu.

Wenn der Wert ein Array ist, entspricht dies dem mehrmaligen Aufrufen dieser Methode.

Wenn es keine vorherigen Werte für den Header gab, entspricht dies dem Aufrufen von response.setHeader().

Der Versuch, einen Header-Feldnamen oder -wert zu setzen, der ungültige Zeichen enthält, führt zu einem geworfenen TypeError.

// Gibt Header einschließlich "set-cookie: a" und "set-cookie: b" zurück
const server = http2.createServer((req, res) => {
  res.setHeader('set-cookie', 'a')
  res.appendHeader('set-cookie', 'b')
  res.writeHead(200)
  res.end('ok')
})

response.connection

Hinzugefügt in: v8.4.0

Veraltet seit: v13.0.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet. Verwenden Sie response.socket.

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

Siehe response.socket.

response.createPushResponse(headers, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v8.4.0	Hinzugefügt in: v8.4.0

• headers <HTTP/2 Header-Objekt> Ein Objekt, das die Header beschreibt
• callback <Funktion> Wird einmal aufgerufen, wenn http2stream.pushStream() abgeschlossen ist, oder entweder wenn der Versuch, den gepushten Http2Stream zu erstellen, fehlgeschlagen ist oder abgelehnt wurde, oder der Zustand von Http2ServerRequest vor dem Aufruf der http2stream.pushStream()-Methode geschlossen ist
  • err <Error>
  • res <http2.Http2ServerResponse> Das neu erstellte Http2ServerResponse-Objekt

Rufen Sie http2stream.pushStream() mit den angegebenen Headern auf und verpacken Sie den gegebenen Http2Stream in eine neu erstellte Http2ServerResponse als Rückrufparameter, wenn erfolgreich. Wenn Http2ServerRequest geschlossen ist, wird der Rückruf mit einem Fehler ERR_HTTP2_INVALID_STREAM aufgerufen.

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

[Versionsgeschichte]

Version	Änderungen
v10.0.0	Diese Methode gibt nun eine Referenz zu ServerResponse zurück.
v8.4.0	Hinzugefügt in: v8.4.0

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Rückgabewert: <this>

Diese Methode signalisiert dem Server, dass alle Antwortheader und der Antwortkörper gesendet wurden; der Server sollte diese Nachricht als abgeschlossen betrachten. Die Methode response.end() MUSS für jede Antwort aufgerufen werden.

Wenn data angegeben ist, entspricht dies dem Aufruf von response.write(data, encoding) gefolgt von response.end(callback).

Wenn callback angegeben ist, wird es aufgerufen, wenn der Antwortstrom abgeschlossen ist.

response.finished

Hinzugefügt in: v8.4.0

Veraltet seit: v13.4.0, v12.16.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet. Verwenden Sie response.writableEnded.

• <boolean>

Boolescher Wert, der angibt, ob die Antwort abgeschlossen ist. Beginnt mit false. Nach der Ausführung von response.end() wird der Wert true.

response.getHeader(name)

Hinzugefügt in: v8.4.0

• name <string>
• Rückgabewert: <string>

Liest einen Header aus, der bereits in die Warteschlange eingereiht, aber noch nicht an den Client gesendet wurde. Der Name ist nicht Groß-/Kleinschreibung-sensitiv.

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

response.getHeaderNames()

Hinzugefügt in: v8.4.0

• Rückgabewert: <string[]>

Gibt ein Array zurück, das die eindeutigen Namen der aktuellen ausgehenden Header enthält. Alle Header-Namen werden in Kleinbuchstaben dargestellt.

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

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

response.getHeaders()

Hinzugefügt in: v8.4.0

• Rückgabewert: <Object>

Gibt eine flache Kopie der aktuellen ausgehenden Header zurück. Da eine flache Kopie verwendet wird, können Array-Werte ohne zusätzliche Aufrufe verschiedener header-bezogener http-Modulmethoden verändert werden. Die Schlüssel des zurückgegebenen Objekts sind die Header-Namen und die Werte sind die entsprechenden Header-Werte. Alle Header-Namen werden in Kleinbuchstaben dargestellt.

Das von der Methode response.getHeaders() zurückgegebene Objekt erbt nicht prototypisch vom JavaScript Object. Das bedeutet, dass typische Object-Methoden wie obj.toString(), obj.hasOwnProperty() und andere nicht definiert sind und nicht funktionieren werden.

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)

Hinzugefügt in: v8.4.0

• name <string>
• Rückgabewert: <boolean>

Gibt true zurück, wenn der durch name identifizierte Header aktuell in den ausgehenden Headern gesetzt ist. Die Header-Namensübereinstimmung ist nicht case-sensitiv.

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

response.headersSent

Hinzugefügt in: v8.4.0

• <boolean>

true, wenn Header gesendet wurden, andernfalls false (schreibgeschützt).

response.removeHeader(name)

Hinzugefügt in: v8.4.0

• name <string>

Entfernt einen Header, der für das implizite Senden in die Warteschlange gestellt wurde.

response.removeHeader('Content-Encoding')

response.req

Hinzugefügt in: v15.7.0

• <http2.Http2ServerRequest>

Ein Verweis auf das ursprüngliche HTTP2 request-Objekt.

response.sendDate

Hinzugefügt in: v8.4.0

• <boolean>

Wenn true, wird der Date-Header automatisch generiert und in der Antwort gesendet, wenn er nicht bereits in den Headern vorhanden ist. Standardmäßig auf true gesetzt.

Dies sollte nur für Tests deaktiviert werden; HTTP erfordert den Date-Header in Antworten.

response.setHeader(name, value)

Hinzugefügt in: v8.4.0

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

Setzt einen einzelnen Header-Wert für implizite Header. Wenn dieser Header bereits in den zu sendenden Headern vorhanden ist, wird sein Wert ersetzt. Verwenden Sie hier ein Array von Strings, um mehrere Header mit dem gleichen Namen zu senden.

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

oder

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

Der Versuch, einen Header-Feldnamen oder -wert zu setzen, der ungültige Zeichen enthält, führt zu einem Auslösen eines TypeError.

Wenn Header mit response.setHeader() gesetzt wurden, werden sie mit allen Headern zusammengeführt, die an response.writeHead() übergeben wurden, wobei die an response.writeHead() übergebenen Header Vorrang haben.

// Gibt content-type = text/plain zurück
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])

Hinzugefügt in: v8.4.0

• msecs <number>
• callback <Function>
• Rückgabewert: <http2.Http2ServerResponse>

Setzt den Timeout-Wert des Http2Stream auf msecs. Wenn ein Callback angegeben wird, wird dieser als Listener für das Ereignis 'timeout' am Response-Objekt hinzugefügt.

Wenn kein 'timeout'-Listener zum Request, zur Response oder zum Server hinzugefügt wird, werden Http2Streams bei Timeout zerstört. Wenn ein Handler den 'timeout'-Ereignissen des Requests, der Response oder des Servers zugewiesen ist, müssen zeitüberschreitende Sockets explizit behandelt werden.

response.socket

Hinzugefügt in: v8.4.0

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

Gibt ein Proxy-Objekt zurück, das als net.Socket (oder tls.TLSSocket) fungiert, aber Getter, Setter und Methoden basierend auf der HTTP/2-Logik anwendet.

Die Eigenschaften destroyed, readable und writable werden von response.stream abgerufen und darauf gesetzt.

Die Methoden destroy, emit, end, on und once werden auf response.stream aufgerufen.

Die Methode setTimeout wird auf response.stream.session aufgerufen.

pause, read, resume und write lösen einen Fehler mit dem Code ERR_HTTP2_NO_SOCKET_MANIPULATION aus. Weitere Informationen finden Sie unter Http2Session und Sockets.

Alle anderen Interaktionen werden direkt an das Socket weitergeleitet.

ESM

import { createServer } from 'node:http2'
const server = createServer((req, res) => {
  const ip = req.socket.remoteAddress
  const port = req.socket.remotePort
  res.end(`Ihre IP-Adresse ist ${ip} und Ihr Quellport ist ${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(`Ihre IP-Adresse ist ${ip} und Ihr Quellport ist ${port}.`)
  })
  .listen(3000)

response.statusCode

Hinzugefügt in: v8.4.0

• <number>

Bei Verwendung impliziter Header (ohne expliziten Aufruf von response.writeHead()) steuert diese Eigenschaft den Statuscode, der an den Client gesendet wird, wenn die Header ausgegeben werden.

response.statusCode = 404

Nachdem der Response-Header an den Client gesendet wurde, gibt diese Eigenschaft den tatsächlich gesendeten Statuscode an.

response.statusMessage

Hinzugefügt in: v8.4.0

• <string>

Statusmeldungen werden von HTTP/2 (RFC 7540 8.1.2.4) nicht unterstützt. Es wird eine leere Zeichenkette zurückgegeben.

response.stream

Hinzugefügt in: v8.4.0

• <Http2Stream>

Das Http2Stream-Objekt, das der Antwort zugrunde liegt.

response.writableEnded

Hinzugefügt in: v12.9.0

• <boolean>

Ist true, nachdem response.end() aufgerufen wurde. Diese Eigenschaft gibt nicht an, ob die Daten ausgegeben wurden. Verwenden Sie stattdessen writable.writableFinished.

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

Hinzugefügt in: v8.4.0

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Rückgabewert: <boolean>

Wenn diese Methode aufgerufen wird und response.writeHead() nicht aufgerufen wurde, wird auf den impliziten Header-Modus umgeschaltet und die impliziten Header ausgegeben.

Dies sendet einen Teil des Antwortkörpers. Diese Methode kann mehrmals aufgerufen werden, um aufeinanderfolgende Teile des Körpers bereitzustellen.

Im Modul node:http wird der Antwortkörper weggelassen, wenn die Anfrage eine HEAD-Anfrage ist. Ebenso dürfen die Antworten 204 und 304 keinen Nachrichtenkörper enthalten.

chunk kann eine Zeichenkette oder ein Puffer sein. Wenn chunk eine Zeichenkette ist, gibt der zweite Parameter an, wie sie in einen Byte-Stream codiert werden soll. Standardmäßig ist die encoding 'utf8'. callback wird aufgerufen, wenn dieser Datenblock ausgegeben wurde.

Dies ist der unformatierte HTTP-Body und hat nichts mit höherwertigen Codierungen von Multipart-Body zu tun, die verwendet werden können.

Beim ersten Aufruf von response.write() werden die gepufferten Headerinformationen und der erste Teil des Körpers an den Client gesendet. Beim zweiten Aufruf von response.write() geht Node.js davon aus, dass Daten gestreamt werden, und sendet die neuen Daten separat. Das heißt, die Antwort wird bis zum ersten Teil des Körpers gepuffert.

Gibt true zurück, wenn die gesamten Daten erfolgreich in den Kernel-Puffer geschrieben wurden. Gibt false zurück, wenn alle oder Teile der Daten im Benutzer-Speicher gepuffert wurden. 'drain' wird emittiert, wenn der Puffer wieder frei ist.

response.writeContinue()

Hinzugefügt in: v8.4.0

Sendet den Status 100 Continue an den Client und gibt an, dass der Anforderungstext gesendet werden sollte. Siehe das Ereignis 'checkContinue' bei Http2Server und Http2SecureServer.

response.writeEarlyHints(hints)

Hinzugefügt in: v18.11.0

• hints <Object>

Sendet den Status 103 Early Hints an den Client mit einem Link-Header, der angibt, dass der User Agent die verlinkten Ressourcen vorladen/vorverbinden kann. hints ist ein Objekt, das die Werte der Header enthält, die mit der Early Hints-Nachricht gesendet werden sollen.

Beispiel

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

[Verlauf]

Version	Änderungen
v11.10.0, v10.17.0	Gibt this von writeHead() zurück, um das Verketten mit end() zu ermöglichen.
v8.4.0	Hinzugefügt in: v8.4.0

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• Rückgabewert: <http2.Http2ServerResponse>

Sendet einen Antwort-Header an die Anfrage. Der Statuscode ist ein dreistelliger HTTP-Statuscode, wie z. B. 404. Das letzte Argument, headers, sind die Antwort-Header.

Gibt einen Verweis auf Http2ServerResponse zurück, sodass Aufrufe verkettet werden können.

Für die Kompatibilität mit HTTP/1 kann eine menschenlesbare statusMessage als zweites Argument übergeben werden. Da die statusMessage innerhalb von HTTP/2 jedoch keine Bedeutung hat, hat das Argument keine Auswirkung und es wird eine Prozesswarnung ausgegeben.

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

Content-Length wird in Bytes, nicht in Zeichen angegeben. Die Buffer.byteLength()-API kann verwendet werden, um die Anzahl der Bytes in einer gegebenen Kodierung zu bestimmen. Bei ausgehenden Nachrichten überprüft Node.js nicht, ob Content-Length und die Länge des übertragenen Texts gleich sind oder nicht. Beim Empfangen von Nachrichten verwirft Node.js jedoch automatisch Nachrichten, wenn Content-Length nicht mit der tatsächlichen Nutzlastgröße übereinstimmt.

Diese Methode darf höchstens einmal pro Nachricht aufgerufen werden, bevor response.end() aufgerufen wird.

Wenn response.write() oder response.end() vor dem Aufruf dieser Methode aufgerufen werden, werden die impliziten/veränderlichen Header berechnet und diese Funktion aufgerufen.

Wenn Header mit response.setHeader() gesetzt wurden, werden sie mit allen an response.writeHead() übergebenen Headern zusammengeführt, wobei die an response.writeHead() übergebenen Header Vorrang haben.

// Gibt content-type = text/plain zurück
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')
})

Der Versuch, einen Header-Feldnamen oder -wert zu setzen, der ungültige Zeichen enthält, führt zu einem Auslösen eines TypeError.

Erfassung von HTTP/2-Leistungsmetriken

Die Performance Observer-API kann verwendet werden, um grundlegende Leistungsmetriken für jede Http2Session- und Http2Stream-Instanz zu erfassen.

ESM

import { PerformanceObserver } from 'node:perf_hooks'

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // gibt 'http2' aus
  if (entry.name === 'Http2Session') {
    // Eintrag enthält Statistiken über die Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Eintrag enthält Statistiken über die 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) // gibt 'http2' aus
  if (entry.name === 'Http2Session') {
    // Eintrag enthält Statistiken über die Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Eintrag enthält Statistiken über die Http2Stream
  }
})
obs.observe({ entryTypes: ['http2'] })

Die entryType-Eigenschaft des PerformanceEntry-Objekts wird 'http2' sein.

Die name-Eigenschaft des PerformanceEntry-Objekts wird entweder 'Http2Stream' oder 'Http2Session' sein.

Wenn name gleich Http2Stream ist, enthält der PerformanceEntry die folgenden zusätzlichen Eigenschaften:

• bytesRead <number> Die Anzahl der empfangenen DATA-Frame-Bytes für diesen Http2Stream.
• bytesWritten <number> Die Anzahl der gesendeten DATA-Frame-Bytes für diesen Http2Stream.
• id <number> Der Bezeichner des zugeordneten Http2Stream.
• timeToFirstByte <number> Die Anzahl der Millisekunden, die zwischen dem startTime des PerformanceEntry und dem Empfang des ersten DATA-Frames vergangen sind.
• timeToFirstByteSent <number> Die Anzahl der Millisekunden, die zwischen dem startTime des PerformanceEntry und dem Senden des ersten DATA-Frames vergangen sind.
• timeToFirstHeader <number> Die Anzahl der Millisekunden, die zwischen dem startTime des PerformanceEntry und dem Empfang des ersten Headers vergangen sind.

Wenn name gleich Http2Session ist, enthält der PerformanceEntry die folgenden zusätzlichen Eigenschaften:

• bytesRead <number> Die Anzahl der für diese Http2Session empfangenen Bytes.
• bytesWritten <number> Die Anzahl der für diese Http2Session gesendeten Bytes.
• framesReceived <number> Die Anzahl der von der Http2Session empfangenen HTTP/2-Frames.
• framesSent <number> Die Anzahl der von der Http2Session gesendeten HTTP/2-Frames.
• maxConcurrentStreams <number> Die maximale Anzahl gleichzeitig geöffneter Streams während der Lebensdauer der Http2Session.
• pingRTT <number> Die Anzahl der Millisekunden, die seit der Übertragung eines PING-Frames und dem Empfang seiner Bestätigung vergangen sind. Nur vorhanden, wenn ein PING-Frame auf der Http2Session gesendet wurde.
• streamAverageDuration <number> Die durchschnittliche Dauer (in Millisekunden) für alle Http2Stream-Instanzen.
• streamCount <number> Die Anzahl der von der Http2Session verarbeiteten Http2Stream-Instanzen.
• type <string> Entweder 'server' oder 'client', um den Typ der Http2Session zu identifizieren.

Anmerkung zu :authority und host

HTTP/2 erfordert, dass Anfragen entweder den Pseudo-Header :authority oder den Header host enthalten. Bevorzugen Sie :authority, wenn Sie eine HTTP/2-Anfrage direkt erstellen, und host, wenn Sie von HTTP/1 konvertieren (z. B. in Proxys).

Die Kompatibilitäts-API greift auf host zurück, wenn :authority nicht vorhanden ist. Siehe request.authority für weitere Informationen. Wenn Sie die Kompatibilitäts-API jedoch nicht verwenden (oder req.headers direkt verwenden), müssen Sie ein solches Rückfallverhalten selbst implementieren.