HTTP/2

Модуль node:http2 предоставляет реализацию протокола HTTP/2. Доступ к нему можно получить следующим образом:

const http2 = require('node:http2');
jscopy

Определение отсутствия поддержки криптографии

Node.js может быть собран без поддержки модуля node:crypto. В таких случаях попытка выполнить import из node:http2 или вызов require('node:http2') приведет к ошибке.

При использовании CommonJS возникшую ошибку можно перехватить с помощью try/catch:

let http2;
try {
  http2 = require('node:http2');
} catch (err) {
  console.error('http2 support is disabled!');
}
cjscopy

При использовании лексического ключевого слова ESM import ошибку можно перехватить, только если обработчик для process.on('uncaughtException') зарегистрирован до любой попытки загрузить модуль (например, с помощью предварительно загружаемого модуля).

При использовании ESM, если код может выполняться в сборке Node.js без поддержки криптографии, рассмотрите возможность использовать функцию import() вместо лексического ключевого слова import:

let http2;
try {
  http2 = await import('node:http2');
} catch (err) {
  console.error('http2 support is disabled!');
}
mjscopy

Основной API

Основной API предоставляет низкоуровневый интерфейс, предназначенный специально для поддержки возможностей протокола HTTP/2. Он не предназначен для совместимости с существующим API модуля HTTP/1. Однако API совместимости предназначен именно для этого.

Основной API http2 гораздо более симметричен для клиента и сервера, чем API http. Например, большинство событий, таких как 'error', 'connect' и 'stream', могут генерироваться как клиентским, так и серверным кодом.

Пример для сервера

В следующем примере показан простой HTTP/2-сервер, использующий основной API. Поскольку браузеры с поддержкой незашифрованного HTTP/2 неизвестны, для взаимодействия с клиентами-браузерами необходимо использовать http2.createSecureServer().

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

server.listen(8443);

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

server.listen(8443);

Чтобы создать сертификат и ключ для этого примера, выполните:

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

Пример для клиента

В следующем примере показан клиент HTTP/2:

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

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

Класс: Http2Session

• Наследует: <EventEmitter>

Экземпляры класса http2.Http2Session представляют активный сеанс связи между клиентом и сервером HTTP/2. Эти экземпляры не предназначены для непосредственного создания пользовательским кодом.

Поведение каждого экземпляра Http2Session будет несколько различаться в зависимости от того, работает он в качестве сервера или клиента. Свойство http2session.type позволяет определить, в каком режиме работает Http2Session. На стороне сервера пользовательскому коду редко приходится работать непосредственно с объектом Http2Session; обычно действия выполняются через взаимодействие с объектами Http2Server или Http2Stream.

Пользовательский код не создает экземпляры Http2Session напрямую. Экземпляры Http2Session на стороне сервера создаются экземпляром Http2Server при получении нового соединения HTTP/2. Экземпляры Http2Session на стороне клиента создаются с помощью метода http2.connect().

Http2Session и сокеты

Каждый экземпляр Http2Session при создании связывается ровно с одним объектом net.Socket или tls.TLSSocket. При уничтожении Socket или Http2Session уничтожаются оба объекта.

Из-за особых требований протокола HTTP/2 к сериализации и обработке данных не рекомендуется, чтобы пользовательский код читал данные из экземпляра Socket, связанного с Http2Session, или записывал в него данные. Это может привести сеанс HTTP/2 в неопределенное состояние, из-за чего сеанс и сокет станут непригодны для использования.

После связывания Socket с Http2Session пользовательскому коду следует взаимодействовать исключительно через API объекта Http2Session.

Событие: 'close'

Событие 'close' генерируется после уничтожения Http2Session. Обработчик события не ожидает аргументов.

Событие: 'connect'

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

Событие 'connect' генерируется после успешного подключения Http2Session к удаленному узлу, когда становится возможным начать обмен данными.

Пользовательский код обычно не обрабатывает это событие напрямую.

Событие: 'error'

• error <Error>

Событие 'error' генерируется при возникновении ошибки во время обработки Http2Session.

Событие: 'frameError'

• type <integer> Тип кадра.
• code <integer> Код ошибки.
• id <integer> Идентификатор потока (или 0, если кадр не связан с потоком).

Событие 'frameError' генерируется при возникновении ошибки во время попытки отправить кадр в рамках сеанса. Если кадр, который не удалось отправить, связан с конкретным Http2Stream, предпринимается попытка сгенерировать событие 'frameError' для объекта Http2Stream.

Если событие 'frameError' связано с потоком, этот поток будет закрыт и уничтожен сразу после события 'frameError'. Если событие не связано с потоком, объект Http2Session будет немедленно отключен после события 'frameError'.

Событие: 'goaway'

• errorCode <number> Код ошибки HTTP/2, указанный в кадре GOAWAY.
• lastStreamID <number> Идентификатор последнего потока, успешно обработанного удаленным узлом (или 0, если идентификатор не указан).
• opaqueData <Buffer> Если в кадр GOAWAY были включены дополнительные непрозрачные данные, будет передан экземпляр Buffer, содержащий эти данные.

Событие 'goaway' генерируется при получении кадра GOAWAY.

Экземпляр Http2Session автоматически отключается при генерации события 'goaway'.

Событие: 'localSettings'

• settings <HTTP/2 Settings Object> Копия полученного кадра SETTINGS.

Событие 'localSettings' генерируется при получении кадра SETTINGS с подтверждением.

При использовании http2session.settings() для передачи новых настроек измененные настройки вступают в силу только после генерации события 'localSettings'.

session.settings({ enablePush: false });

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

Событие: 'ping'

• payload <Buffer> 8-байтовая полезная нагрузка кадра PING

Событие 'ping' генерируется каждый раз при получении кадра PING от подключенного узла.

Событие: 'remoteSettings'

• settings <HTTP/2 Settings Object> Копия полученного кадра SETTINGS.

Событие 'remoteSettings' генерируется при получении нового кадра SETTINGS от подключенного узла.

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

Событие: 'stream'

• stream <Http2Stream> Ссылка на поток
• headers <HTTP/2 Headers Object> Объект с описанием заголовков
• flags <number> Связанные числовые флаги
• rawHeaders {Необработанные заголовки HTTP/2} Массив, содержащий необработанные заголовки

Событие 'stream' генерируется при создании нового Http2Stream.

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

На стороне сервера пользовательский код обычно не обрабатывает это событие напрямую. Вместо этого он регистрирует обработчик события 'stream', генерируемого экземплярами net.Server или tls.Server, возвращаемыми соответственно методами http2.createServer() и http2.createSecureServer(), как показано в примере ниже:

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

Хотя потоки HTTP/2 и сетевые сокеты не соответствуют друг другу один к одному, сетевая ошибка уничтожит каждый отдельный поток, поэтому ее необходимо обрабатывать на уровне потока, как показано выше.

Событие: 'timeout'

После вызова метода http2session.setTimeout() для установки периода ожидания для этого Http2Session событие 'timeout' генерируется, если в течение заданного количества миллисекунд в Http2Session не было активности. Обработчик события не ожидает аргументов.

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

http2session.alpnProtocol

• Тип: <string> | <undefined>

Значение будет равно undefined, если Http2Session еще не подключен к сокету, и h2c, если Http2Session не подключен к TLSSocket. В противном случае будет возвращено значение свойства alpnProtocol самого подключенного TLSSocket.

http2session.close([callback])

• callback <Function>

Корректно закрывает Http2Session, позволяя завершить работу всех существующих потоков и предотвращая создание новых экземпляров Http2Stream. После закрытия может быть вызван http2session.destroy(), если открытых экземпляров Http2Stream нет.

Если указана функция callback, она регистрируется в качестве обработчика события 'close'.

http2session.closed

• Тип: <boolean>

Равно true, если этот экземпляр Http2Session был закрыт, и false в противном случае.

http2session.connecting

• Тип: <boolean>

Равно true, если этот экземпляр Http2Session все еще подключается. Значение будет установлено в false перед генерацией события connect и/или вызовом обратного вызова http2.connect.

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

• error <Error> Объект Error, если Http2Session уничтожается из-за ошибки.
• code <number> Код ошибки HTTP/2 для отправки в заключительном кадре GOAWAY. Если значение не указано, а error не равно undefined, по умолчанию используется INTERNAL_ERROR; в противном случае используется NO_ERROR.

Немедленно завершает Http2Session и связанный с ним объект net.Socket или tls.TLSSocket.

После уничтожения Http2Session сгенерирует событие 'close'. Если error не равно undefined, событие 'error' будет сгенерировано непосредственно перед событием 'close'.

Все оставшиеся открытые экземпляры Http2Streams, связанные с Http2Session, также будут уничтожены.

http2session.destroyed

• Тип: <boolean>

Равно true, если этот экземпляр Http2Session был уничтожен и его больше нельзя использовать, и false в противном случае.

http2session.encrypted

• Тип: <boolean> | <undefined>

Значение равно undefined, если сокет сеанса Http2Session еще не подключен, true, если Http2Session подключен к TLSSocket, и false, если Http2Session подключен к сокету или потоку любого другого типа.

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

• code <number> Код ошибки HTTP/2
• lastStreamID <number> Числовой идентификатор последнего обработанного Http2Stream
• opaqueData <Buffer> | <TypedArray> | <DataView> Экземпляр TypedArray или DataView, содержащий дополнительные данные для передачи в кадре GOAWAY.

Передает подключенному узлу кадр GOAWAY, не отключая Http2Session.

http2session.localSettings

• Тип: <HTTP/2 Settings Object>

Объект без прототипа, описывающий текущие локальные настройки этого Http2Session. Локальные настройки относятся к этому экземпляру Http2Session.

http2session.originSet

• Тип: <string[]> | <undefined>

Если Http2Session подключен к TLSSocket, свойство originSet вернет Array источников, для которых Http2Session может считаться авторитетным.

Свойство originSet доступно только при использовании защищенного TLS-соединения.

http2session.pendingSettingsAck

• Тип: <boolean>

Показывает, ожидает ли Http2Session в данный момент подтверждения отправленного кадра SETTINGS. После вызова метода http2session.settings() значение будет true. Оно станет false после подтверждения всех отправленных кадров SETTINGS.

http2session.ping([payload, ]callback)

• payload <Buffer> | <TypedArray> | <DataView> Необязательная полезная нагрузка ping.
• callback <Function>
• Возвращает: <boolean>

Отправляет кадр PING подключенному узлу HTTP/2. Необходимо указать функцию callback. Метод вернет true, если PING был отправлен, и false в противном случае.

Максимальное количество ожидающих подтверждения ping определяется параметром конфигурации maxOutstandingPings. По умолчанию это значение равно 10.

Если указан, payload должен быть объектом Buffer, TypedArray или DataView, содержащим 8 байт данных, которые будут переданы вместе с PING и возвращены с подтверждением ping.

Обратный вызов будет вызван с тремя аргументами: аргументом ошибки, который будет равен null, если PING был успешно подтвержден; аргументом duration, содержащим число миллисекунд, прошедших с момента отправки ping до получения подтверждения; и объектом Buffer, содержащим 8-байтовую полезную нагрузку PING.

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

Если аргумент payload не указан, полезной нагрузкой по умолчанию будет 64-битная временная метка в порядке байтов от младшего к старшему, обозначающая начало интервала PING.

http2session.ref()

Вызывает ref() для базового объекта net.Socket этого экземпляра Http2Session.

http2session.remoteSettings

• Тип: <HTTP/2 Settings Object>

Объект без прототипа, описывающий текущие удаленные настройки этого Http2Session. Удаленные настройки задаются подключенным узлом HTTP/2.

http2session.setLocalWindowSize(windowSize)

• windowSize <number>

Задает размер окна локальной конечной точки. windowSize — это общий размер окна, который необходимо установить, а не приращение.

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

Для клиентов http2 подходящим событием будет либо 'connect', либо 'remoteSettings'.

http2session.setTimeout(msecs, callback)

• msecs <number>
• callback <Function>

Используется для установки функции обратного вызова, которая вызывается, если в Http2Session нет активности в течение msecs миллисекунд. Указанный callback регистрируется как обработчик события 'timeout'.

http2session.socket

• Тип: <net.Socket> | <tls.TLSSocket>

Возвращает объект Proxy, который действует как net.Socket (или tls.TLSSocket), но предоставляет только те методы, которые безопасно использовать с HTTP/2.

Вызов методов destroy, emit, end, pause, read, resume и write приведет к ошибке с кодом ERR_HTTP2_NO_SOCKET_MANIPULATION. Дополнительные сведения см. в разделе Http2Session и сокеты.

Для этого Http2Session будет вызван метод setTimeout.

Все остальные операции будут напрямую передаваться сокету.

http2session.state

Предоставляет различные сведения о текущем состоянии Http2Session.

• Тип: <Object>
  • effectiveLocalWindowSize <number> Текущий размер локального окна управления потоком (приема) для Http2Session.
  • effectiveRecvDataLength <number> Текущее количество байтов, полученных с момента последнего кадра WINDOW_UPDATE управления потоком.
  • nextStreamID <number> Числовой идентификатор, который будет использован при следующем создании нового Http2Stream этим объектом Http2Session.
  • localWindowSize <number> Количество байтов, которые удаленный узел может отправить, не получив WINDOW_UPDATE.
  • lastProcStreamID <number> Числовой идентификатор Http2Stream, для которого последним был получен кадр HEADERS или DATA.
  • remoteWindowSize <number> Количество байтов, которые этот Http2Session может отправить, не получив WINDOW_UPDATE.
  • outboundQueueSize <number> Количество кадров, находящихся в данный момент в очереди исходящих данных этого Http2Session.
  • deflateDynamicTableSize <number> Текущий размер таблицы состояния сжатия исходящих заголовков в байтах.
  • inflateDynamicTableSize <number> Текущий размер таблицы состояния сжатия входящих заголовков в байтах.

Объект, описывающий текущее состояние этого Http2Session.

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

• settings <HTTP/2 Settings Object>
• callback <Function> Обратный вызов, который вызывается после подключения сеанса или сразу, если сеанс уже подключен.
  • err <Error> | <null>
  • settings <HTTP/2 Settings Object> Обновленный объект settings.
  • duration <integer>

Обновляет текущие локальные настройки этого Http2Session и отправляет новый кадр SETTINGS подключенному узлу HTTP/2.

После вызова свойство http2session.pendingSettingsAck будет иметь значение true, пока сеанс ожидает подтверждения новых настроек удаленным узлом.

Новые настройки вступят в силу только после получения подтверждения SETTINGS и генерации события 'localSettings'. Можно отправлять несколько кадров SETTINGS, пока подтверждение еще ожидается.

http2session.type

• Тип: <number>

Значение http2session.type будет равно http2.constants.NGHTTP2_SESSION_SERVER, если этот экземпляр Http2Session является сервером, и http2.constants.NGHTTP2_SESSION_CLIENT, если экземпляр является клиентом.

http2session.unref()

Вызывает unref() для базового net.Socket этого экземпляра Http2Session.

Класс: ServerHttp2Session

• Наследует: <Http2Session>

serverhttp2session.altsvc(alt, originOrStream)

• alt <string> Описание конфигурации альтернативной службы, определенной в RFC 7838.
• originOrStream <number> | <string> | <URL> | <Object> Строка URL, задающая источник (или Object со свойством origin), либо числовой идентификатор активного Http2Stream, заданный свойством http2stream.id.

Отправляет подключенному клиенту кадр ALTSVC (определенный в RFC 7838).

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

Отправка кадра ALTSVC с определенным идентификатором потока указывает, что альтернативная служба связана с источником указанного Http2Stream.

Значение alt и строка источника должны содержать только байты ASCII и строго интерпретируются как последовательность байтов ASCII. Специальное значение 'clear' можно передать, чтобы удалить все ранее заданные альтернативные службы для указанного домена.

Если в аргументе originOrStream передана строка, она будет разобрана как URL, а источник будет получен из нее. Например, источник HTTP URL 'https://example.org/foo/bar' — это строка ASCII 'https://example.org'. Будет вызвана ошибка, если переданную строку нельзя разобрать как URL или если невозможно получить допустимый источник.

В качестве originOrStream можно передать объект URL или любой объект со свойством origin; в этом случае будет использовано значение свойства origin. Значение свойства origin должно быть правильно сериализованным источником ASCII.

Указание альтернативных служб

Формат параметра alt строго определен в RFC 7838: это строка ASCII со списком протоколов «альтернатив», разделенных запятыми и связанных с определенным узлом и портом.

Например, значение 'h2="example.org:81"' указывает, что протокол HTTP/2 доступен на узле 'example.org' через порт TCP/IP 81. Узел и порт должны быть заключены в кавычки (символы ").

Можно указать несколько альтернатив, например: 'h2="example.org:81", h2=":82"'.

Идентификатор протокола ('h2' в примерах) может быть любым допустимым идентификатором протокола ALPN.

Реализация Node.js не проверяет синтаксис этих значений: они передаются без изменений в том виде, в каком были предоставлены пользователем или получены от узла.

serverhttp2session.origin(...origins)

• origins { string | URL | Object } Одна или несколько строк URL, передаваемых в качестве отдельных аргументов.

Отправляет подключенному клиенту кадр ORIGIN (определенный в RFC 8336), чтобы сообщить набор источников, для которых сервер может предоставлять авторитетные ответы.

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

Если в качестве origin передана строка, она будет разобрана как URL, а источник будет получен из нее. Например, источник HTTP URL 'https://example.org/foo/bar' — это строка ASCII 'https://example.org'. Будет вызвана ошибка, если переданную строку нельзя разобрать как URL или если невозможно получить допустимый источник.

В качестве origin можно передать объект URL или любой объект со свойством origin; в этом случае будет использовано значение свойства origin. Значение свойства origin должно быть правильно сериализованным источником ASCII.

В качестве альтернативы при создании нового сервера HTTP/2 с помощью метода http2.createSecureServer() можно использовать параметр origins:

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

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

Класс: ClientHttp2Session

• Наследует: <Http2Session>

Событие: 'altsvc'

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

Событие 'altsvc' возникает каждый раз, когда клиент получает кадр ALTSVC. Событие передается со значением ALTSVC, источником и идентификатором потока. Если в кадре ALTSVC не указан origin, значение origin будет пустой строкой.

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

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

Событие: 'origin'

• origins <string[]>

Событие 'origin' возникает каждый раз, когда клиент получает кадр ORIGIN. Событие передается с массивом строк origin. Значение http2session.originSet обновляется и включает полученные источники.

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

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

Событие 'origin' возникает только при использовании защищенного соединения TLS.

clienthttp2session.request(headers[, options])

• headers <HTTP/2 Headers Object>

• options <Object>

  • endStream <boolean> true, если изначально следует закрыть записываемую сторону Http2Stream, например при отправке запроса GET, для которого не ожидается тело.
  • exclusive <boolean> Если true и parent указывают на родительский поток, созданный поток становится единственной непосредственной зависимостью родительского потока, а все остальные существующие зависимые потоки становятся зависимыми от вновь созданного потока. По умолчанию: false.
  • parent <number> Указывает числовой идентификатор потока, от которого зависит вновь созданный поток.
  • waitForTrailers <boolean> Если задано значение true, Http2Stream вызовет событие 'wantTrailers' после отправки последнего кадра DATA.
  • signal <AbortSignal> Сигнал AbortSignal, который можно использовать для отмены выполняющегося запроса.

• Возвращает: <ClientHttp2Stream>

Только для экземпляров клиента HTTP/2 Http2Session: http2session.request() создает и возвращает экземпляр Http2Stream, который можно использовать для отправки запроса HTTP/2 подключенному серверу.

При первом создании ClientHttp2Session сокет может быть еще не подключен. Если в это время вызывается clienthttp2session.request(), фактический запрос будет отложен до готовности сокета.

Если сеанс станет недоступен до создания запроса, для возвращенного потока асинхронно возникнет ERR_HTTP2_GOAWAY_SESSION или ERR_HTTP2_INVALID_SESSION.

Этот метод доступен только в том случае, если http2session.type равно http2.constants.NGHTTP2_SESSION_CLIENT.

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

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

Если задан параметр options.waitForTrailers, событие 'wantTrailers' возникает сразу после постановки в очередь последнего фрагмента данных тела для отправки. Затем можно вызвать метод http2stream.sendTrailers(), чтобы отправить узлу завершающие заголовки.

Если задан параметр options.waitForTrailers, Http2Stream не будет автоматически закрыт после передачи последнего кадра DATA. Пользовательский код должен вызвать http2stream.sendTrailers() или http2stream.close(), чтобы закрыть Http2Stream.

Если задан options.signal с AbortSignal, а затем для соответствующего AbortController вызывается abort, запрос вызовет событие 'error' с ошибкой AbortError.

Псевдозаголовки :method и :path не определены в headers; по умолчанию они принимают следующие значения:

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

Класс: Http2Stream

• Наследует: <stream.Duplex>

Каждый экземпляр класса Http2Stream представляет двунаправленный поток обмена данными HTTP/2 через экземпляр Http2Session. За время существования одного экземпляра Http2Session может быть создано до 2³¹-1 экземпляров Http2Stream.

Пользовательский код не создает экземпляры Http2Stream напрямую. Они создаются, управляются и передаются пользовательскому коду через экземпляр Http2Session. На сервере экземпляры Http2Stream создаются либо в ответ на входящий HTTP-запрос (и передаются пользовательскому коду через событие 'stream'), либо при вызове метода http2stream.pushStream(). На клиенте экземпляры Http2Stream создаются и возвращаются при вызове метода http2session.request() либо в ответ на входящее событие 'push'.

Класс Http2Stream является базовым для классов ServerHttp2Stream и ClientHttp2Stream, каждый из которых используется соответственно на стороне сервера или клиента.

Все экземпляры Http2Stream являются потоками Duplex. Сторона Writable объекта Duplex используется для отправки данных подключенному узлу, а сторона Readable — для получения данных, отправленных подключенным узлом.

Кодировка текста по умолчанию для Http2Stream — UTF-8. При использовании Http2Stream для отправки текста задайте кодировку символов в заголовке 'content-type'.

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

Http2Stream Жизненный цикл

Создание

На стороне сервера экземпляры ServerHttp2Stream создаются в следующих случаях:

• Получен новый кадр HEADERS HTTP/2 с ранее не использовавшимся идентификатором потока;
• Вызван метод http2stream.pushStream().

На стороне клиента экземпляры ClientHttp2Stream создаются при вызове метода http2session.request().

На клиенте экземпляр Http2Stream, возвращаемый методом http2session.request(), может быть не готов к использованию, если родительский Http2Session еще не установлен полностью. В таких случаях операции, вызываемые для Http2Stream, будут буферизованы до возникновения события 'ready'. Пользовательскому коду редко, если вообще когда-либо, требуется непосредственно обрабатывать событие 'ready'. Готовность Http2Stream можно определить, проверив значение http2stream.id. Если значение равно undefined, поток еще не готов к использованию.

Уничтожение

Все экземпляры Http2Stream уничтожаются в следующих случаях:

• Подключенный узел получает кадр RST_STREAM для потока, и (только для клиентских потоков) ожидающие данные прочитаны.
• Вызван метод http2stream.close(), и (только для клиентских потоков) ожидающие данные прочитаны.
• Вызван метод http2stream.destroy() или http2session.destroy().

При уничтожении экземпляра Http2Stream будет предпринята попытка отправить подключенному узлу кадр RST_STREAM.

При уничтожении экземпляра Http2Stream будет вызвано событие 'close'. Поскольку Http2Stream является экземпляром stream.Duplex, событие 'end' также будет вызвано, если данные потока в данный момент передаются. Событие 'error' также может быть вызвано, если http2stream.destroy() был вызван с объектом Error в качестве первого аргумента.

После уничтожения Http2Stream свойство http2stream.destroyed будет иметь значение true, а свойство http2stream.rstCode укажет код ошибки RST_STREAM. После уничтожения экземпляр Http2Stream больше нельзя использовать.

Событие: 'aborted'

Событие 'aborted' возникает, когда экземпляр Http2Stream неожиданно прерывается в процессе обмена данными. Обработчик этого события не ожидает аргументов.

Событие 'aborted' возникает только в том случае, если записываемая сторона Http2Stream еще не была завершена.

Событие: 'close'

Событие 'close' возникает при уничтожении Http2Stream. После вызова этого события экземпляр Http2Stream больше нельзя использовать.

Код ошибки HTTP/2, использованный при закрытии потока, можно получить с помощью свойства http2stream.rstCode. Если код отличается от NGHTTP2_NO_ERROR (0), также будет вызвано событие 'error'.

Событие: 'error'

• error <Error>

Событие 'error' возникает при ошибке во время обработки Http2Stream.

Событие: 'frameError'

• type <integer> Тип кадра.
• code <integer> Код ошибки.
• id <integer> Идентификатор потока (или 0, если кадр не связан с потоком).

Событие 'frameError' возникает при ошибке во время попытки отправить кадр. При вызове обработчик получает целочисленный аргумент, указывающий тип кадра, и целочисленный аргумент, указывающий код ошибки. Экземпляр Http2Stream будет уничтожен сразу после возникновения события 'frameError'.

Событие: 'ready'

Событие 'ready' возникает, когда Http2Stream открыт, ему назначен id и он готов к использованию. Обработчик этого события не ожидает аргументов.

Событие: 'timeout'

Событие 'timeout' возникает, если в течение количества миллисекунд, заданного с помощью http2stream.setTimeout(), для этого Http2Stream не поступает никаких данных. Обработчик этого события не ожидает аргументов.

Событие: 'trailers'

• headers <HTTP/2 Headers Object> Объект с описанием заголовков
• flags <number> Связанные числовые флаги
• rawHeaders { необработанные заголовки HTTP/2 }

Событие 'trailers' возникает при получении блока заголовков, связанного с завершающими полями заголовков. В обратный вызов обработчика передаются объект заголовков HTTP/2, связанные с заголовками флаги и заголовки в необработанном формате (см. необработанные заголовки HTTP/2).

Это событие может не возникнуть, если http2stream.end() вызван до получения завершающих заголовков и входящие данные не считываются и для них не зарегистрирован обработчик.

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

Событие: 'wantTrailers'

Событие 'wantTrailers' возникает, когда Http2Stream поставил в очередь последний кадр DATA для отправки в кадре и Http2Stream готов отправить завершающие заголовки. Чтобы вызвать это событие при отправке запроса или ответа, необходимо задать параметр waitForTrailers.

http2stream.aborted

• Тип: <boolean>

Принимает значение true, если экземпляр Http2Stream был неожиданно прерван. В этом случае событие 'aborted' уже было вызвано.

http2stream.bufferSize

• Тип: <number>

Это свойство показывает количество символов, в данный момент буферизованных для записи. Подробности см. в разделе net.Socket.bufferSize.

http2stream.close(code[, callback])

• code <number> Беззнаковое 32-битное целое число, идентифицирующее код ошибки. По умолчанию: http2.constants.NGHTTP2_NO_ERROR (0x00).
• callback <Function> Необязательная функция, зарегистрированная для обработки события 'close'.

Закрывает экземпляр Http2Stream, отправляя подключенному узлу HTTP/2 кадр RST_STREAM.

http2stream.closed

• Тип: <boolean>

Принимает значение true, если экземпляр Http2Stream закрыт.

http2stream.destroyed

• Тип: <boolean>

Принимает значение true, если экземпляр Http2Stream уничтожен и больше не может использоваться.

http2stream.endAfterHeaders

• Тип: <boolean>

Принимает значение true, если во входящем кадре HEADERS запроса или ответа установлен флаг END_STREAM, указывающий, что дополнительные данные больше не должны поступать и читаемая сторона Http2Stream будет закрыта.

http2stream.id

• Тип: <number> | <undefined>

Числовой идентификатор потока этого экземпляра Http2Stream. Принимает значение undefined, если идентификатор потока еще не назначен.

http2stream.pending

• Тип: <boolean>

Принимает значение true, если экземпляру Http2Stream еще не назначен числовой идентификатор потока.

http2stream.priority(options)

Пустой метод, оставленный только для сохранения обратной совместимости.

http2stream.rstCode

• Тип: <number>

Содержит код ошибки RST_STREAM, сообщенный при уничтожении Http2Stream после получения от подключенного узла кадра RST_STREAM, вызова http2stream.close() или http2stream.destroy(). Имеет значение undefined, если Http2Stream еще не закрыт.

http2stream.sentHeaders

• Тип: <HTTP/2 Headers Object>

Объект, содержащий исходящие заголовки, отправленные для этого Http2Stream.

http2stream.sentInfoHeaders

• Тип: <HTTP/2 Headers Object[]>

Массив объектов, содержащих отправленные исходящие информационные (дополнительные) заголовки для этого Http2Stream.

http2stream.sentTrailers

• Тип: <HTTP/2 Headers Object>

Объект, содержащий отправленные исходящие завершающие заголовки для этого HttpStream.

http2stream.session

• Тип: <Http2Session>

Ссылка на экземпляр Http2Session, которому принадлежит этот Http2Stream. Значение будет undefined после уничтожения экземпляра Http2Stream.

http2stream.setTimeout(msecs, callback)

• msecs <number>
• callback <Function>

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

// Cancel the stream if there's no activity after 5 seconds
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL));

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

// Cancel the stream if there's no activity after 5 seconds
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL));

http2stream.state

Предоставляет различные сведения о текущем состоянии Http2Stream.

• Тип: <Object>
  • localWindowSize <number> Количество байтов, которое подключенный узел может отправить для этого Http2Stream, не получив WINDOW_UPDATE.
  • state <number> Флаг, указывающий текущее состояние Http2Stream низкого уровня, определяемое посредством nghttp2.
  • localClose <number> 1, если этот Http2Stream был закрыт локально.
  • remoteClose <number> 1, если этот Http2Stream был закрыт удаленно.
  • sumDependencyWeight <number> Устаревшее свойство, которому всегда присваивается значение 0.
  • weight <number> Устаревшее свойство, которому всегда присваивается значение 16.

Текущее состояние этого Http2Stream.

http2stream.sendTrailers(headers)

• headers <HTTP/2 Headers Object>

Отправляет завершающий кадр HEADERS подключенному узлу HTTP/2. Этот метод немедленно закрывает Http2Stream, поэтому его можно вызывать только после создания события 'wantTrailers'. При отправке запроса или ответа необходимо задать параметр options.waitForTrailers, чтобы Http2Stream оставался открытым после отправки последнего кадра DATA и можно было отправить завершающие заголовки.

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

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

Спецификация HTTP/1 запрещает включать в завершающие заголовки псевдозаголовки HTTP/2 (например, ':method', ':path' и т. д.).

Класс: ClientHttp2Stream

• Наследует <Http2Stream>

Класс ClientHttp2Stream является расширением Http2Stream, используемым исключительно в клиентах HTTP/2. Экземпляры Http2Stream на стороне клиента предоставляют такие события, как 'response' и 'push', актуальные только для клиента.

Событие: 'continue'

Вызывается, когда сервер отправляет статус 100 Continue, обычно потому, что запрос содержит Expect: 100-continue. Это указание клиенту отправить тело запроса.

Событие: 'headers'

• headers <HTTP/2 Headers Object>
• flags <number>
• rawHeaders {Необработанные заголовки HTTP/2}

Событие 'headers' вызывается при получении для потока дополнительного блока заголовков, например блока из 1xx информационных заголовков. Функция-обработчик получает объект объект заголовков HTTP/2, связанные с заголовками флаги и заголовки в необработанном формате (см. необработанные заголовки HTTP/2).

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

Событие: 'push'

• headers <HTTP/2 Headers Object>
• flags <number>
• rawHeaders {Необработанные заголовки HTTP/2}

Событие 'push' вызывается при получении заголовков ответа для потока Server Push. Функция-обработчик получает объект объект заголовков HTTP/2, связанные с заголовками флаги и заголовки в необработанном формате (см. необработанные заголовки HTTP/2).

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

Событие: 'response'

• headers <HTTP/2 Headers Object>
• flags <number>
• rawHeaders {Необработанные заголовки HTTP/2}

Событие 'response' вызывается, когда подключенный сервер HTTP/2 отправляет для этого потока кадр HEADERS. Обработчик вызывается с тремя аргументами: Object, содержащим полученный объект заголовков HTTP/2, флаги, связанные с заголовками, и заголовки в необработанном формате (см. необработанные заголовки HTTP/2).

import { connect } from 'node:http2';
const client = connect('https://localhost');
const req = client.request({ ':path': '/' });
req.on('response', (headers, flags) => {
  console.log(headers[':status']);
});

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

Класс: ServerHttp2Stream

• Наследует: <Http2Stream>

Класс ServerHttp2Stream является расширением Http2Stream, используемым исключительно на серверах HTTP/2. Экземпляры Http2Stream на стороне сервера предоставляют дополнительные методы, такие как http2stream.pushStream() и http2stream.respond(), актуальные только для сервера.

http2stream.additionalHeaders(headers)

• headers <HTTP/2 Headers Object>

Отправляет подключенному узлу HTTP/2 дополнительный информационный кадр HEADERS.

http2stream.headersSent

• Тип: <boolean>

True, если заголовки были отправлены, иначе false (только для чтения).

http2stream.pushAllowed

• Тип: <boolean>

Свойство только для чтения, соответствующее флагу SETTINGS_ENABLE_PUSH в последнем кадре SETTINGS удаленного клиента. Имеет значение true, если удаленный узел принимает потоки push, и false в противном случае. Настройки одинаковы для каждого Http2Stream в рамках одного и того же Http2Session.

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

• headers <HTTP/2 Headers Object>
• options <Object>
  • exclusive <boolean> Если true и parent указывает родительский поток, созданный поток становится единственной непосредственной зависимостью родительского потока, а все остальные существующие зависимые потоки становятся зависимыми от нового потока. По умолчанию: false.
  • parent <number> Указывает числовой идентификатор потока, от которого зависит новый поток.
• callback <Function> Обратный вызов, который вызывается после инициализации потока push.
  • err <Error>
  • pushStream <ServerHttp2Stream> Возвращенный объект pushStream.
  • headers <HTTP/2 Headers Object> Объект заголовков, с которым был инициирован pushStream.

Инициирует поток push. Обратный вызов вызывается с новым экземпляром Http2Stream, созданным для потока push и переданным вторым аргументом, либо с Error, переданным первым аргументом.

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

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

Задавать вес потока push в кадре HEADERS нельзя. Передайте значение weight в http2stream.priority с параметром silent, установленным в true, чтобы включить балансировку пропускной способности на стороне сервера между параллельными потоками.

Вызов http2stream.pushStream() из потока push запрещен и приведет к ошибке.

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

• headers <HTTP/2 Headers Object>
• options <Object>
  • endStream <boolean> Установите значение true, чтобы указать, что ответ не будет содержать данные полезной нагрузки.
  • waitForTrailers <boolean> Если задано true, Http2Stream вызовет событие 'wantTrailers' после отправки последнего кадра DATA.

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.end('some data');
});

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.end('some data');
});

Инициирует ответ. Если задан параметр options.waitForTrailers, событие 'wantTrailers' будет вызвано сразу после постановки в очередь последнего фрагмента данных полезной нагрузки для отправки. Затем метод http2stream.sendTrailers() можно использовать для отправки узлу завершающих полей заголовков.

Если задан options.waitForTrailers, Http2Stream не будет автоматически закрыт после передачи последнего кадра DATA. Пользовательский код должен вызвать http2stream.sendTrailers() или http2stream.close(), чтобы закрыть Http2Stream.

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

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

• fd <number> | <FileHandle> Дескриптор файла для чтения.
• headers <HTTP/2 Headers Object>
• options <Object>
  • statCheck <Function>
  • waitForTrailers <boolean> Если задано true, Http2Stream вызовет событие 'wantTrailers' после отправки последнего кадра DATA.
  • offset <number> Смещение, с которого следует начать чтение.
  • length <number> Объем данных, отправляемых из fd.

Инициирует ответ, данные которого считываются из указанного дескриптора файла. Проверка указанного дескриптора файла не выполняется. Если при попытке чтения данных с помощью дескриптора файла происходит ошибка, Http2Stream будет закрыт с помощью кадра RST_STREAM со стандартным кодом INTERNAL_ERROR.

При использовании интерфейс Duplex объекта Http2Stream будет закрыт автоматически.

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

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

Необязательная функция options.statCheck может быть указана, чтобы пользовательский код мог задать дополнительные заголовки содержимого на основе сведений fs.Stat об указанном fd. Если указана функция statCheck, метод http2stream.respondWithFD() выполнит вызов fs.fstat() для сбора сведений об указанном дескрипторе файла.

Параметры offset и length можно использовать, чтобы ограничить ответ определенным диапазоном. Это может использоваться, например, для поддержки запросов HTTP Range.

Дескриптор файла или FileHandle не закрывается при закрытии потока, поэтому его необходимо закрыть вручную, когда он больше не нужен. Одновременное использование одного дескриптора файла несколькими потоками не поддерживается и может привести к потере данных. Повторное использование дескриптора файла после завершения потока поддерживается.

Если задан параметр options.waitForTrailers, событие 'wantTrailers' будет вызвано сразу после постановки в очередь последнего фрагмента данных полезной нагрузки для отправки. Затем метод http2stream.sendTrailers() можно использовать для отправки узлу завершающих полей заголовков.

Если задан options.waitForTrailers, Http2Stream не будет автоматически закрыт после передачи последнего кадра DATA. Пользовательский код должен вызвать http2stream.sendTrailers() или http2stream.close(), чтобы закрыть Http2Stream.

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

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

• path <string> | <Buffer> | <URL>
• headers <HTTP/2 Headers Object>
• options <Object>
  • statCheck <Function>
  • onError <Function> Функция обратного вызова, вызываемая в случае ошибки до отправки.
  • waitForTrailers <boolean> Если задано true, Http2Stream вызовет событие 'wantTrailers' после отправки последнего кадра DATA.
  • offset <number> Смещение, с которого следует начать чтение.
  • length <number> Объем данных, отправляемых из fd.

Отправляет обычный файл в качестве ответа. В path должен быть указан обычный файл, иначе для объекта Http2Stream будет вызвано событие 'error'.

При использовании интерфейс Duplex объекта Http2Stream будет закрыт автоматически.

Необязательная функция options.statCheck может быть указана, чтобы пользовательский код мог задать дополнительные заголовки содержимого на основе сведений fs.Stat об указанном файле:

Если при попытке чтения данных файла происходит ошибка, Http2Stream будет закрыт с помощью кадра RST_STREAM со стандартным кодом INTERNAL_ERROR. Если задан обратный вызов onError, он будет вызван. В противном случае поток будет уничтожен.

Пример использования пути к файлу:

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() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.error(err);
    }
    stream.end();
  }

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

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() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.error(err);
    }
    stream.end();
  }

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

Функцию options.statCheck также можно использовать для отмены операции отправки, вернув false. Например, условный запрос может проверить результаты stat, чтобы определить, был ли изменен файл, и вернуть подходящий ответ 304:

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // Check the stat here...
    stream.respond({ ':status': 304 });
    return false; // Cancel the send operation
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
});

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // Check the stat here...
    stream.respond({ ':status': 304 });
    return false; // Cancel the send operation
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
});

Поле заголовка content-length будет задано автоматически.

Параметры offset и length можно использовать, чтобы ограничить ответ определенным диапазоном. Это может использоваться, например, для поддержки запросов HTTP Range.

Функцию options.onError также можно использовать для обработки всех ошибок, которые могут произойти до начала передачи файла. По умолчанию поток уничтожается.

Если задан параметр options.waitForTrailers, событие 'wantTrailers' будет вызвано сразу после постановки в очередь последнего фрагмента данных полезной нагрузки для отправки. Затем метод http2stream.sendTrailers() можно использовать для отправки узлу завершающих полей заголовков.

Если задан options.waitForTrailers, Http2Stream не будет автоматически закрыт после передачи последнего кадра DATA. Пользовательский код должен вызвать http2stream.sendTrailers() или http2stream.close(), чтобы закрыть Http2Stream.

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

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

Класс: Http2Server

• Наследует: <net.Server>

Экземпляры Http2Server создаются с помощью функции http2.createServer(). Класс Http2Server не экспортируется напрямую модулем node:http2.

Событие: 'checkContinue'

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

Если зарегистрирован обработчик 'request' или для http2.createServer() указана функция обратного вызова, событие 'checkContinue' вызывается при каждом получении запроса с HTTP Expect: 100-continue. Если обработчик этого события отсутствует, сервер автоматически отправляет соответствующий статус 100 Continue.

Для обработки этого события необходимо вызвать response.writeContinue(), если клиенту следует продолжить отправку тела запроса, либо сформировать подходящий ответ HTTP (например, 400 Bad Request), если клиенту не следует продолжать отправку тела запроса.

Если это событие вызвано и обработано, событие 'request' вызвано не будет.

Событие: 'connection'

• socket <stream.Duplex>

Это событие вызывается при установлении нового потока TCP. Обычно socket — это объект типа net.Socket. Как правило, пользователям не требуется обращаться к этому событию.

Пользователи могут также явно вызывать это событие, чтобы передать подключения HTTP-серверу. В этом случае можно передать любой поток Duplex.

Событие: 'request'

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

Вызывается при каждом поступлении запроса. В рамках одного сеанса может поступить несколько запросов. См. API совместимости.

Событие: 'session'

• session <ServerHttp2Session>

Событие 'session' вызывается при создании нового Http2Session объектом Http2Server.

Событие: 'sessionError'

• error <Error>
• session <ServerHttp2Session>

Событие 'sessionError' вызывается, когда событие 'error' вызывается объектом Http2Session, связанным с Http2Server.

Событие: 'stream'

• stream <Http2Stream> Ссылка на поток
• headers <HTTP/2 Headers Object> Объект с описанием заголовков
• flags <number> Соответствующие числовые флаги
• rawHeaders {Необработанные заголовки HTTP/2} Массив, содержащий необработанные заголовки

Событие 'stream' вызывается, когда событие 'stream' вызвано объектом Http2Session, связанным с сервером.

См. также событие 'stream' объекта Http2Session.

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

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

Событие: 'timeout'

Событие 'timeout' вызывается, если на сервере отсутствует активность в течение числа миллисекунд, заданного с помощью http2server.setTimeout(). По умолчанию: 0 (без тайм-аута)

server.close([callback])

• callback <Function>

Останавливает сервер, запрещая создание новых сеансов. Это не предотвращает создание новых потоков запросов из-за постоянного характера сеансов HTTP/2. Чтобы корректно завершить работу сервера, вызовите http2session.close() для всех активных сеансов.

Если предоставлен callback, он не будет вызван, пока все активные сеансы не будут закрыты, хотя сервер уже перестанет разрешать новые сеансы. Подробнее см. в разделе net.Server.close().

server[Symbol.asyncDispose]()

Вызывает server.close() и возвращает промис, который выполняется после закрытия сервера.

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

• msecs <number> По умолчанию: 0 (тайм-аут отсутствует)
• callback <Function>
• Возвращает: <Http2Server>

Используется для установки значения тайм-аута для запросов сервера http2 и задаёт функцию обратного вызова, которая вызывается, если на Http2Server отсутствует активность в течение msecs миллисекунд.

Переданный обратный вызов регистрируется как обработчик события 'timeout'.

Если callback не является функцией, будет вызвана новая ошибка ERR_INVALID_ARG_TYPE.

server.timeout

• Тип: <number> Тайм-аут в миллисекундах. По умолчанию: 0 (тайм-аут отсутствует)

Количество миллисекунд бездействия, по истечении которого считается, что время ожидания сокета истекло.

Значение 0 отключает действие тайм-аута для входящих подключений.

Логика тайм-аута сокета настраивается при подключении, поэтому изменение этого значения влияет только на новые подключения к серверу, но не на уже существующие.

server.updateSettings([settings])

• settings <HTTP/2 Settings Object>

Используется для обновления сервера с помощью предоставленных параметров.

Для недопустимых значений settings вызывается ERR_HTTP2_INVALID_SETTING_VALUE.

Для недопустимого аргумента settings вызывается ERR_INVALID_ARG_TYPE.

Класс: Http2SecureServer

• Наследует: <tls.Server>

Экземпляры Http2SecureServer создаются с помощью функции http2.createSecureServer(). Класс Http2SecureServer напрямую не экспортируется модулем node:http2.

Событие: 'checkContinue'

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

Если зарегистрирован обработчик 'request' или для http2.createSecureServer() предоставлена функция обратного вызова, событие 'checkContinue' генерируется при каждом получении запроса с HTTP Expect: 100-continue. Если это событие не обрабатывается, сервер автоматически отправит соответствующий статус 100 Continue.

Для обработки этого события необходимо вызвать response.writeContinue(), если клиенту следует продолжить отправку тела запроса, либо сформировать подходящий ответ HTTP (например, 400 Bad Request), если клиенту не следует продолжать отправку тела запроса.

При генерации и обработке этого события событие 'request' генерироваться не будет.

Событие: 'connection'

• socket <stream.Duplex>

Это событие генерируется при установлении нового потока TCP до начала TLS-рукопожатия. socket обычно является объектом типа net.Socket. Как правило, пользователям не требуется обращаться к этому событию.

Пользователи также могут явно генерировать это событие, чтобы передавать подключения HTTP-серверу. В этом случае можно передать любой поток Duplex.

Событие: 'request'

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

Генерируется при каждом запросе. В одном сеансе может быть несколько запросов. См. API совместимости.

Событие: 'session'

• session <ServerHttp2Session>

Событие 'session' генерируется при создании нового Http2Session объектом Http2SecureServer.

Событие: 'sessionError'

• error <Error>
• session <ServerHttp2Session>

Событие 'sessionError' генерируется, когда объект Http2Session, связанный с Http2SecureServer, генерирует событие 'error'.

Событие: 'stream'

• stream <Http2Stream> Ссылка на поток
• headers <HTTP/2 Headers Object> Объект с описанием заголовков
• flags <number> Связанные числовые флаги
• rawHeaders {Необработанные заголовки HTTP/2} Массив, содержащий необработанные заголовки

Событие 'stream' генерируется, когда объект Http2Session, связанный с сервером, генерирует событие 'stream'.

См. также событие 'stream' объекта Http2Session.

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

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

Событие: 'timeout'

Событие 'timeout' генерируется, если на сервере отсутствует активность в течение заданного количества миллисекунд, установленного с помощью http2secureServer.setTimeout(). По умолчанию: 2 минуты.

Событие: 'unknownProtocol'

• socket <stream.Duplex>

Событие 'unknownProtocol' генерируется, когда подключающийся клиент не может согласовать разрешённый протокол (то есть HTTP/2 или HTTP/1.1). Обработчик события получает сокет для обработки. Если для этого события не зарегистрирован обработчик, подключение завершается. Тайм-аут можно задать с помощью параметра 'unknownProtocolTimeout', переданного в http2.createSecureServer().

В более ранних версиях Node.js это событие генерировалось, если allowHTTP1 равно false и во время TLS-рукопожатия клиент не отправлял расширение ALPN либо отправлял расширение ALPN, не включающее HTTP/2 (h2). В новых версиях Node.js это событие генерируется, только если allowHTTP1 равно false и клиент не отправляет расширение ALPN. Если клиент отправляет расширение ALPN, не включающее HTTP/2 (или HTTP/1.1, если allowHTTP1 равно true), TLS-рукопожатие завершится ошибкой, и защищённое подключение не будет установлено.

См. API совместимости.

server.close([callback])

• callback <Function>

Останавливает сервер, запрещая создание новых сеансов. Это не предотвращает создание новых потоков запросов из-за постоянного характера сеансов HTTP/2. Чтобы корректно завершить работу сервера, вызовите http2session.close() для всех активных сеансов.

Если предоставлен callback, он не будет вызван, пока все активные сеансы не будут закрыты, хотя сервер уже перестанет разрешать новые сеансы. Подробнее см. в разделе tls.Server.close().

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

• msecs <number> По умолчанию: 120000 (2 минуты)
• callback <Function>
• Возвращает: <Http2SecureServer>

Используется для установки значения тайм-аута для запросов защищённого сервера http2 и задаёт функцию обратного вызова, которая вызывается, если на Http2SecureServer отсутствует активность в течение msecs миллисекунд.

Переданный обратный вызов регистрируется как обработчик события 'timeout'.

Если callback не является функцией, будет вызвана новая ошибка ERR_INVALID_ARG_TYPE.

server.timeout

• Тип: <number> Тайм-аут в миллисекундах. По умолчанию: 0 (тайм-аут отсутствует)

Количество миллисекунд бездействия, по истечении которого считается, что время ожидания сокета истекло.

Значение 0 отключает действие тайм-аута для входящих подключений.

Логика тайм-аута сокета настраивается при подключении, поэтому изменение этого значения влияет только на новые подключения к серверу, но не на уже существующие.

server.updateSettings([settings])

• settings <HTTP/2 Settings Object>

Используется для обновления сервера с помощью предоставленных параметров.

Для недопустимых значений settings вызывается ERR_HTTP2_INVALID_SETTING_VALUE.

Для недопустимого аргумента settings вызывается ERR_INVALID_ARG_TYPE.

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

• options <Object>
  • maxDeflateDynamicTableSize <number> Устанавливает максимальный размер динамической таблицы для сжатия полей заголовков. По умолчанию: 4Kib.
  • maxSettings <number> Устанавливает максимальное количество записей параметров в каждом кадре SETTINGS. Минимально допустимое значение — 1. По умолчанию: 32.
  • maxSessionMemory<number> Устанавливает максимальный объём памяти, который может использовать Http2Session. Значение задаётся в мегабайтах; например, 1 соответствует 1 мегабайту. Минимально допустимое значение — 1. Это ограничение основано на кредитах: существующие Http2Stream могут привести к превышению лимита, но новые экземпляры Http2Stream будут отклоняться, пока лимит превышен. В текущий лимит учитываются текущее количество сеансов Http2Stream, текущий объём памяти, используемый таблицами сжатия заголовков, данные, ожидающие отправки, а также неподтверждённые кадры PING и SETTINGS. По умолчанию: 10.
  • maxHeaderListPairs <number> Устанавливает максимальное количество записей заголовков. Аналогично параметрам server.maxHeadersCount или request.maxHeadersCount модуля node:http. Минимальное значение — 4. По умолчанию: 128.
  • maxOutstandingPings <number> Устанавливает максимальное количество ожидающих подтверждения ping-запросов. По умолчанию: 10.
  • maxSendHeaderBlockLength <number> Устанавливает максимальный допустимый размер сериализованного сжатого блока заголовков. Попытки отправить заголовки, превышающие этот лимит, приведут к генерации события 'frameError', а поток будет закрыт и уничтожен. Хотя этот параметр задаёт максимальный допустимый размер всего блока заголовков, nghttp2 (внутренняя библиотека http2) ограничивает каждую распакованную пару «ключ/значение» размером 65536.
  • paddingStrategy <number> Стратегия определения объёма заполнения для кадров HEADERS и DATA. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Возможные значения:
    • http2.constants.PADDING_STRATEGY_NONE: заполнение не применяется.
    • http2.constants.PADDING_STRATEGY_MAX: применяется максимально возможный объём заполнения, определяемый внутренней реализацией.
    • http2.constants.PADDING_STRATEGY_ALIGNED: предпринимается попытка добавить достаточно заполнения, чтобы общая длина кадра, включая 9-байтовый заголовок, была кратна 8. Для каждого кадра существует максимальное допустимое количество байтов заполнения, определяемое текущим состоянием управления потоком и настройками. Если этот максимум меньше рассчитанного объёма, необходимого для выравнивания, используется максимальное значение, и общая длина кадра не обязательно будет кратна 8 байтам.
  • peerMaxConcurrentStreams <number> Устанавливает максимальное количество параллельных потоков для удалённого узла, как если бы был получен кадр SETTINGS. Это значение будет переопределено, если удалённый узел задаст собственное значение maxConcurrentStreams. По умолчанию: 100.
  • maxSessionInvalidFrames <integer> Устанавливает максимальное количество недопустимых кадров, которое допускается до закрытия сеанса. По умолчанию: 1000.
  • maxSessionRejectedStreams <integer> Устанавливает максимальное количество потоков, отклонённых при создании, которое допускается до закрытия сеанса. Каждое отклонение связано с ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна сообщать удалённому узлу, чтобы тот не открывал новые потоки; поэтому продолжение открытия потоков считается признаком неправильного поведения удалённого узла. По умолчанию: 100.
  • settings <HTTP/2 Settings Object> Начальные параметры, отправляемые удалённому узлу при подключении.
  • streamResetBurst <number> и streamResetRate <number> Устанавливают ограничение частоты для сброса входящих потоков (кадров RST_STREAM). Чтобы параметры действовали, необходимо задать оба; значения по умолчанию — 1000 и 33 соответственно.
  • remoteCustomSettings <Array> Массив целочисленных значений определяет типы параметров, включаемые в свойство CustomSettings объекта remoteSettings. Дополнительные сведения о допустимых типах параметров см. в свойстве CustomSettings объекта Http2Settings.
  • Http1IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage, используемый для резервного режима HTTP/1. Полезно для расширения исходного http.IncomingMessage. По умолчанию: http.IncomingMessage. Устарело. Вместо этого используйте http1Options.IncomingMessage. См. DEP0202.
  • Http1ServerResponse <http.ServerResponse> Указывает класс ServerResponse, используемый для резервного режима HTTP/1. Полезно для расширения исходного http.ServerResponse. По умолчанию: http.ServerResponse. Устарело. Вместо этого используйте http1Options.ServerResponse. См. DEP0202.
  • http1Options <Object> Объект параметров для настройки резервного режима HTTP/1, когда allowHTTP1 равно true. Эти параметры передаются базовому серверу HTTP/1. Доступные параметры см. в разделе http.createServer(). Помимо прочих, поддерживаются следующие параметры:
    • IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage для резервного режима HTTP/1. По умолчанию: http.IncomingMessage.
    • ServerResponse <http.ServerResponse> Указывает класс ServerResponse для резервного режима HTTP/1. По умолчанию: http.ServerResponse.
    • keepAliveTimeout <number> Время в миллисекундах, в течение которого сервер должен ожидать дополнительные входящие данные после завершения отправки последнего ответа, прежде чем сокет будет уничтожен. По умолчанию: 5000.
  • Http2ServerRequest <http2.Http2ServerRequest> Указывает используемый класс Http2ServerRequest. Полезно для расширения исходного Http2ServerRequest. По умолчанию: Http2ServerRequest.
  • Http2ServerResponse <http2.Http2ServerResponse> Указывает используемый класс Http2ServerResponse. Полезно для расширения исходного Http2ServerResponse. По умолчанию: Http2ServerResponse.
  • unknownProtocolTimeout <number> Задаёт тайм-аут в миллисекундах, который сервер должен ожидать после генерации события 'unknownProtocol'. Если к этому моменту сокет не будет уничтожен, сервер уничтожит его. По умолчанию: 10000.
  • strictFieldWhitespaceValidation <boolean> Если true, включается строгая проверка начальных и конечных пробелов в именах и значениях полей заголовков HTTP/2 в соответствии с RFC-9113. По умолчанию: true.
  • strictSingleValueFields <boolean> Если true, для заголовков и завершающих заголовков, определённых как имеющие только одно значение, применяется строгая проверка: при передаче нескольких значений возникает ошибка. По умолчанию: true.
  • ...options <Object> Можно передать любой параметр net.createServer().
• onRequestHandler <Function> См. API совместимости
• Возвращает: <Http2Server>

Возвращает экземпляр net.Server, который создаёт экземпляры Http2Session и управляет ими.

Поскольку нет известных браузеров, поддерживающих незашифрованный HTTP/2, для взаимодействия с браузерными клиентами необходимо использовать http2.createSecureServer().

import { createServer } from 'node:http2';

// Create an unencrypted HTTP/2 server.
// Since there are no browsers known that support
// unencrypted HTTP/2, the use of `createSecureServer()`
// is necessary when communicating with browser clients.
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);

const http2 = require('node:http2');

// Create an unencrypted HTTP/2 server.
// Since there are no browsers known that support
// unencrypted HTTP/2, the use of `http2.createSecureServer()`
// is necessary when communicating with browser clients.
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])

• options <Object>
  • allowHTTP1 <boolean> Входящие подключения клиентов, не поддерживающих HTTP/2, будут переключены на HTTP/1.x, если установлено значение true. См. событие 'unknownProtocol'. См. раздел Согласование ALPN. По умолчанию: false.
  • maxDeflateDynamicTableSize <number> Задает максимальный размер динамической таблицы для сжатия полей заголовка. По умолчанию: 4Kib.
  • maxSettings <number> Задает максимальное количество записей настроек в каждом кадре SETTINGS. Минимально допустимое значение — 1. По умолчанию: 32.
  • maxSessionMemory<number> Задает максимальный объем памяти, который разрешено использовать Http2Session. Значение указывается в мегабайтах; например, 1 соответствует 1 мегабайту. Минимально допустимое значение — 1. Это ограничение основано на кредитах: уже существующие экземпляры Http2Stream могут привести к превышению этого ограничения, однако новые экземпляры Http2Stream будут отклоняться, пока ограничение превышено. В текущее ограничение включаются текущее количество сеансов Http2Stream, текущее использование памяти таблицами сжатия заголовков, данные, ожидающие отправки, а также неподтвержденные кадры PING и SETTINGS. По умолчанию: 10.
  • maxHeaderListPairs <number> Задает максимальное количество записей заголовков. Это аналогично server.maxHeadersCount или request.maxHeadersCount в модуле node:http. Минимальное значение — 4. По умолчанию: 128.
  • maxOutstandingPings <number> Задает максимальное количество ожидающих подтверждения ping-запросов. По умолчанию: 10.
  • maxSendHeaderBlockLength <number> Задает максимально допустимый размер сериализованного сжатого блока заголовков. Попытки отправить заголовки, превышающие это ограничение, приведут к возникновению события 'frameError', а поток будет закрыт и уничтожен.
  • paddingStrategy <number> Стратегия определения объема заполнения для кадров HEADERS и DATA. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Возможны следующие значения:
    • http2.constants.PADDING_STRATEGY_NONE: заполнение не применяется.
    • http2.constants.PADDING_STRATEGY_MAX: применяется максимально возможное заполнение, определяемое внутренней реализацией.
    • http2.constants.PADDING_STRATEGY_ALIGNED: предпринимается попытка добавить достаточное заполнение, чтобы общая длина кадра, включая 9-байтовый заголовок, была кратна 8. Для каждого кадра максимальное допустимое количество байтов заполнения определяется текущим состоянием управления потоком и настройками. Если это максимальное значение меньше рассчитанного количества, необходимого для выравнивания, используется максимальное значение, и общая длина кадра не обязательно будет кратна 8 байтам.
  • peerMaxConcurrentStreams <number> Задает максимальное количество параллельных потоков для удаленного узла, как если бы был получен кадр SETTINGS. Это значение будет переопределено, если удаленный узел задаст собственное значение maxConcurrentStreams. По умолчанию: 100.
  • maxSessionInvalidFrames <integer> Задает максимальное количество недопустимых кадров, которое допускается до закрытия сеанса. По умолчанию: 1000.
  • maxSessionRejectedStreams <integer> Задает максимальное количество отклоненных при создании потоков, которое допускается до закрытия сеанса. Каждое отклонение сопровождается ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна сообщить удаленному узлу, что не следует открывать новые потоки; поэтому дальнейшие попытки открыть потоки считаются признаком некорректного поведения удаленного узла. По умолчанию: 100.
  • settings <HTTP/2 Settings Object> Начальные настройки, отправляемые удаленному узлу при подключении.
  • streamResetBurst <number> и streamResetRate <number> Задают ограничение частоты для входящих сбросов потоков (кадр RST_STREAM). Чтобы эти параметры действовали, необходимо задать оба; значения по умолчанию — 1000 и 33 соответственно.
  • remoteCustomSettings <Array> Массив целочисленных значений определяет типы настроек, включаемые в свойство customSettings полученного объекта remoteSettings. Дополнительные сведения о допустимых типах настроек см. в свойстве customSettings объекта Http2Settings.
  • ...options <Object> Можно указать любые параметры tls.createServer(). Для серверов обычно требуются параметры идентификации (pfx или key/cert).
  • origins <string[]> Массив строк origin, отправляемых в кадре ORIGIN сразу после создания нового серверного Http2Session.
  • unknownProtocolTimeout <number> Указывает тайм-аут в миллисекундах, в течение которого сервер должен ожидать после возникновения события 'unknownProtocol'. Если к этому моменту сокет не был уничтожен, сервер уничтожит его. По умолчанию: 10000.
  • strictFieldWhitespaceValidation <boolean> Если задано значение true, включается строгая проверка начальных и конечных пробелов в именах и значениях полей заголовков HTTP/2 в соответствии с RFC-9113. По умолчанию: true.
  • strictSingleValueFields <boolean> Если задано значение true, для заголовков и завершающих заголовков, определенных как содержащие только одно значение, используется строгая проверка: при передаче нескольких значений возникает ошибка. По умолчанию: true.
  • http1Options <Object> Объект параметров для настройки резервного режима HTTP/1, когда allowHTTP1 имеет значение true. Эти параметры передаются базовому серверу HTTP/1. Список доступных параметров см. в разделе http.createServer(). Поддерживаются, в частности, следующие параметры:
    • IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage, используемый для резервного режима HTTP/1. По умолчанию: http.IncomingMessage.
    • ServerResponse <http.ServerResponse> Указывает класс ServerResponse, используемый для резервного режима HTTP/1. По умолчанию: http.ServerResponse.
    • keepAliveTimeout <number> Время бездействия в миллисекундах, в течение которого сервер должен ожидать дополнительные входящие данные после завершения записи последнего ответа, прежде чем сокет будет уничтожен. По умолчанию: 5000.
• onRequestHandler <Function> См. раздел API совместимости
• Возвращает: <Http2SecureServer>

Возвращает экземпляр tls.Server, который создает экземпляры Http2Session и управляет ими.

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

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

// Create a secure 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);

const http2 = require('node:http2');
const fs = require('node:fs');

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

// Create a secure 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])

• authority <string> | <URL> Удаленный HTTP/2-сервер для подключения. Это должен быть минимальный корректный URL с префиксом http:// или https://, именем узла и IP-портом (если используется порт, отличный от порта по умолчанию). Данные пользователя (идентификатор и пароль), путь, строка запроса и фрагмент URL игнорируются.
• options <Object>
  • maxDeflateDynamicTableSize <number> Задает максимальный размер динамической таблицы для сжатия полей заголовка. По умолчанию: 4Kib.
  • maxSettings <number> Задает максимальное количество записей настроек в каждом кадре SETTINGS. Минимально допустимое значение — 1. По умолчанию: 32.
  • maxSessionMemory<number> Задает максимальный объем памяти, который разрешено использовать Http2Session. Значение указывается в мегабайтах; например, 1 соответствует 1 мегабайту. Минимально допустимое значение — 1. Это ограничение основано на кредитах: уже существующие экземпляры Http2Stream могут привести к превышению этого ограничения, однако новые экземпляры Http2Stream будут отклоняться, пока ограничение превышено. В текущее ограничение включаются текущее количество сеансов Http2Stream, текущее использование памяти таблицами сжатия заголовков, данные, ожидающие отправки, а также неподтвержденные кадры PING и SETTINGS. По умолчанию: 10.
  • maxHeaderListPairs <number> Задает максимальное количество записей заголовков. Это аналогично server.maxHeadersCount или request.maxHeadersCount в модуле node:http. Минимальное значение — 1. По умолчанию: 128.
  • maxOriginSetSize <number> Задает максимальное количество уникальных origin, которые сервер может отправить в кадрах ORIGIN. По умолчанию: 128.
  • maxOutstandingPings <number> Задает максимальное количество ожидающих подтверждения ping-запросов. По умолчанию: 10.
  • maxReservedRemoteStreams <number> Задает максимальное количество зарезервированных потоков push, которые клиент может принимать одновременно. Когда текущее количество зарезервированных потоков push превысит это ограничение, новые потоки push, отправленные сервером, будут автоматически отклоняться. Минимально допустимое значение — 0. Максимально допустимое значение — 2³²-1. Отрицательное значение устанавливает для этого параметра максимально допустимое значение. По умолчанию: 200.
  • maxSendHeaderBlockLength <number> Задает максимально допустимый размер сериализованного сжатого блока заголовков. Попытки отправить заголовки, превышающие это ограничение, приведут к возникновению события 'frameError', а поток будет закрыт и уничтожен.
  • paddingStrategy <number> Стратегия определения объема заполнения для кадров HEADERS и DATA. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Возможны следующие значения:
    • http2.constants.PADDING_STRATEGY_NONE: заполнение не применяется.
    • http2.constants.PADDING_STRATEGY_MAX: применяется максимально возможное заполнение, определяемое внутренней реализацией.
    • http2.constants.PADDING_STRATEGY_ALIGNED: предпринимается попытка добавить достаточное заполнение, чтобы общая длина кадра, включая 9-байтовый заголовок, была кратна 8. Для каждого кадра максимальное допустимое количество байтов заполнения определяется текущим состоянием управления потоком и настройками. Если это максимальное значение меньше рассчитанного количества, необходимого для выравнивания, используется максимальное значение, и общая длина кадра не обязательно будет кратна 8 байтам.
  • peerMaxConcurrentStreams <number> Задает максимальное количество параллельных потоков для удаленного узла, как если бы был получен кадр SETTINGS. Это значение будет переопределено, если удаленный узел задаст собственное значение maxConcurrentStreams. По умолчанию: 100.
  • protocol <string> Протокол для подключения, если он не указан в authority. Возможные значения: 'http:' или 'https:'. По умолчанию: 'https:'
  • settings <HTTP/2 Settings Object> Начальные настройки, отправляемые удаленному узлу при подключении.
  • remoteCustomSettings <Array> Массив целочисленных значений определяет типы настроек, включаемые в свойство CustomSettings полученного объекта remoteSettings. Дополнительные сведения о допустимых типах настроек см. в свойстве CustomSettings объекта Http2Settings.
  • createConnection <Function> Необязательная функция обратного вызова, которая получает экземпляр URL, переданный в connect, и объект options, а затем возвращает любой поток Duplex, используемый в качестве подключения для этого сеанса.
  • ...options <Object> Можно указать любые параметры net.connect() или tls.connect().
  • unknownProtocolTimeout <number> Указывает тайм-аут в миллисекундах, в течение которого сервер должен ожидать после возникновения события 'unknownProtocol'. Если к этому моменту сокет не был уничтожен, сервер уничтожит его. По умолчанию: 10000.
  • strictFieldWhitespaceValidation <boolean> Если задано значение true, включается строгая проверка начальных и конечных пробелов в именах и значениях полей заголовков HTTP/2 в соответствии с RFC-9113. По умолчанию: true.
• listener <Function> Будет зарегистрирована как однократный обработчик события 'connect'.
• Возвращает: <ClientHttp2Session>

Возвращает экземпляр ClientHttp2Session.

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

/* Use the client */

client.close();

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

/* Use the client */

client.close();

http2.constants

Коды ошибок для RST_STREAM и GOAWAY

Событие 'timeout' возникает, если на сервере нет активности в течение заданного количества миллисекунд, установленного с помощью http2server.setTimeout().

http2.getDefaultSettings()

• Возвращает: <HTTP/2 Settings Object>

Возвращает объект, содержащий настройки по умолчанию для экземпляра Http2Session. При каждом вызове этот метод возвращает новый экземпляр объекта, поэтому возвращенные экземпляры можно безопасно изменять.

http2.getPackedSettings([settings])

• settings <HTTP/2 Settings Object>
• Возвращает: <Buffer>

Возвращает экземпляр Buffer, содержащий сериализованное представление указанных настроек HTTP/2 в соответствии со спецификацией HTTP/2. Он предназначен для использования с полем заголовка HTTP2-Settings.

import { getPackedSettings } from 'node:http2';

const packed = getPackedSettings({ enablePush: false });

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

const http2 = require('node:http2');

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

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

http2.getUnpackedSettings(buf)

• buf <Buffer> | <TypedArray> Упакованные настройки.
• Возвращает: <HTTP/2 Settings Object>

Возвращает объект настроек HTTP/2, содержащий десериализованные настройки из указанного Buffer, созданного с помощью http2.getPackedSettings().

http2.performServerHandshake(socket[, options])

• socket <stream.Duplex>
• options <Object> Можно указать любой параметр http2.createServer().
• Возвращает: <ServerHttp2Session>

Создает сеанс сервера HTTP/2 на основе существующего сокета.

http2.sensitiveHeaders

• Тип: <symbol>

Этот символ можно задать в качестве свойства объекта заголовков HTTP/2 со значением-массивом, чтобы указать список заголовков, считающихся конфиденциальными. Подробнее см. в разделе Конфиденциальные заголовки.

Объект заголовков

Заголовки представлены в виде собственных свойств объектов JavaScript. Ключи свойств при сериализации переводятся в нижний регистр. Значения свойств должны быть строками (если это не так, они будут приведены к строкам) или Array строк, чтобы передать более одного значения для одного поля заголовка.

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

stream.respond(headers);
jscopy

Объекты заголовков, передаваемые функциям обратного вызова, имеют прототип null. Это означает, что стандартные методы объектов JavaScript, такие как Object.prototype.toString() и Object.prototype.hasOwnProperty(), работать не будут.

Для входящих заголовков:

• Заголовок :status преобразуется в number.
• Дубликаты заголовков :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 или x-content-type-options отбрасываются.
• set-cookie всегда является массивом. Дубликаты добавляются в массив.
• Значения дублирующихся заголовков cookie объединяются с помощью «; ».
• Значения всех остальных заголовков объединяются с помощью «, ».

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

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

Необработанные заголовки

В некоторых API заголовки можно передавать или получать не только в виде объекта, но и в виде необработанного плоского массива, сохраняющего порядок и дублирующиеся ключи для соответствия формату передачи.

В этом формате ключи и значения находятся в одном списке. Это не список кортежей. Поэтому смещения с четными номерами соответствуют значениям ключей, а смещения с нечетными номерами — связанным с ними значениям. Дублирующиеся заголовки не объединяются, и каждая пара «ключ-значение» отображается отдельно.

Это может быть полезно, например, для прокси-серверов, где существующие заголовки нужно передавать в точности в том виде, в каком они были получены, или для оптимизации производительности, если заголовки уже доступны в необработанном формате.

const rawHeaders = [
  ':status',
  '404',
  'content-type',
  'text/plain',
];

stream.respond(rawHeaders);
jscopy

Конфиденциальные заголовки

Заголовки HTTP/2 можно пометить как конфиденциальные; это означает, что алгоритм сжатия заголовков HTTP/2 никогда не будет индексировать их. Это может иметь смысл для значений заголовков с низкой энтропией, которые могут представлять интерес для злоумышленника, например Cookie или Authorization. Для этого добавьте имя заголовка в свойство [http2.sensitiveHeaders] в виде массива:

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);
jscopy

Для некоторых заголовков, например Authorization и коротких заголовков Cookie, этот флаг устанавливается автоматически.

Это свойство также устанавливается для полученных заголовков. Оно содержит имена всех заголовков, помеченных как конфиденциальные, включая заголовки с автоматически установленной отметкой.

Для необработанных заголовков это свойство по-прежнему следует задавать у массива, например rawHeadersArray[http2.sensitiveHeaders] = ['cookie'], а не в виде отдельной пары ключ-значение внутри самого массива.

Объект настроек

API http2.getDefaultSettings(), http2.getPackedSettings(), http2.createServer(), http2.createSecureServer(), http2session.settings(), http2session.localSettings и http2session.remoteSettings либо возвращают объект, либо принимают его в качестве входных данных; этот объект определяет параметры конфигурации для объекта Http2Session. Эти объекты являются обычными объектами JavaScript, содержащими следующие свойства.

• headerTableSize <number> Задает максимальное количество байтов, используемых для сжатия заголовков. Минимально допустимое значение — 0. Максимально допустимое значение — 2³²-1. По умолчанию: 4096.
• enablePush <boolean> Указывает true, если потоки HTTP/2 Push разрешены для экземпляров Http2Session. По умолчанию: true.
• initialWindowSize <number> Задает начальный размер окна отправителя в байтах для управления потоком на уровне потока. Минимально допустимое значение — 0. Максимально допустимое значение — 2³²-1. По умолчанию: 65535.
• maxFrameSize <number> Задает размер полезной нагрузки самого большого кадра в байтах. Минимально допустимое значение — 16,384. Максимально допустимое значение — 2²⁴-1. По умолчанию: 16384.
• maxConcurrentStreams <number> Задает максимальное количество одновременных потоков, разрешенных для Http2Session. Значение по умолчанию отсутствует, что означает, по крайней мере теоретически, что в любой момент времени в Http2Session могут быть одновременно открыты 2³²-1 потока. Минимальное значение — 0. Максимально допустимое значение — 2³²-1. По умолчанию: 4294967295.
• maxHeaderListSize <number> Задает максимальный размер (несжатое количество октетов) принимаемого списка заголовков. Минимально допустимое значение — 0. Максимально допустимое значение — 2³²-1. По умолчанию: 65535.
• maxHeaderSize <number> Псевдоним для maxHeaderListSize.
• enableConnectProtocol<boolean> Указывает true, если необходимо включить «Расширенный протокол Connect», определенный в RFC 8441. Эта настройка имеет смысл только в том случае, если ее отправляет сервер. После включения настройки enableConnectProtocol для заданного Http2Session ее нельзя отключить. По умолчанию: false.
• customSettings <Object> Задает дополнительные настройки, которые пока не реализованы в node и базовых библиотеках. Ключ объекта определяет числовое значение типа настройки (как определено в реестре «HTTP/2 SETTINGS», созданном согласно [RFC 7540]), а значение — фактическое числовое значение настройки. Тип настройки должен быть целым числом в диапазоне от 1 до 2^16-1. Он не должен совпадать с типом настройки, уже обрабатываемым node, то есть в настоящее время должен быть больше 6, хотя это не является ошибкой. Значения должны быть беззнаковыми целыми числами в диапазоне от 0 до 2^32-1. В настоящее время поддерживается не более 10 пользовательских настроек. Это свойство поддерживается только при отправке SETTINGS или при получении значений настроек, указанных в параметрах remoteCustomSettings объекта сервера или клиента. Не смешивайте механизм customSettings для идентификатора настройки с интерфейсами для настроек, обрабатываемых нативно, на случай если настройка получит нативную поддержку в будущей версии node.

Все дополнительные свойства объекта настроек игнорируются.

Обработка ошибок

При использовании модуля node:http2 могут возникать несколько типов ошибок:

Ошибки проверки возникают, если передан неверный аргумент, параметр или значение настройки. О них всегда сообщается посредством синхронного throw.

Ошибки состояния возникают, если действие выполняется в неподходящий момент (например, если предпринимается попытка отправить данные по уже закрытому потоку). О них сообщается либо посредством синхронного throw, либо через событие 'error' объекта Http2Stream, Http2Session или сервера HTTP/2 — в зависимости от того, где и когда произошла ошибка.

Внутренние ошибки возникают при неожиданном сбое сеанса HTTP/2. О них сообщается через событие 'error' объекта Http2Session или сервера HTTP/2.

Ошибки протокола возникают при нарушении различных ограничений протокола HTTP/2. О них сообщается либо посредством синхронного throw, либо через событие 'error' объекта Http2Stream, Http2Session или сервера HTTP/2 — в зависимости от того, где и когда произошла ошибка.

Обработка недопустимых символов в именах и значениях заголовков

Реализация HTTP/2 обрабатывает недопустимые символы в именах и значениях HTTP-заголовков строже, чем реализация HTTP/1.

Имена полей заголовков нечувствительны к регистру и передаются по сети строго в виде строк в нижнем регистре. API Node.js позволяет задавать имена заголовков в смешанном регистре (например, Content-Type), но при передаче преобразует их в нижний регистр (например, content-type).

Имена полей заголовков должны содержать только один или несколько следующих символов ASCII: a-z, A-Z, 0-9, !, #, $, %, &, ', *, +, -, ., ^, _, ` (обратная кавычка), | и ~.

Использование недопустимых символов в имени поля HTTP-заголовка приведет к закрытию потока с сообщением об ошибке протокола.

К значениям полей заголовков предъявляются менее строгие требования, однако они не должны содержать символы новой строки или возврата каретки и должны состоять только из символов US-ASCII в соответствии с требованиями спецификации HTTP.

Потоки Push на стороне клиента

Чтобы получать потоки Push на стороне клиента, задайте обработчик события 'stream' объекта ClientHttp2Session:

import { connect } from 'node:http2';

const client = 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': '/' });

const http2 = require('node: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': '/' });

Поддержка метода CONNECT

Метод CONNECT используется для того, чтобы HTTP/2-сервер можно было применять в качестве прокси для TCP/IP-подключений.

Простой TCP-сервер:

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

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

Прокси HTTP/2 CONNECT:

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') {
    // Only accept CONNECT requests
    stream.close(NGHTTP2_REFUSED_STREAM);
    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 = 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);

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') {
    // Only accept CONNECT requests
    stream.close(NGHTTP2_REFUSED_STREAM);
    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.close(http2.constants.NGHTTP2_CONNECT_ERROR);
  });
});

proxy.listen(8001);

Клиент HTTP/2 CONNECT:

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

const client = 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: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(`The server says: ${data}`);
  client.close();
});
req.end('Jane');

const http2 = require('node: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: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(`The server says: ${data}`);
  client.close();
});
req.end('Jane');

Расширенный протокол CONNECT

RFC 8441 определяет расширение «Extended CONNECT Protocol» для HTTP/2, которое может использоваться для установления Http2Stream с помощью метода CONNECT в качестве туннеля для других протоколов связи (например, WebSockets).

Использование расширенного протокола CONNECT включается на HTTP/2-серверах с помощью настройки enableConnectProtocol:

import { createServer } from 'node:http2';
const settings = { enableConnectProtocol: true };
const server = createServer({ settings });

const http2 = require('node:http2');
const settings = { enableConnectProtocol: true };
const server = http2.createServer({ settings });

Получив от сервера кадр SETTINGS, указывающий на возможность использования расширенного CONNECT, клиент может отправлять запросы CONNECT, использующие псевдозаголовок HTTP/2 ':protocol':

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

const http2 = require('node:http2');
const client = http2.connect('http://localhost:8080');
client.on('remoteSettings', (settings) => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' });
    // ...
  }
});

API совместимости

API совместимости призвано обеспечить разработчикам при использовании HTTP/2 опыт, аналогичный работе с HTTP/1, и дать возможность разрабатывать приложения, поддерживающие и HTTP/1, и HTTP/2. Это API охватывает только публичный API HTTP/1. Однако многие модули используют внутренние методы или состояние, которые не поддерживаются, поскольку реализация полностью отличается.

В следующем примере создается HTTP/2-сервер с использованием API совместимости:

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

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

Чтобы создать смешанный сервер HTTPS и HTTP/2, см. раздел Согласование ALPN. Обновление незашифрованных HTTP/1-серверов не поддерживается.

API совместимости HTTP/2 состоит из Http2ServerRequest и Http2ServerResponse. Они обеспечивают совместимость API с HTTP/1, но не скрывают различия между протоколами. Например, текст состояния для кодов HTTP игнорируется.

Согласование ALPN

Согласование ALPN позволяет поддерживать HTTPS и HTTP/2 через один и тот же сокет. Объекты req и res могут относиться как к HTTP/1, так и к HTTP/2, поэтому приложение должно ограничиваться публичным API HTTP/1 и определять, можно ли использовать более расширенные возможности HTTP/2.

В следующем примере создается сервер, поддерживающий оба протокола:

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) {
  // Detects if it is an 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,
  }));
}

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) {
  // Detects if it is an 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,
  }));
}

Событие 'request' работает одинаково и в HTTPS, и в HTTP/2.

Класс: http2.Http2ServerRequest

• Наследует: <stream.Readable>

Объект Http2ServerRequest создается объектом http2.Server или http2.SecureServer и передается в качестве первого аргумента событию 'request'. Его можно использовать для доступа к состоянию запроса, заголовкам и данным.

Событие: 'aborted'

Событие 'aborted' возникает всякий раз, когда экземпляр Http2ServerRequest аварийно прерывается во время обмена данными.

Событие 'aborted' возникает только в том случае, если записывающая сторона Http2ServerRequest еще не завершена.

Событие: 'close'

Указывает, что базовый Http2Stream был закрыт. Как и 'end', это событие возникает только один раз для каждого ответа.

request.aborted

• Тип: <boolean>

Свойство request.aborted имеет значение true, если запрос был прерван.

request.authority

• Тип: <string>

Псевдозаголовок authority запроса. Поскольку HTTP/2 позволяет задавать в запросах либо :authority, либо host, это значение берется из req.headers[':authority'], если оно присутствует. В противном случае оно берется из req.headers['host'].

request.complete

• Тип: <boolean>

Свойство request.complete имеет значение true, если запрос завершен, прерван или уничтожен.

request.connection

• Тип: <net.Socket> | <tls.TLSSocket>

См. request.socket.

request.destroy([error])

• error <Error>

Вызывает destroy() для Http2Stream, получившего Http2ServerRequest. Если указан error, генерируется событие 'error', а error передается в качестве аргумента всем обработчикам этого события.

Ничего не делает, если поток уже уничтожен.

request.headers

• Тип: <Object>

Объект заголовков запроса/ответа.

Пары «ключ-значение» для имен и значений заголовков. Имена заголовков записываются в нижнем регистре.

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

См. Объект заголовков HTTP/2.

В HTTP/2 путь запроса, имя хоста, протокол и метод представлены специальными заголовками с префиксом в виде символа : (например, ':path'). Эти специальные заголовки включаются в объект request.headers. Следует соблюдать осторожность, чтобы случайно не изменить эти специальные заголовки, иначе могут возникнуть ошибки. Например, удаление всех заголовков запроса приведет к ошибкам:

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

request.httpVersion

• Тип: <string>

Для запроса к серверу — версия HTTP, отправленная клиентом. Для ответа клиента — версия HTTP подключенного сервера. Возвращает '2.0'.

Кроме того, message.httpVersionMajor — это первое целое число, а message.httpVersionMinor — второе.

request.method

• Тип: <string>

Метод запроса в виде строки. Только для чтения. Примеры: 'GET', 'DELETE'.

request.rawHeaders

• Тип: {Необработанные заголовки HTTP/2}

Список необработанных заголовков запроса/ответа точно в том виде, в каком они были получены.

// 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);
jscopy

request.rawTrailers

• Тип: <string[]>

Необработанные ключи и значения завершающих заголовков запроса/ответа точно в том виде, в каком они были получены. Заполняется только при событии 'end'.

request.scheme

• Тип: <string>

Псевдозаголовок scheme запроса, указывающий схему целевого URL.

request.setTimeout(msecs, callback)

• msecs <number>
• callback <Function>
• Возвращает: <http2.Http2ServerRequest>

Устанавливает время ожидания для Http2Stream равным msecs. Если передана функция обратного вызова, она добавляется в качестве обработчика события 'timeout' объекта ответа.

Если обработчик события 'timeout' не добавлен для запроса, ответа или сервера, то Http2Stream уничтожаются по истечении времени ожидания. Если для событий 'timeout' запроса, ответа или сервера назначен обработчик, обработку сокетов с истекшим временем ожидания необходимо выполнять явно.

request.socket

• Тип: <net.Socket> | <tls.TLSSocket>

Возвращает объект Proxy, который действует как net.Socket (или tls.TLSSocket), но применяет геттеры, сеттеры и методы на основе логики HTTP/2.

Свойства destroyed, readable и writable будут получаться из объекта request.stream и устанавливаться в нем.

Методы destroy, emit, end, on и once будут вызываться для объекта request.stream.

Метод setTimeout будет вызываться для объекта request.stream.session.

Вызов pause, read, resume и write приведет к ошибке с кодом ERR_HTTP2_NO_SOCKET_MANIPULATION. Дополнительные сведения см. в разделе Http2Session и сокеты.

Все остальные операции будут напрямую перенаправляться сокету. При использовании TLS применяйте request.socket.getPeerCertificate() для получения сведений об аутентификации клиента.

request.stream

• Тип: <Http2Stream>

Объект Http2Stream, на основе которого создан запрос.

request.trailers

• Тип: <Object>

Объект завершающих заголовков запроса/ответа. Заполняется только при событии 'end'.

request.url

• Тип: <string>

Строка URL запроса. Она содержит только URL, присутствующий в фактическом HTTP-запросе. Если запрос имеет вид:

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

Тогда request.url будет иметь значение:

"/status?name=ryan"
jsoncopy

Для разбора URL на составляющие можно использовать new URL():

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

Класс: http2.Http2ServerResponse

• Наследует: <Stream>

Этот объект создается сервером HTTP автоматически, а не пользователем. Он передается в качестве второго параметра событию 'request'.

Событие: 'close'

Указывает, что базовый Http2Stream был прерван до вызова response.end() или до возможности сбросить данные.

Событие: 'finish'

Возникает после отправки ответа. Точнее, это событие генерируется, когда последний фрагмент заголовков и тела ответа передан мультиплексору HTTP/2 для отправки по сети. Оно не означает, что клиент уже что-либо получил.

После этого события для объекта ответа больше не генерируются события.

response.addTrailers(headers)

• headers <Object>

Этот метод добавляет к ответу завершающие HTTP-заголовки (заголовки в конце сообщения).

Попытка задать имя или значение поля заголовка, содержащее недопустимые символы, приведет к возникновению исключения TypeError.

response.appendHeader(name, value)

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

Добавляет одно значение заголовка в объект заголовков.

Если значение представляет собой массив, это равносильно многократному вызову данного метода.

Если для заголовка еще не было задано значений, это равносильно вызову response.setHeader().

Попытка задать имя или значение поля заголовка, содержащее недопустимые символы, приведет к возникновению исключения TypeError.

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

response.connection

• Тип: <net.Socket> | <tls.TLSSocket>

См. response.socket.

response.createPushResponse(headers, callback)

• headers <HTTP/2 Headers Object> Объект, описывающий заголовки
• callback <Function> Вызывается после завершения http2stream.pushStream(), при неудачной попытке создания отправленного потока Http2Stream, при отклонении этой попытки или если состояние Http2ServerRequest закрыто до вызова метода http2stream.pushStream()
  • err <Error>
  • res <http2.Http2ServerResponse> Вновь созданный объект Http2ServerResponse

Вызывает http2stream.pushStream() с заданными заголовками и в случае успеха оборачивает заданный Http2Stream в только что созданный Http2ServerResponse, передавая его в качестве параметра функции обратного вызова. При закрытии Http2ServerRequest функция обратного вызова вызывается с ошибкой ERR_HTTP2_INVALID_STREAM.

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Возвращает: <this>

Этот метод сообщает серверу, что все заголовки и тело ответа отправлены и сервер должен считать сообщение завершенным. Метод response.end() MUST вызываться для каждого ответа.

Если указан data, это равносильно вызову response.write(data, encoding), за которым следует response.end(callback).

Если указан callback, он будет вызван после завершения потока ответа.

response.finished

• Тип: <boolean>

Логическое значение, указывающее, завершен ли ответ. Изначально равно false. После выполнения response.end() значение будет равно true.

response.getHeader(name)

• name <string>
• Возвращает: <string>

Читает заголовок, который уже поставлен в очередь, но ещё не отправлен клиенту. Имя не чувствительно к регистру.

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

response.getHeaderNames()

• Возвращает: <string[]>

Возвращает массив, содержащий уникальные имена текущих исходящих заголовков. Все имена заголовков записаны в нижнем регистре.

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

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

response.getHeaders()

• Возвращает: <Object>

Возвращает поверхностную копию текущих исходящих заголовков. Поскольку используется поверхностная копия, значения массивов можно изменять без дополнительных вызовов различных методов модуля http, связанных с заголовками. Ключами возвращаемого объекта являются имена заголовков, а значениями — соответствующие значения заголовков. Все имена заголовков записаны в нижнем регистре.

Объект, возвращаемый методом response.getHeaders(), не наследует прототип от JavaScript Object. Это означает, что стандартные методы Object, такие как obj.toString(), obj.hasOwnProperty() и другие, не определены и не будут работать.

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

response.hasHeader(name)

• name <string>
• Возвращает: <boolean>

Возвращает true, если заголовок с именем name в данный момент установлен в исходящих заголовках. Сравнение имён заголовков не чувствительно к регистру.

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

response.headersSent

• Тип: <boolean>

True, если заголовки отправлены, иначе false (только для чтения).

response.removeHeader(name)

• name <string>

Удаляет заголовок, поставленный в очередь для неявной отправки.

response.removeHeader('Content-Encoding');
jscopy

response.req

• Тип: <http2.Http2ServerRequest>

Ссылка на исходный объект HTTP2 request.

response.sendDate

• Тип: <boolean>

Если значение true, заголовок Date будет автоматически создан и отправлен в ответе, если его ещё нет среди заголовков. По умолчанию — true.

Отключать эту функцию следует только для тестирования; согласно HTTP, в ответах должен присутствовать заголовок Date.

response.setHeader(name, value)

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

Устанавливает одно значение заголовка для неявных заголовков. Если этот заголовок уже присутствует среди заголовков, которые предстоит отправить, его значение будет заменено. Используйте здесь массив строк, чтобы отправить несколько заголовков с одинаковым именем.

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

или

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

Попытка задать имя или значение поля заголовка, содержащее недопустимые символы, приведёт к выбрасыванию TypeError.

Заголовки, установленные с помощью response.setHeader(), будут объединены с заголовками, переданными в response.writeHead(); приоритет получат заголовки, переданные в response.writeHead().

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

response.setTimeout(msecs[, callback])

• msecs <number>
• callback <Function>
• Возвращает: <http2.Http2ServerResponse>

Устанавливает значение тайм-аута для Http2Stream равным msecs. Если передана функция обратного вызова, она добавляется в качестве обработчика события 'timeout' объекта ответа.

Если для запроса, ответа или сервера не добавлен обработчик события 'timeout', то Http2Stream уничтожаются по истечении времени ожидания. Если для событий 'timeout' запроса, ответа или сервера назначен обработчик, сокеты, для которых истекло время ожидания, необходимо обрабатывать явно.

response.socket

• Тип: <net.Socket> | <tls.TLSSocket>

Возвращает объект Proxy, который действует как net.Socket (или tls.TLSSocket), но применяет геттеры, сеттеры и методы, основанные на логике HTTP/2.

Свойства destroyed, readable и writable будут считываться из response.stream и устанавливаться в нём.

Методы destroy, emit, end, on и once будут вызываться для response.stream.

Метод setTimeout будет вызван для response.stream.session.

Вызов pause, read, resume и write приведёт к ошибке с кодом ERR_HTTP2_NO_SOCKET_MANIPULATION. Подробнее см. в разделе Http2Session и сокеты.

Все остальные взаимодействия будут перенаправлены непосредственно к сокету.

import { createServer } from 'node:http2';
const server = 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);

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

response.statusCode

• Тип: <number>

При использовании неявных заголовков (если явно не вызывается response.writeHead()) это свойство задаёт код состояния, который будет отправлен клиенту при отправке заголовков.

response.statusCode = 404;
jscopy

После отправки заголовка ответа клиенту это свойство указывает отправленный код состояния.

response.statusMessage

• Тип: <string>

Сообщение о состоянии не поддерживается HTTP/2 (RFC 7540 8.1.2.4). Возвращается пустая строка.

response.stream

• Тип: <Http2Stream>

Объект Http2Stream, лежащий в основе ответа.

response.writableEnded

• Тип: <boolean>

Равно true после вызова response.end(). Это свойство не указывает, были ли данные отправлены; для этого используйте writable.writableFinished.

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

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Возвращает: <boolean>

Если вызвать этот метод, не вызвав response.writeHead(), будет включён режим неявных заголовков и отправлены неявные заголовки.

Отправляет фрагмент тела ответа. Этот метод можно вызывать несколько раз, чтобы передавать последовательные части тела.

В модуле node:http тело ответа пропускается, если запрос является запросом HEAD. Аналогично, ответы 204 и 304 не должны содержать тело сообщения.

chunk может быть строкой или буфером. Если chunk — строка, второй параметр задаёт способ её кодирования в поток байтов. По умолчанию encoding имеет значение 'utf8'. Функция callback будет вызвана после отправки этого фрагмента данных.

Это необработанное тело HTTP, не связанное с кодированием тела на более высоком уровне, например многочастным кодированием.

При первом вызове response.write() буферизованные сведения заголовка и первый фрагмент тела будут отправлены клиенту. При втором вызове response.write() Node.js предполагает, что данные будут передаваться потоком, и отправляет новые данные отдельно. Иными словами, ответ буферизуется до первого фрагмента тела.

Возвращает true, если все данные успешно отправлены в буфер ядра. Возвращает false, если все данные или их часть поставлены в очередь в памяти пользователя. Событие 'drain' будет создано, когда буфер снова освободится.

response.writeContinue()

Отправляет клиенту статус 100 Continue, указывающий, что тело запроса следует отправить. См. событие 'checkContinue' для Http2Server и Http2SecureServer.

response.writeEarlyHints(hints)

• hints <Object>

Отправляет клиенту статус 103 Early Hints с заголовком Link, указывая, что пользовательский агент может предварительно загрузить связанные ресурсы или установить предварительное соединение с ними. hints — это объект, содержащий значения заголовков, которые нужно отправить вместе с сообщением ранних подсказок.

Пример

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

response.writeInformation(statusCode[, headers])

• statusCode <number> Информационный код состояния HTTP 1xx, от 100 до 199 включительно, кроме 101 (переключение протоколов), которое не допускается в HTTP/2.
• headers <Object> Необязательный объект заголовков, отправляемых вместе с информационным ответом.

Отправляет произвольный информационный ответ HTTP 1xx, эквивалентный в HTTP/2 кадру HEADERS, псевдозаголовок :status которого содержит код 1xx. Метод можно вызывать несколько раз до отправки окончательного ответа. После отправки заголовков окончательного ответа этот метод ничего не делает и возвращает false.

Это универсальный аналог методов response.writeContinue() и response.writeEarlyHints().

response.writeInformation(110, { 'X-Progress': '50%' });
jscopy

response.writeHead(statusCode[, statusMessage][, headers])

• statusCode <number>
• statusMessage <string>
• headers <HTTP/2 Headers Object>
• Возвращает: <http2.Http2ServerResponse>

Отправляет заголовок ответа на запрос. Код состояния — это трёхзначный код состояния HTTP, например 404. Последний аргумент, headers, содержит заголовки ответа.

Возвращает ссылку на Http2ServerResponse, позволяя объединять вызовы в цепочку.

Для совместимости с HTTP/1 в качестве второго аргумента можно передать человекочитаемый текст statusMessage. Однако, поскольку statusMessage не имеет значения в HTTP/2, этот аргумент не окажет никакого эффекта, а процесс выдаст предупреждение.

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

Content-Length указывается в байтах, а не в символах. Для определения количества байтов в заданной кодировке можно использовать API Buffer.byteLength(). В исходящих сообщениях Node.js не проверяет, равна ли длина Content-Length длине передаваемого тела. Однако при получении сообщений Node.js автоматически отклоняет их, если Content-Length не соответствует фактическому размеру полезной нагрузки.

Этот метод можно вызвать для сообщения не более одного раза до вызова response.end().

Если вызвать response.write() или response.end() до этого метода, будут вычислены неявные/изменяемые заголовки и вызвана эта функция.

Заголовки, установленные с помощью response.setHeader(), будут объединены с заголовками, переданными в response.writeHead(); приоритет получат заголовки, переданные в response.writeHead().

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

Попытка задать имя или значение поля заголовка, содержащее недопустимые символы, приведёт к выбрасыванию TypeError.

Сбор показателей производительности HTTP/2

API Performance Observer можно использовать для сбора основных показателей производительности каждого экземпляра Http2Session и Http2Stream.

import { PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((items) => {
  const entry = items.getEntries()[0];
  console.log(entry.entryType);  // prints 'http2'
  if (entry.name === 'Http2Session') {
    // Entry contains statistics about the Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Entry contains statistics about the Http2Stream
  }
});
obs.observe({ entryTypes: ['http2'] });

const { PerformanceObserver } = require('node:perf_hooks');

const obs = new PerformanceObserver((items) => {
  const entry = items.getEntries()[0];
  console.log(entry.entryType);  // prints 'http2'
  if (entry.name === 'Http2Session') {
    // Entry contains statistics about the Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Entry contains statistics about the Http2Stream
  }
});
obs.observe({ entryTypes: ['http2'] });

Свойство entryType объекта PerformanceEntry будет равно 'http2'.

Свойство name объекта PerformanceEntry будет равно либо 'Http2Stream', либо 'Http2Session'.

Если name равно Http2Stream, PerformanceEntry будет содержать следующие дополнительные свойства:

• bytesRead <number> Количество байтов кадров DATA, полученных для этого Http2Stream.
• bytesWritten <number> Количество байтов кадров DATA, отправленных для этого Http2Stream.
• id <number> Идентификатор связанного Http2Stream
• timeToFirstByte <number> Количество миллисекунд между PerformanceEntry startTime и получением первого кадра DATA.
• timeToFirstByteSent <number> Количество миллисекунд между PerformanceEntry startTime и отправкой первого кадра DATA.
• timeToFirstHeader <number> Количество миллисекунд между PerformanceEntry startTime и получением первого заголовка.

Если name равно Http2Session, PerformanceEntry будет содержать следующие дополнительные свойства:

• bytesRead <number> Количество байтов, полученных для этого Http2Session.
• bytesWritten <number> Количество байтов, отправленных для этого Http2Session.
• framesReceived <number> Количество кадров HTTP/2, полученных Http2Session.
• framesSent <number> Количество кадров HTTP/2, отправленных Http2Session.
• maxConcurrentStreams <number> Максимальное количество потоков, одновременно открытых в течение всего времени существования Http2Session.
• pingRTT <number> Количество миллисекунд между отправкой кадра PING и получением подтверждения его приёма. Присутствует только в том случае, если кадр PING был отправлен через Http2Session.
• streamAverageDuration <number> Средняя длительность (в миллисекундах) для всех экземпляров Http2Stream.
• streamCount <number> Количество экземпляров Http2Stream, обработанных Http2Session.
• type <string> Либо 'server', либо 'client' для определения типа Http2Session.

Примечание об :authority и host

Для запросов HTTP/2 требуется либо псевдозаголовок :authority, либо заголовок host. При непосредственном создании запроса HTTP/2 предпочтительно использовать :authority, а при преобразовании из HTTP/1 (например, в прокси-серверах) — host.

API совместимости использует host, если :authority отсутствует. Подробнее см. в разделе request.authority. Однако если вы не используете API совместимости (или используете напрямую req.headers), вам необходимо самостоятельно реализовать поведение резервного варианта.