http2

The request.aborted property will be true if the request has been aborted.

The request authority pseudo header field. Because HTTP/2 allows requests to set either :authority or host, this value is derived from req.headers[':authority'] if present. Otherwise, it is derived from req.headers['host'].

The request.complete property will be true if the request has been completed, aborted, or destroyed.

See request.socket.

The request/response headers object.

Key-value pairs of header names and values. Header names are lower-cased.

// Prints something like:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*' }
console.log(request.headers);

See HTTP/2 Headers Object.

In HTTP/2, the request path, host name, protocol, and method are represented as special headers prefixed with the : character (e.g. ':path'). These special headers will be included in the request.headers object. Care must be taken not to inadvertently modify these special headers or errors may occur. For instance, removing all headers from the request will cause errors to occur:

removeAllHeaders(request.headers);
assert(request.url);   // Fails because the :path header has been removed

In case of server request, the HTTP version sent by the client. In the case of client response, the HTTP version of the connected-to server. Returns '2.0'.

Also message.httpVersionMajor is the first integer and message.httpVersionMinor is the second.

The request method as a string. Read-only. Examples: 'GET', 'DELETE'.

The raw request/response headers list exactly as they were received.

The keys and values are in the same list. It is not a list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values.

Header names are not lowercased, and duplicates are not merged.

// Prints something like:
//
// [ '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);

The raw request/response trailer keys and values exactly as they were received. Only populated at the 'end' event.

The request scheme pseudo header field indicating the scheme portion of the target URL.

Returns a Proxy object that acts as a net.Socket (or tls.TLSSocket) but applies getters, setters, and methods based on HTTP/2 logic.

destroyed, readable, and writable properties will be retrieved from and set on request.stream.

destroy, emit, end, on and once methods will be called on request.stream.

setTimeout method will be called on request.stream.session.

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

All other interactions will be routed directly to the socket. With TLS support, use request.socket.getPeerCertificate() to obtain the client's authentication details.

The Http2Stream object backing the request.

The request/response trailers object. Only populated at the 'end' event.

Request URL string. This contains only the URL that is present in the actual HTTP request. If the request is:

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

Then request.url will be:

'/status?name=ryan'

To parse the url into its parts, new URL() can be used:

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

Sets the Http2Stream's timeout value to msecs. If a callback is provided, then it is added as a listener on the 'timeout' event on the response object.

If no 'timeout' listener is added to the request, the response, or the server, then Http2Streams are destroyed when they time out. If a handler is assigned to the request, the response, or the server's 'timeout'events, timed out sockets must be handled explicitly.

See response.socket.

Boolean value that indicates whether the response has completed. Starts as false. After response.end() executes, the value will be true.

True if headers were sent, false otherwise (read-only).

A reference to the original HTTP2 request object.

When true, the Date header will be automatically generated and sent in the response if it is not already present in the headers. Defaults to true.

This should only be disabled for testing; HTTP requires the Date header in responses.

Returns a Proxy object that acts as a net.Socket (or tls.TLSSocket) but applies getters, setters, and methods based on HTTP/2 logic.

destroyed, readable, and writable properties will be retrieved from and set on response.stream.

destroy, emit, end, on and once methods will be called on response.stream.

setTimeout method will be called on response.stream.session.

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

All other interactions will be routed directly to the socket.

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

When using implicit headers (not calling response.writeHead() explicitly), this property controls the status code that will be sent to the client when the headers get flushed.

response.statusCode = 404;

After response header was sent to the client, this property indicates the status code which was sent out.

Status message is not supported by HTTP/2 (RFC 7540 8.1.2.4). It returns an empty string.

The Http2Stream object backing the response.

This method adds HTTP trailing headers (a header but at the end of the message) to the response.

Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

Append a single header value to the header object.

If the value is an array, this is equivalent to calling this method multiple times.

If there were no previous values for the header, this is equivalent to calling setHeader.

Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

// Returns headers including "set-cookie: a" and "set-cookie: b"
const server = http2.createServer((req, res) => {
  res.setHeader('set-cookie', 'a');
  res.appendHeader('set-cookie', 'b');
  res.writeHead(200);
  res.end('ok');
});

Call http2stream.pushStream() with the given headers, and wrap the given Http2Stream on a newly created Http2ServerResponse as the callback parameter if successful. When Http2ServerRequest is closed, the callback is called with an error ERR_HTTP2_INVALID_STREAM.

This method signals to the server that all of the response headers and body have been sent; that server should consider this message complete. The method, response.end(), MUST be called on each response.

If data is specified, it is equivalent to calling response.write(data, encoding) followed by response.end(callback).

If callback is specified, it will be called when the response stream is finished.

Reads out a header that has already been queued but not sent to the client. The name is case-insensitive.

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

Returns an array containing the unique names of the current outgoing headers. All header names are lowercase.

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

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

Returns a shallow copy of the current outgoing headers. Since a shallow copy is used, array values may be mutated without additional calls to various header-related http module methods. The keys of the returned object are the header names and the values are the respective header values. All header names are lowercase.

The object returned by the response.getHeaders() method does not prototypically inherit from the JavaScript Object. This means that typical Object methods such as obj.toString(), obj.hasOwnProperty(), and others are not defined and will not work.

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

Returns true if the header identified by name is currently set in the outgoing headers. The header name matching is case-insensitive.

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

Removes a header that has been queued for implicit sending.

response.removeHeader('Content-Encoding');

Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings here to send multiple headers with the same name.

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

or

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

Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

When headers have been set with response.setHeader(), they will be merged with any headers passed to response.writeHead(), with the headers passed to response.writeHead() given precedence.

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

Sets the Http2Stream's timeout value to msecs. If a callback is provided, then it is added as a listener on the 'timeout' event on the response object.

If no 'timeout' listener is added to the request, the response, or the server, then Http2Stream s are destroyed when they time out. If a handler is assigned to the request, the response, or the server's 'timeout' events, timed out sockets must be handled explicitly.

If this method is called and response.writeHead() has not been called, it will switch to implicit header mode and flush the implicit headers.

This sends a chunk of the response body. This method may be called multiple times to provide successive parts of the body.

In the node:http module, the response body is omitted when the request is a HEAD request. Similarly, the 204 and 304 responses must not include a message body.

chunk can be a string or a buffer. If chunk is a string, the second parameter specifies how to encode it into a byte stream. By default the encoding is 'utf8'. callback will be called when this chunk of data is flushed.

This is the raw HTTP body and has nothing to do with higher-level multi-part body encodings that may be used.

The first time response.write() is called, it will send the buffered header information and the first chunk of the body to the client. The second time response.write() is called, Node.js assumes data will be streamed, and sends the new data separately. That is, the response is buffered up to the first chunk of the body.

Returns true if the entire data was flushed successfully to the kernel buffer. Returns false if all or part of the data was queued in user memory.'drain' will be emitted when the buffer is free again.

Sends a status 100 Continue to the client, indicating that the request body should be sent. See the 'checkContinue' event on Http2Server and Http2SecureServer.

Sends a status 103 Early Hints to the client with a Link header, indicating that the user agent can preload/preconnect the linked resources. The hints is an object containing the values of headers to be sent with early hints message.

Example

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

Sends a response header to the request. The status code is a 3-digit HTTP status code, like 404. The last argument, headers, are the response headers.

Returns a reference to the Http2ServerResponse, so that calls can be chained.

For compatibility with HTTP/1, a human-readable statusMessage may be passed as the second argument. However, because the statusMessage has no meaning within HTTP/2, the argument will have no effect and a process warning will be emitted.

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

Content-Length is given in bytes not characters. TheBuffer.byteLength() API may be used to determine the number of bytes in a given encoding. On outbound messages, Node.js does not check if Content-Length and the length of the body being transmitted are equal or not. However, when receiving messages, Node.js will automatically reject messages when the Content-Length does not match the actual payload size.

This method may be called at most one time on a message before response.end() is called.

If response.write() or response.end() are called before calling this, the implicit/mutable headers will be calculated and call this function.

When headers have been set with response.setHeader(), they will be merged with any headers passed to response.writeHead(), with the headers passed to response.writeHead() given precedence.

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

Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

For HTTP/2 Client Http2Session instances only, the http2session.request() creates and returns an Http2Stream instance that can be used to send an HTTP/2 request to the connected server.

When a ClientHttp2Session is first created, the socket may not yet be connected. if clienthttp2session.request() is called during this time, the actual request will be deferred until the socket is ready to go. If the session is closed before the actual request be executed, an ERR_HTTP2_GOAWAY_SESSION is thrown.

This method is only available if http2session.type is equal to http2.constants.NGHTTP2_SESSION_CLIENT.

import http2 from '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', () => { // ..  });
});

When the options.waitForTrailers option is set, the 'wantTrailers' event is emitted immediately after queuing the last chunk of payload data to be sent. The http2stream.sendTrailers() method can then be called to send trailing headers to the peer.

When options.waitForTrailers is set, the Http2Stream will not automatically close when the final DATA frame is transmitted. User code must call eitherhttp2stream.sendTrailers() or http2stream.close() to close theHttp2Stream.

When options.signal is set with an AbortSignal and then abort on the corresponding AbortController is called, the request will emit an 'error'event with an AbortError error.

The :method and :path pseudo-headers are not specified within headers, they respectively default to:

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