• maxDeflateDynamicTableSize Sets the maximum dynamic table sizefor deflating header fields. Default: 4Kib
• maxHeaderListPairs Sets the maximum number of header entries.Default: 128. The minimum value is 1.
• maxOutstandingPings Sets the maximum number of outstanding,unacknowledged pings. The default is 10.
• maxReservedRemoteStreams Sets the maximum number of reserved pushstreams the client will accept at any given time. Once the current number ofcurrently reserved push streams exceeds reaches this limit, new push streamssent by the server will be automatically rejected.
• maxSendHeaderBlockLength Sets the maximum allowed size for aserialized, compressed block of headers. Attempts to send headers thatexceed this limit will result in a 'frameError' event being emittedand the stream being closed and destroyed.
• paddingStrategy Identifies the strategy used for determining the amount of padding to use for HEADERS and DATA frames. Default: http2.constants.PADDING_STRATEGY_NONE. Value may be one of:
  • http2.constants.PADDING_STRATEGY_NONE - Specifies that no padding isto be applied.
  • http2.constants.PADDING_STRATEGY_MAX - Specifies that the maximumamount of padding, as determined by the internal implementation, is tobe applied.
  • http2.constants.PADDING_STRATEGY_CALLBACK - Specifies that the userprovided options.selectPadding callback is to be used to determine theamount of padding.
• peerMaxConcurrentStreams Sets the maximum number of concurrentstreams for the remote peer as if a SETTINGS frame had been received. Willbe overridden if the remote peer sets its own value formaxConcurrentStreams. Default: 100
• selectPadding When options.paddingStrategy is equal tohttp2.constants.PADDING_STRATEGY_CALLBACK, provides the callback functionused to determine the padding. See Using options.selectPadding.
• settings <Settings Object> The initial settings to send to theremote peer upon connection.
• createConnection An optional callback that receives the URLinstance passed to connect and the options object, and returns anyDuplex stream that is to be used as the connection for this session.
• ...: Any net.connect() or tls.connect() options can be provided.

Returns a HTTP/2 client Http2Session instance.

const http2 = require('http2');const client = http2.connect('https://localhost:1234');/** use the client **/client.destroy();

http2.constants#

Error Codes for RST_STREAM and GOAWAY#

The 'timeout' event is emitted when there is no activity on the Server fora given number of milliseconds set using http2server.setTimeout().

http2.getDefaultSettings()#

• Returns: <Settings Object>

Returns an object containing the default settings for an Http2Sessioninstance. This method returns a new object instance every time it is calledso instances returned may be safely modified for use.

http2.getPackedSettings(settings)#

• settings <Settings Object>
• Returns:

Returns a Buffer instance containing serialized representation of the givenHTTP/2 settings as specified in the HTTP/2 specification. This is intendedfor use with the HTTP2-Settings header field.

const http2 = require('http2');const packed = http2.getPackedSettings({ enablePush: false });console.log(packed.toString('base64'));// Prints: AAIAAAAA

http2.getUnpackedSettings(buf)#

• buf | The packed settings.
• Returns: <Settings Object>

Returns a Settings Object containing the deserialized settings from thegiven Buffer as generated by http2.getPackedSettings().

Headers Object#

Headers are represented as own-properties on JavaScript objects. The propertykeys will be serialized to lower-case. Property values should be strings (ifthey are not they will be coerced to strings) or an Array of strings (in orderto send more than one value per header field).

For example:

const headers = {  ':status': '200',  'content-type': 'text-plain',  'ABC': ['has', 'more', 'than', 'one', 'value']};stream.respond(headers);

Note: Header objects passed to callback functions will have a nullprototype. This means that normal JavaScript object methods such asObject.prototype.toString() and Object.prototype.hasOwnProperty() willnot work.

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

Settings Object#

The http2.getDefaultSettings(), http2.getPackedSettings(),http2.createServer(), http2.createSecureServer(),http2session.settings(), http2session.localSettings, andhttp2session.remoteSettings APIs either return or receive as input anobject that defines configuration settings for an Http2Session object.These objects are ordinary JavaScript objects containing the followingproperties.

• headerTableSize Specifies the maximum number of bytes used forheader compression. Default: 4,096 octets. The minimum allowedvalue is 0. The maximum allowed value is 2³²-1.
• enablePush Specifies true if HTTP/2 Push Streams are to bepermitted on the Http2Session instances.
• initialWindowSize Specifies the senders initial window sizefor stream-level flow control. Default: 65,535 bytes. The minimumallowed value is 0. The maximum allowed value is 2³²-1.
• maxFrameSize Specifies the size of the largest frame payload.Default: 16,384 bytes. The minimum allowed value is 16,384. The maximumallowed value is 2²⁴-1.
• maxConcurrentStreams Specifies the maximum number of concurrentstreams permitted on an Http2Session. There is no default value whichimplies, at least theoretically, 2³¹-1 streams may be openconcurrently at any given time in an Http2Session. The minimum value is
  0. The maximum allowed value is 2³¹-1.
• maxHeaderListSize Specifies the maximum size (uncompressed octets)of header list that will be accepted. The minimum allowed value is 0. Themaximum allowed value is 2³²-1. Default: 65535.

All additional properties on the settings object are ignored.

Using options.selectPadding#

When options.paddingStrategy is equal tohttp2.constants.PADDING_STRATEGY_CALLBACK, the HTTP/2 implementation willconsult the options.selectPadding callback function, if provided, to determinethe specific amount of padding to use per HEADERS and DATA frame.

The options.selectPadding function receives two numeric arguments,frameLen and maxFrameLen and must return a number N such thatframeLen <= N <= maxFrameLen.

const http2 = require('http2');const server = http2.createServer({  paddingStrategy: http2.constants.PADDING_STRATEGY_CALLBACK,  selectPadding(frameLen, maxFrameLen) {    return maxFrameLen;  }});

Note: The options.selectPadding function is invoked once for everyHEADERS and DATA frame. This has a definite noticeable impact onperformance.

Error Handling#

There are several types of error conditions that may arise when using thehttp2 module:

Validation Errors occur when an incorrect argument, option, or setting value ispassed in. These will always be reported by a synchronous throw.

State Errors occur when an action is attempted at an incorrect time (forinstance, attempting to send data on a stream after it has closed). These willbe reported using either a synchronous throw or via an 'error' event onthe Http2Stream, Http2Session or HTTP/2 Server objects, depending on whereand when the error occurs.

Internal Errors occur when an HTTP/2 session fails unexpectedly. These will bereported via an 'error' event on the Http2Session or HTTP/2 Server objects.

Protocol Errors occur when various HTTP/2 protocol constraints are violated.These will be reported using either a synchronous throw or via an 'error'event on the Http2Stream, Http2Session or HTTP/2 Server objects, dependingon where and when the error occurs.

Invalid character handling in header names and values#

The HTTP/2 implementation applies stricter handling of invalid characters inHTTP header names and values than the HTTP/1 implementation.

Header field names are case-insensitive and are transmitted over the wirestrictly as lower-case strings. The API provided by Node.js allows headernames to be set as mixed-case strings (e.g. Content-Type) but will convertthose to lower-case (e.g. content-type) upon transmission.

Header field-names must only contain one or more of the following ASCIIcharacters: a-z, A-Z, 0-9, !, #, $, %, &, ', *, +,-, ., ^, _, ` (backtick), |, and ~.

Using invalid characters within an HTTP header field name will cause thestream to be closed with a protocol error being reported.

Header field values are handled with more leniency but should not containnew-line or carriage return characters and should be limited to US-ASCIIcharacters, per the requirements of the HTTP specification.

Push streams on the client#

To receive pushed streams on the client, set a listener for the 'stream'event on the ClientHttp2Session:

const http2 = require('http2');const client = http2.connect('http://localhost');client.on('stream', (pushedStream, requestHeaders) => {  pushedStream.on('push', (responseHeaders) => {    // process response headers  });  pushedStream.on('data', (chunk) => { /* handle pushed data */ });});const req = client.request({ ':path': '/' });

Supporting the CONNECT method#

The CONNECT method is used to allow an HTTP/2 server to be used as a proxyfor TCP/IP connections.

A simple TCP Server:

const net = require('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);

An HTTP/2 CONNECT proxy:

const http2 = require('http2');const net = require('net');const { URL } = require('url');const proxy = http2.createServer();proxy.on('stream', (stream, headers) => {  if (headers[':method'] !== 'CONNECT') {    // Only accept CONNECT requests    stream.rstWithRefused();    return;  }  const auth = new URL(`tcp://${headers[':authority']}`);  // It's a very good idea to verify that hostname and port are  // things this proxy should be connecting to.  const socket = net.connect(auth.port, auth.hostname, () => {    stream.respond();    socket.pipe(stream);    stream.pipe(socket);  });  socket.on('error', (error) => {    stream.rstStream(http2.constants.NGHTTP2_CONNECT_ERROR);  });});proxy.listen(8001);

An HTTP/2 CONNECT client:

const http2 = require('http2');const client = http2.connect('http://localhost:8001');// Must not specify the ':path' and ':scheme' headers// for CONNECT requests or an error will be thrown.const req = client.request({  ':method': 'CONNECT',  ':authority': `localhost:${port}`});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(`The server says: ${data}`);  client.destroy();});req.end('Jane');

Compatibility API#

The Compatibility API has the goal of providing a similar developer experienceof HTTP/1 when using HTTP/2, making it possible to develop applicationsthat supports both HTTP/1 and HTTP/2. This API targets only thepublic API of the HTTP/1, however many modules uses internalmethods or state, and those are not supported as it is a completelydifferent implementation.

The following example creates an HTTP/2 server using the compatibilityAPI:

const http2 = require('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' });  res.end('ok');});

In order to create a mixed HTTPS and HTTP/2 server, refer to theALPN negotiation section.Upgrading from non-tls HTTP/1 servers is not supported.

The HTTP2 compatibility API is composed of Http2ServerRequest andHttp2ServerResponse. They aim at API compatibility with HTTP/1, butthey do not hide the differences between the protocols. As an example,the status message for HTTP codes is ignored.

ALPN negotiation#

ALPN negotiation allows to support both HTTPS and HTTP/2 overthe same socket. The req and res objects can be either HTTP/1 orHTTP/2, and an application must restrict itself to the public API ofHTTP/1, and detect if it is possible to use the more advancedfeatures of HTTP/2.

The following example creates a server that supports both protocols:

const { createSecureServer } = require('http2');const { readFileSync } = require('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) {  // detects if it is a HTTPS request or HTTP/2  const { socket: { alpnProtocol } } = req.httpVersion === '2.0' ?    req.stream.session : req;  res.writeHead(200, { 'content-type': 'application/json' });  res.end(JSON.stringify({    alpnProtocol,    httpVersion: req.httpVersion  }));}

The 'request' event works identically on both HTTPS andHTTP/2.

Class: http2.Http2ServerRequest#

A Http2ServerRequest object is created by http2.Server orhttp2.SecureServer and passed as the first argument to the'request' event. It may be used to access a request status, headers anddata.

It implements the Readable Stream interface, as well as thefollowing additional events, methods, and properties.

Event: 'aborted'#

The 'aborted' event is emitted whenever a Http2ServerRequest instance isabnormally aborted in mid-communication.

Note: The 'aborted' event will only be emitted if theHttp2ServerRequest writable side has not been ended.

Event: 'close'#

Indicates that the underlying Http2Stream was closed.Just like 'end', this event occurs only once per response.

request.destroy([error])#

• error

Calls destroy() on the Http2Stream that receivedthe Http2ServerRequest. If error is provided, an 'error' eventis emitted and error is passed as an argument to any listeners on the event.

It does nothing if the stream was already destroyed.

request.headers#