Node.js v24.21.0 documentation

Http2Session and sockets#

Every Http2Session instance is associated with exactly one net.Socket or tls.TLSSocket when it is created. When either the Socket or the Http2Session are destroyed, both will be destroyed.

Because of the specific serialization and processing requirements imposed by the HTTP/2 protocol, it is not recommended for user code to read data from or write data to a Socket instance bound to a Http2Session. Doing so can put the HTTP/2 session into an indeterminate state causing the session and the socket to become unusable.

Once a Socket has been bound to an Http2Session, user code should rely solely on the API of the Http2Session.

Event: 'close'#

The 'close' event is emitted once the Http2Session has been destroyed. Its listener does not expect any arguments.

Event: 'connect'#

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

The 'connect' event is emitted once the Http2Session has been successfully connected to the remote peer and communication may begin.

User code will typically not listen for this event directly.

Event: 'error'#

• error <Error>

The 'error' event is emitted when an error occurs during the processing of an Http2Session.

Event: 'frameError'#

• type <integer> The frame type.
• code <integer> The error code.
• id <integer> The stream id (or 0 if the frame isn't associated with a stream).

The 'frameError' event is emitted when an error occurs while attempting to send a frame on the session. If the frame that could not be sent is associated with a specific Http2Stream, an attempt to emit a 'frameError' event on the Http2Stream is made.

If the 'frameError' event is associated with a stream, the stream will be closed and destroyed immediately following the 'frameError' event. If the event is not associated with a stream, the Http2Session will be shut down immediately following the 'frameError' event.

Event: 'goaway'#

• errorCode <number> The HTTP/2 error code specified in the GOAWAY frame.
• lastStreamID <number> The ID of the last stream the remote peer successfully processed (or 0 if no ID is specified).
• opaqueData <Buffer> If additional opaque data was included in the GOAWAY frame, a Buffer instance will be passed containing that data.

The 'goaway' event is emitted when a GOAWAY frame is received.

The Http2Session instance will be shut down automatically when the 'goaway' event is emitted.

Event: 'localSettings'#

• settings <HTTP/2 Settings Object> A copy of the SETTINGS frame received.

The 'localSettings' event is emitted when an acknowledgment SETTINGS frame has been received.

When using http2session.settings() to submit new settings, the modified settings do not take effect until the 'localSettings' event is emitted.

session.settings({ enablePush: false });

session.on('localSettings', (settings) => {
  /* Use the new settings */
}); copy

Event: 'ping'#

• payload <Buffer> The PING frame 8-byte payload

The 'ping' event is emitted whenever a PING frame is received from the connected peer.

Event: 'remoteSettings'#

• settings <HTTP/2 Settings Object> A copy of the SETTINGS frame received.

The 'remoteSettings' event is emitted when a new SETTINGS frame is received from the connected peer.

session.on('remoteSettings', (settings) => {
  /* Use the new settings */
}); copy

Event: 'stream'#

• stream <Http2Stream> A reference to the stream
• headers <HTTP/2 Headers Object> An object describing the headers
• flags <number> The associated numeric flags
• rawHeaders <HTTP/2 Raw Headers> An array containing the raw headers

The 'stream' event is emitted when a new Http2Stream is created.

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

On the server side, user code will typically not listen for this event directly, and would instead register a handler for the 'stream' event emitted by the net.Server or tls.Server instances returned by http2.createServer() and http2.createSecureServer(), respectively, as in the example below:

import { createServer } from 'node:http2';

// Create an unencrypted HTTP/2 server
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);const http2 = require('node:http2');

// Create an unencrypted HTTP/2 server
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);copy

Even though HTTP/2 streams and network sockets are not in a 1:1 correspondence, a network error will destroy each individual stream and must be handled on the stream level, as shown above.

Event: 'timeout'#

After the http2session.setTimeout() method is used to set the timeout period for this Http2Session, the 'timeout' event is emitted if there is no activity on the Http2Session after the configured number of milliseconds. Its listener does not expect any arguments.

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

http2session.alpnProtocol#

• Type: <string> | <undefined>

Value will be undefined if the Http2Session is not yet connected to a socket, h2c if the Http2Session is not connected to a TLSSocket, or will return the value of the connected TLSSocket's own alpnProtocol property.

http2session.close([callback])#

• callback <Function>

Gracefully closes the Http2Session, allowing any existing streams to complete on their own and preventing new Http2Stream instances from being created. Once closed, http2session.destroy() might be called if there are no open Http2Stream instances.

If specified, the callback function is registered as a handler for the 'close' event.

http2session.closed#

• Type: <boolean>

Will be true if this Http2Session instance has been closed, otherwise false.

http2session.connecting#

• Type: <boolean>

Will be true if this Http2Session instance is still connecting, will be set to false before emitting connect event and/or calling the http2.connect callback.

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

• error <Error> An Error object if the Http2Session is being destroyed due to an error.
• code <number> The HTTP/2 error code to send in the final GOAWAY frame. If unspecified, and error is not undefined, the default is INTERNAL_ERROR, otherwise defaults to NO_ERROR.

Immediately terminates the Http2Session and the associated net.Socket or tls.TLSSocket.

Once destroyed, the Http2Session will emit the 'close' event. If error is not undefined, an 'error' event will be emitted immediately before the 'close' event.

If there are any remaining open Http2Streams associated with the Http2Session, those will also be destroyed.

http2session.destroyed#

• Type: <boolean>

Will be true if this Http2Session instance has been destroyed and must no longer be used, otherwise false.

http2session.encrypted#

• Type: <boolean> | <undefined>

Value is undefined if the Http2Session session socket has not yet been connected, true if the Http2Session is connected with a TLSSocket, and false if the Http2Session is connected to any other kind of socket or stream.

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

• code <number> An HTTP/2 error code
• lastStreamID <number> The numeric ID of the last processed Http2Stream
• opaqueData <Buffer> | <TypedArray> | <DataView> A TypedArray or DataView instance containing additional data to be carried within the GOAWAY frame.

Transmits a GOAWAY frame to the connected peer without shutting down the Http2Session.

http2session.localSettings#

• Type: <HTTP/2 Settings Object>

A prototype-less object describing the current local settings of this Http2Session. The local settings are local to this Http2Session instance.

http2session.originSet#

• Type: <string[]> | <undefined>

If the Http2Session is connected to a TLSSocket, the originSet property will return an Array of origins for which the Http2Session may be considered authoritative.

The originSet property is only available when using a secure TLS connection.

http2session.pendingSettingsAck#

• Type: <boolean>

Indicates whether the Http2Session is currently waiting for acknowledgment of a sent SETTINGS frame. Will be true after calling the http2session.settings() method. Will be false once all sent SETTINGS frames have been acknowledged.

http2session.ping([payload, ]callback)#

• payload <Buffer> | <TypedArray> | <DataView> Optional ping payload.
• callback <Function>
• Returns: <boolean>

Sends a PING frame to the connected HTTP/2 peer. A callback function must be provided. The method will return true if the PING was sent, false otherwise.

The maximum number of outstanding (unacknowledged) pings is determined by the maxOutstandingPings configuration option. The default maximum is 10.

If provided, the payload must be a Buffer, TypedArray, or DataView containing 8 bytes of data that will be transmitted with the PING and returned with the ping acknowledgment.

The callback will be invoked with three arguments: an error argument that will be null if the PING was successfully acknowledged, a duration argument that reports the number of milliseconds elapsed since the ping was sent and the acknowledgment was received, and a Buffer containing the 8-byte PING payload.

session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`Ping acknowledged in ${duration} milliseconds`);
    console.log(`With payload '${payload.toString()}'`);
  }
}); copy

If the payload argument is not specified, the default payload will be the 64-bit timestamp (little endian) marking the start of the PING duration.

http2session.ref()#

Calls ref() on this Http2Session instance's underlying net.Socket.

http2session.remoteSettings#

• Type: <HTTP/2 Settings Object>

A prototype-less object describing the current remote settings of this Http2Session. The remote settings are set by the connected HTTP/2 peer.

http2session.setLocalWindowSize(windowSize)#

• windowSize <number>

Sets the local endpoint's window size. The windowSize is the total window size to set, not the delta.

import { createServer } from 'node:http2';

const server = createServer();
const expectedWindowSize = 2 ** 20;
server.on('session', (session) => {

  // Set local window size to be 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});const http2 = require('node:http2');

const server = http2.createServer();
const expectedWindowSize = 2 ** 20;
server.on('session', (session) => {

  // Set local window size to be 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});copy

For http2 clients the proper event is either 'connect' or 'remoteSettings'.

http2session.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>

Used to set a callback function that is called when there is no activity on the Http2Session after msecs milliseconds. The given callback is registered as a listener on the 'timeout' event.

http2session.socket#

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

Returns a Proxy object that acts as a net.Socket (or tls.TLSSocket) but limits available methods to ones safe to use with HTTP/2.

emit, end, pause, read, resume, and write will throw an error with code ERR_HTTP2_NO_SOCKET_MANIPULATION. See Http2Session and Sockets for more information.

destroy, setTimeout, ref, and unref methods will be called on this Http2Session.

All other interactions will be routed directly to the socket.

http2session.state#

Provides miscellaneous information about the current state of the Http2Session.

• Type: <Object>
  • effectiveLocalWindowSize <number> The current local (receive) flow control window size for the Http2Session.
  • effectiveRecvDataLength <number> The current number of bytes that have been received since the last flow control WINDOW_UPDATE.
  • nextStreamID <number> The numeric identifier to be used the next time a new Http2Stream is created by this Http2Session.
  • localWindowSize <number> The number of bytes that the remote peer can send without receiving a WINDOW_UPDATE.
  • lastProcStreamID <number> The numeric id of the Http2Stream for which a HEADERS or DATA frame was most recently received.
  • remoteWindowSize <number> The number of bytes that this Http2Session may send without receiving a WINDOW_UPDATE.
  • outboundQueueSize <number> The number of frames currently within the outbound queue for this Http2Session.
  • deflateDynamicTableSize <number> The current size in bytes of the outbound header compression state table.
  • inflateDynamicTableSize <number> The current size in bytes of the inbound header compression state table.

An object describing the current status of this Http2Session.

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

• settings <HTTP/2 Settings Object>
• callback <Function> Callback that is called once the session is connected or right away if the session is already connected.
  • err <Error> | <null>
  • settings <HTTP/2 Settings Object> The updated settings object.
  • duration <integer>

Updates the current local settings for this Http2Session and sends a new SETTINGS frame to the connected HTTP/2 peer.

Once called, the http2session.pendingSettingsAck property will be true while the session is waiting for the remote peer to acknowledge the new settings.

The new settings will not become effective until the SETTINGS acknowledgment is received and the 'localSettings' event is emitted. It is possible to send multiple SETTINGS frames while acknowledgment is still pending.

http2session.type#

• Type: <number>

The http2session.type will be equal to http2.constants.NGHTTP2_SESSION_SERVER if this Http2Session instance is a server, and http2.constants.NGHTTP2_SESSION_CLIENT if the instance is a client.

http2session.unref()#

Calls unref() on this Http2Session instance's underlying net.Socket.

serverhttp2session.altsvc(alt, originOrStream)#

• alt <string> A description of the alternative service configuration as defined by RFC 7838.
• originOrStream <number> | <string> | <URL> | <Object> Either a URL string specifying the origin (or an Object with an origin property) or the numeric identifier of an active Http2Stream as given by the http2stream.id property.

Submits an ALTSVC frame (as defined by RFC 7838) to the connected client.

import { createServer } from 'node:http2';

const server = createServer();
server.on('session', (session) => {
  // Set altsvc for origin https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80');
});

server.on('stream', (stream) => {
  // Set altsvc for a specific stream
  stream.session.altsvc('h2=":8000"', stream.id);
});const http2 = require('node:http2');

const server = http2.createServer();
server.on('session', (session) => {
  // Set altsvc for origin https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80');
});

server.on('stream', (stream) => {
  // Set altsvc for a specific stream
  stream.session.altsvc('h2=":8000"', stream.id);
});copy

Sending an ALTSVC frame with a specific stream ID indicates that the alternate service is associated with the origin of the given Http2Stream.

The alt and origin string must contain only ASCII bytes and are strictly interpreted as a sequence of ASCII bytes. The special value 'clear' may be passed to clear any previously set alternative service for a given domain.

When a string is passed for the originOrStream argument, it will be parsed as a URL and the origin will be derived. For instance, the origin for the HTTP URL 'https://example.org/foo/bar' is the ASCII string 'https://example.org'. An error will be thrown if either the given string cannot be parsed as a URL or if a valid origin cannot be derived.

A URL object, or any object with an origin property, may be passed as originOrStream, in which case the value of the origin property will be used. The value of the origin property must be a properly serialized ASCII origin.

Specifying alternative services#

The format of the alt parameter is strictly defined by RFC 7838 as an ASCII string containing a comma-delimited list of "alternative" protocols associated with a specific host and port.

For example, the value 'h2="example.org:81"' indicates that the HTTP/2 protocol is available on the host 'example.org' on TCP/IP port 81. The host and port must be contained within the quote (") characters.

Multiple alternatives may be specified, for instance: 'h2="example.org:81", h2=":82"'.

The protocol identifier ('h2' in the examples) may be any valid ALPN Protocol ID.

The syntax of these values is not validated by the Node.js implementation and are passed through as provided by the user or received from the peer.

serverhttp2session.origin(...origins)#

• origins <string> | <URL> | <Object> One or more URL Strings passed as separate arguments.

Submits an ORIGIN frame (as defined by RFC 8336) to the connected client to advertise the set of origins for which the server is capable of providing authoritative responses.

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

When a string is passed as an origin, it will be parsed as a URL and the origin will be derived. For instance, the origin for the HTTP URL 'https://example.org/foo/bar' is the ASCII string 'https://example.org'. An error will be thrown if either the given string cannot be parsed as a URL or if a valid origin cannot be derived.

A URL object, or any object with an origin property, may be passed as an origin, in which case the value of the origin property will be used. The value of the origin property must be a properly serialized ASCII origin.

Alternatively, the origins option may be used when creating a new HTTP/2 server using the http2.createSecureServer() method:

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'