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

Возможна ситуация, когда 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!');
} copy

При использовании лексического 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!');
} copy

Основной API

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

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

Пример серверной стороны

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

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

Для генерации сертификата и ключа для этого примера выполните следующие действия:

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

Пример клиентской стороны

Следующий пример демонстрирует HTTP/2-клиент:

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

Класс: 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' срабатывает, когда возникает ошибка при обработке Http2Session.

Событие: 'frameError'

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

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

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

Событие: 'goaway'

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

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

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

Событие: 'localSettings'

• settings <Объект настроек HTTP/2> Копия полученного кадра SETTINGS.

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

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

session.settings({ enablePush: false });

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

Событие: 'ping'

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

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

Событие: 'remoteSettings'

• settings <Объект настроек HTTP/2> Копия полученного кадра SETTINGS.

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

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

Событие: 'stream'

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

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

const http2 = require('node:http2');
session.on('stream', (stream, headers, flags) => {
  const method = headers[':method'];
  const path = headers[':path'];
  // ...
  stream.respond({
    ':status': 200,
    'content-type': 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
}); copy

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

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

// Create an unencrypted HTTP/2 server
const server = http2.createServer();

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.on('error', (error) => console.error(error));
  stream.end('<h1>Hello World</h1>');
});

server.listen(8000); copy

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

Событие: 'timeout'

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

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

http2session.alpnProtocol

• <строка> | <неопределён>

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

http2session.close([callback])

• callback <Функция>

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

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

http2session.closed

• <логическое значение>

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

http2session.connecting

• <логическое значение>

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

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

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

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

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

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

http2session.destroyed

• <логическое значение>

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

http2session.encrypted

• <логическое значение> | <undefined>

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

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

• code <число> Код ошибки HTTP/2
• lastStreamID <число> Численный идентификатор последнего обработанного Http2Stream
• opaqueData <Буфер> | <Массив типов> | <DataView> Объект TypedArray или DataView, содержащий дополнительные данные, которые будут переданы в кадре GOAWAY.

Пересылает кадр GOAWAY подключённому узлу без закрытия сеанса Http2Session.

http2session.localSettings

• <Объект настроек HTTP/2>

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

http2session.originSet

• <массив строк> | <undefined>

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

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

http2session.pendingSettingsAck

• <логическое значение>

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

http2session.ping([payload, ]callback)

• payload <Буфер> | <Массив типов> | <DataView> Необязательная полезная нагрузка для пинга.
• callback <Функция>
• Возвращает: <логическое значение>

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

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

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

Обратный вызов будет вызван с тремя аргументами: аргументом ошибки, который будет null, если подтверждение PING было успешно получено, аргументом duration, который сообщает количество миллисекунд, прошедших с момента отправки пинга и получения подтверждения, и значением типа 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()}'`);
  }
}); copy

Если аргумент payload не указан, значение по умолчанию — 64-битное отметка времени (little endian), обозначающая начало PING.

http2session.ref()

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

http2session.remoteSettings

• <Объект настроек HTTP/2>

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

http2session.setLocalWindowSize(windowSize)

• windowSize <число>

Устанавливает размер окна локального узла. windowSize — это общий размер окна для установки, а не приращение.

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

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

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

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

http2session.setTimeout(msecs, callback)

• msecs <число>
• callback <Функция>

Используется для установки функции обратного вызова, которая вызывается, когда нет активности на 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 и Сокеты для получения дополнительной информации.

Метод setTimeout будет вызван на этом Http2Session.

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

http2session.state

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

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

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

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

• settings <Объект настроек HTTP/2>
• callback <Функция> Функция обратного вызова, которая вызывается, когда сессия подключена или сразу, если сессия уже подключена.
  • err <Ошибка> | <null>
  • settings <Объект настроек HTTP/2> Обновлённый объект settings.
  • duration <целое число>

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

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

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

http2session.type

• <число>

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

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

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

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

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

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

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

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

Объект URL или любой объект со свойством origin может быть передан как originOrStream, в этом случае будет использовано значение свойства 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 <строка> | <URL> | <Объект> Один или несколько URL-строк, переданных в качестве отдельных аргументов.

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

const http2 = require('node:http2');
const options = getSecureOptionsSomehow();
const server = http2.createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});
server.on('session', (session) => {
  session.origin('https://example.com', 'https://example.org');
}); copy

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

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

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

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

Класс: ClientHttp2Session

• Расширяет: <Http2Session>

Событие: 'altsvc'

• alt <строка>
• origin <строка>
• streamId <число>

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

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

Событие: 'origin'

• origins <массив строк>

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

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

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

clienthttp2session.request(headers[, options])

• headers <Объект заголовков HTTP/2>

• options <Объект>

  • endStream <логическое значение> true, если сторона Http2Stream должна быть закрыта изначально, например, при отправке запроса GET, который не должен ожидать тела полезной нагрузки.
  • exclusive <логическое значение> Когда true и parent идентифицируют родительский поток, созданный поток становится единственной прямой зависимостью родительского потока, а все другие существующие зависимые потоки становятся зависимыми от вновь созданного потока. По умолчанию: false.
  • parent <число> Указывает числовой идентификатор потока, от которого зависит вновь созданный поток.
  • weight <число> Указывает относительную зависимость потока по отношению к другим потокам с тем же parent. Значение является числом от 1 до 256 (включительно).
  • waitForTrailers <логическое значение> Когда true, Http2Stream сгенерирует событие 'wantTrailers' после отправки последнего кадра DATA.
  • signal <AbortSignal> Объект AbortSignal, который может быть использован для прерывания текущего запроса.

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

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

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

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

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

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

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

Если options.signal установлено с AbortSignal, а затем вызывается abort на соответствующем AbortController, запрос сгенерирует событие '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. Сторона Duplex экземпляра Writable используется для отправки данных подключенному peer, а сторона Readable используется для получения данных, отправленных подключенным peer.

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

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

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

Создание

На стороне сервера экземпляры ServerHttp2Stream создаются, когда:

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

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

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

Уничтожение

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

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

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

При уничтожении экземпляра 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' генерируется, когда возникает ошибка во время обработки Http2Stream.

Событие: 'frameError'

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

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

Событие: 'ready'

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

Событие: 'timeout'

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

Событие: 'trailers'

• headers <Объект заголовков HTTP/2> Объект, описывающий заголовки
• flags <число> Соответствующие числовые флаги

Событие 'trailers' генерируется, когда получен блок заголовков, связанных с полями заголовков-прицепов. Обработчик получает в качестве аргументов Объект заголовков HTTP/2 и флаги, связанные с заголовками.

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

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

Событие: 'wantTrailers'

Событие 'wantTrailers' генерируется, когда Http2Stream поместил в очередь последний кадр DATA для отправки в кадре, и Http2Stream готов к отправке заголовков-прицепов. При инициализации запроса или ответа параметр waitForTrailers должен быть установлен, чтобы это событие генерировалось.

http2stream.aborted

• <логическое значение>

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

http2stream.bufferSize

• <число>

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

http2stream.close(code[, callback])

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

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

http2stream.closed

• <логическое значение>

Устанавливается в true, если экземпляр Http2Stream был закрыт.

http2stream.destroyed

• <логическое значение>

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

http2stream.endAfterHeaders

• <логическое значение>

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

http2stream.id

• <число> | <неопределено>

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

http2stream.pending

• <логическое значение>

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

http2stream.priority(options)

• options <Объект>
  • exclusive <логическое значение> Когда true и parent идентифицируют родительский поток, этот поток становится единственной непосредственной зависимостью родительского потока, а все другие существующие зависимости становятся зависимыми от этого потока. По умолчанию: false.
  • parent <число> Указывает числовой идентификатор потока, от которого зависит этот поток.
  • weight <число> Указывает относительную зависимость потока по отношению к другим потокам с тем же parent. Значение является числом от 1 до 256 (включительно).
  • silent <логическое значение> Если true, изменяет приоритет локально без отправки кадра PRIORITY подключенному узлу.

Обновляет приоритет для этого экземпляра Http2Stream.

http2stream.rstCode

• <число>

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

http2stream.sentHeaders

• <Объект заголовков HTTP/2>

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

http2stream.sentInfoHeaders

• <Объект заголовков HTTP/2[]>

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

http2stream.sentTrailers

• <Объект заголовков HTTP/2>

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

http2stream.session

• <Http2Session>

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

http2stream.setTimeout(msecs, callback)

• msecs <число>
• callback <Функция>

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

http2stream.state

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

• <Объект>
  • localWindowSize <число> Количество байтов, которые подключённый узел может отправить для этого Http2Stream, не получив WINDOW_UPDATE.
  • state <число> Флаг, указывающий на текущее состояние низкого уровня Http2Stream, определённый nghttp2.
  • localClose <число> 1, если этот Http2Stream был закрыт локально.
  • remoteClose <число> 1, если этот Http2Stream был закрыт удалённо.
  • sumDependencyWeight <число> Суммарный вес всех экземпляров Http2Stream, которые зависят от этого Http2Stream, как указано с использованием фреймов PRIORITY.
  • weight <число> Вес приоритета этого Http2Stream.

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

http2stream.sendTrailers(headers)

• headers <Объект заголовков HTTP/2>

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

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

Спецификация 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>
• flags <число>

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

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

Событие: 'push'

• headers <Объект заголовков HTTP/2>
• flags <число>

Событие 'push' генерируется, когда принимаются заголовки ответа для потока Server Push. Обратный вызов слушателя получает Объект заголовков HTTP/2 и флаги, связанные с заголовками.

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

Событие: 'response'

• headers <Объект заголовков HTTP/2>
• flags <число>

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

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

Класс: ServerHttp2Stream

• Расширяет: <Http2Stream>

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

http2stream.additionalHeaders(headers)

• headers <Объект заголовков HTTP/2>

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

http2stream.headersSent

• <логическое>

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

http2stream.pushAllowed

• <логическое>

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

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

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

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

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

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

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

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

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

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

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

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

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

http2stream.respondWithFD(fd[, headers[, options]])

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

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

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

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

Необязательная функция 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.

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

http2stream.respondWithFile(path[, headers[, options]])

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

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

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

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

Если при попытке чтения данных файла произойдет ошибка, Http2Stream будет закрыт с помощью кадра RST_STREAM с использованием стандартного кода INTERNAL_ERROR. Если определен обратный вызов 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 });
}); copy

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

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

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

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

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

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

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

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

Класс: 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> Объект, описывающий заголовки
• flags <число> Соответствующий числовой флаг
• rawHeaders <Массив> Массив, содержащий исходные имена заголовков, после которых следуют их соответствующие значения.

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

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

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

Событие: 'timeout'

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

server.close([callback])

• callback <Функция>

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

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

server[Symbol.asyncDispose]()

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

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

• msecs <число> По умолчанию: 0 (без таймаута)
• callback <Функция>
• Возвращает: <Http2Server>

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

Указанный обратный вызов регистрируется как слушатель события 'timeout'.

В случае, если callback не является функцией, будет выброшено новое исключение ERR_INVALID_ARG_TYPE.

server.timeout

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

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

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

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

server.updateSettings([settings])

• settings <Объект настроек HTTP/2>

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

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

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

Класс: 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' генерируется, когда событие 'error' генерируется объектом Http2Session, связанным с Http2SecureServer.

Событие: 'stream'

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

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

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

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

Событие: '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 secure server и устанавливает функцию обратного вызова, которая вызывается, когда на Http2SecureServer нет активности после msecs миллисекунд.

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

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

server.timeout

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

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

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

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

server.updateSettings([settings])

• settings <HTTP/2 Settings Object>

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

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

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

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

• options <Объект>
  • maxDeflateDynamicTableSize <число> Устанавливает максимальный размер динамической таблицы для сжатия заголовков. По умолчанию: 4Kib.
  • maxSettings <число> Устанавливает максимальное количество записей настроек на кадр SETTINGS. Минимальное допустимое значение — 1. По умолчанию: 32.
  • maxSessionMemory<число> Устанавливает максимальную память, которую может использовать Http2Session. Значение выражается в мегабайтах, например, 1 равно 1 мегабайту. Минимальное допустимое значение — 1. Это ограничение на кредит, существующие Http2Stream могут привести к превышению этого предела, но новые экземпляры Http2Stream будут отклоняться, пока этот предел превышен. Текущее количество сессий Http2Stream, текущее использование памяти таблицами сжатия заголовков, текущие данные, ожидающие отправки, а также неоповещённые кадры PING и SETTINGS учитываются в текущем пределе. По умолчанию: 10.
  • maxHeaderListPairs <число> Устанавливает максимальное количество записей заголовков. Это аналогично server.maxHeadersCount или request.maxHeadersCount в модуле node:http. Минимальное значение — 4. По умолчанию: 128.
  • maxOutstandingPings <число> Устанавливает максимальное количество незавершенных, неоповещённых пингов. По умолчанию: 10.
  • maxSendHeaderBlockLength <число> Устанавливает максимальный разрешенный размер сериализованного, сжатого блока заголовков. Попытки отправить заголовки, превышающие этот предел, приведут к тому, что будет выброшено событие 'frameError', и поток будет закрыт и уничтожен. Хотя это устанавливает максимальный разрешенный размер для всего блока заголовков, nghttp2 (внутренняя библиотека http2) имеет ограничение в 65536 для каждой декомпрессированной пары ключ/значение.
  • paddingStrategy <число> Стратегия определения количества заполнения для кадров 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 <число> Устанавливает максимальное количество одновременных потоков для удаленного узла, как если бы был получен кадр SETTINGS. Будет переопределено, если удаленный узел установит собственное значение для maxConcurrentStreams. По умолчанию: 100.
  • maxSessionInvalidFrames <целое число> Устанавливает максимальное количество недопустимых кадров, которые будут терпеть, прежде чем сессия будет закрыта. По умолчанию: 1000.
  • maxSessionRejectedStreams <целое число> Устанавливает максимальное количество отклоненных при создании потоков, которые будут терпеть, прежде чем сессия будет закрыта. Каждое отклонение связано с ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна сказать узлу не открывать больше потоков, поэтому продолжение открытия потоков считается признаком некорректного узла. По умолчанию: 100.
  • settings <Объект настроек HTTP/2> Начальные настройки для отправки удалённому узлу при подключении.
  • remoteCustomSettings <Массив> Массив целочисленных значений определяет типы настроек, которые включены в свойство CustomSettings полученных удалённых настроек. Для получения дополнительной информации о разрешенных типах настроек см. свойство CustomSettings объекта Http2Settings.
  • ...: Любой параметр net.createServer() может быть предоставлен.

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

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

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

http2.createSecureServer(options[, onRequestHandler])

• options <Объект>
  • 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> Устанавливает максимальное количество ожидающих, неподтвержденных пингов. По умолчанию: 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> Начальные настройки, которые будут отправлены удаленному узлу при подключении.
  • remoteCustomSettings <Массив> Массив целых значений определяет типы настроек, которые включены в свойство customSettings полученных удаленных настроек. Дополнительную информацию о разрешенных типах настроек см. в свойстве customSettings объекта Http2Settings.
  • ...: Любые параметры tls.createServer() могут быть предоставлены. Для серверов обычно требуются параметры идентификации (pfx или key/cert).
  • origins <массив строк> Массив строк-источников, которые необходимо отправить в кадре ORIGIN сразу после создания нового серверного Http2Session.
  • unknownProtocolTimeout <number> Указывает время ожидания в миллисекундах, которое должен ждать сервер, когда генерируется событие 'unknownProtocol'. Если сокет не был уничтожен к этому времени, сервер уничтожит его. По умолчанию: 10000.
• onRequestHandler <Функция> См. API совместимости
• Возвращает: <Http2SecureServer>

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

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

http2.connect(authority[, options][, listener])

• authority <строка> | <URL> Дистанционный сервер HTTP/2 для подключения. Он должен быть представлен в виде минимального, валидного URL с префиксом http:// или https://, именем хоста и номером порта (если используется нестандартный порт). Данные userinfo (идентификатор пользователя и пароль), путь, строка запроса и фрагмент в URL будут проигнорированы.
• options <Объект>
  • maxDeflateDynamicTableSize <число> Устанавливает максимальный размер динамической таблицы для сжатия заголовков. По умолчанию: 4Kib.
  • maxSettings <число> Устанавливает максимальное количество записей настроек на фрейм SETTINGS. Минимальное значение равно 1. По умолчанию: 32.
  • maxSessionMemory<число> Устанавливает максимальный объём памяти, который может использовать Http2Session. Значение выражается в мегабайтах, например, 1 равно 1 мегабайту. Минимальное разрешённое значение — 1. Это лимит, основанный на квоте; существующие Http2Stream могут привести к превышению этого лимита, но новые экземпляры Http2Stream будут отклонены, пока лимит не будет превышен. Текущее количество Http2Stream сессий, текущее использование памяти таблицами сжатия заголовков, текущие данные, ожидающие отправки, и неподтверждённые PING и SETTINGS фреймы учитываются в текущем лимите. По умолчанию: 10.
  • maxHeaderListPairs <число> Устанавливает максимальное количество записей заголовков. Аналогично server.maxHeadersCount или request.maxHeadersCount в модуле node:http. Минимальное значение равно 1. По умолчанию: 128.
  • maxOutstandingPings <число> Устанавливает максимальное количество незавершенных, неподтвержденных запросов ping. По умолчанию: 10.
  • maxReservedRemoteStreams <число> Устанавливает максимальное количество зарезервированных push-потоков, которые клиент примет в любой момент. После превышения текущего количества зарезервированных push-потоков порогом, новые push-потоки, отправленные сервером, будут автоматически отклонены. Минимальное разрешённое значение — 0. Максимальное разрешённое значение — 2³²-1. Отрицательное значение устанавливает этот параметр в максимальное разрешённое значение. По умолчанию: 200.
  • maxSendHeaderBlockLength <число> Устанавливает максимальный разрешённый размер сериализованного, сжатого блока заголовков. Попытки отправки заголовков, превышающих этот лимит, приведут к событию 'frameError' и закрытию и уничтожению потока.
  • paddingStrategy <число> Стратегия определения количества заполнения для 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 <число> Устанавливает максимальное количество одновременных потоков для удаленного узла, как если бы был получен фрейм SETTINGS. Будет переопределено, если удалённый узел установит собственное значение для maxConcurrentStreams. По умолчанию: 100.
  • protocol <строка> Протокол подключения, если не указан в authority. Значение может быть либо 'http:', либо 'https:'. По умолчанию: 'https:'
  • settings <Объект настроек HTTP/2> Начальные настройки, которые будут отправлены удалённому узлу при подключении.
  • remoteCustomSettings <Массив> Массив целых значений определяет типы настроек, которые включены в свойство CustomSettings полученных настроек удалённого узла. Дополнительную информацию о разрешённых типах настроек см. в свойстве CustomSettings объекта Http2Settings.
  • createConnection <Функция> Дополнительный обратный вызов, который получает экземпляр URL, переданный в connect, и объект options, и возвращает любой поток Duplex, который будет использоваться в качестве соединения для этой сессии.
  • ...: Любые опции net.connect() или tls.connect() могут быть предоставлены.
  • unknownProtocolTimeout <число> Устанавливает таймаут в миллисекундах, который сервер должен ждать, когда будет отправлено событие 'unknownProtocol'. Если сокет не был уничтожен к этому моменту, сервер уничтожит его. По умолчанию: 10000.
• listener <Функция> Будет зарегистрирована как однократный слушатель события 'connect'.
• Возвращает: <ClientHttp2Session>

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

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

/* Use the client */

client.close(); copy

http2.constants

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

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

http2.getDefaultSettings()

• Возвращает: <Объект настроек HTTP/2>

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

http2.getPackedSettings([settings])

• settings <Объект настроек HTTP/2>
• Возвращает: <Буфер>

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

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

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

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

http2.getUnpackedSettings(buf)

• buf <Буфер> | <Массив типов> Упакованные настройки.
• Возвращает: <Объект настроек HTTP/2>

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

http2.performServerHandshake(socket[, options])

• socket <stream.Duplex>
• options <Объект>
  • ...: Любой параметр http2.createServer() может быть предоставлен.
• Возвращает: <Сессия сервера HTTP/2>

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

http2.sensitiveHeaders

• <символ>

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

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

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

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

stream.respond(headers); copy

Объекты заголовков, переданные функциям обратного вызова, будут иметь прототип 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 значения объединяются с помощью '; '.
• Для всех остальных заголовков значения объединяются с помощью ', '.

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

Чувствительные заголовки

Заголовки HTTP2 могут быть помечены как чувствительные, что означает, что алгоритм сжатия заголовков 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); copy

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

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

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

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

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

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

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

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

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

Потоки push на клиенте

Для получения потоков push на клиенте задайте обработчик события 'stream' на ClientHttp2Session:

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

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

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

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

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

HTTP/2 CONNECT-прокси:

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

HTTP/2 CONNECT-клиент:

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

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

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

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

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

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

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

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

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

Следующий пример создает сервер HTTP/2, используя API совместимости:

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

Для создания смешанного сервера HTTPS и HTTP/2, обратитесь к разделу Переговоры ALPN. Обновление с серверов HTTP/1 без TLS не поддерживается.

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.

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

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

Событие '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>

Псевдополе заголовка авторитета запроса. Поскольку 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); copy

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

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

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

request.httpVersion

• <string>

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

Также message.httpVersionMajor — первое целое число, а message.httpVersionMinor — второе.

request.method

• <string>

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

request.rawHeaders

• <string[]>

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

Ключи и значения находятся в одном списке. Это не список кортежей. Поэтому чётные индексы — ключи, а нечётные — соответствующие значения.

Имена заголовков не переводятся в нижний регистр, и дубликаты не объединяются.

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

request.rawTrailers

• <string[]>

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

request.scheme

• <string>

Псевдополе заголовка схемы запроса, указывающее на часть схемы целевого 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

• <Объект>

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

request.url

• <строка>

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

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

Тогда request.url будет:

'/status?name=ryan' copy

Для разбора 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: ''
} copy

Класс: http2.Http2ServerResponse

• Расширяет: <Поток>

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

Событие: 'close'

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

Событие: 'finish'

Выполняется, когда ответ был отправлен. Более точно, это событие выполняется, когда последний сегмент заголовков и тела ответа передаётся в HTTP/2 для передачи по сети. Это не подразумевает, что клиент что-либо получил.

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

response.addTrailers(headers)

• headers <Объект>

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

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

response.appendHeader(name, value)

• name <строка>
• value <строка> | <массив строк>

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

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

Если для заголовка не было предыдущих значений, это эквивалентно вызову 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');
}); copy

response.connection

• <net.Сокет> | <tls.TLSСокет>

См. response.socket.

response.createPushResponse(headers, callback)

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

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

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

• data <строка> | <Буфер> | <Uint8Массив>
• encoding <строка>
• callback <Функция>
• Возвращает: <this>

Этот метод сигнализирует серверу, что все заголовки и тело ответа отправлены; сервер должен считать это сообщение полным. Метод response.end() ДОЛЖЕН быть вызван для каждого ответа.

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

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

response.finished

• <логическое значение>

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

response.getHeader(name)

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

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

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

response.getHeaderNames()

• Возвращает: <массив строк>

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

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

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

response.getHeaders()

• Возвращает: <Объект>

Возвращает поверхностную копию текущих исходящих заголовков. Так как используется поверхностная копия, массивы значений могут быть изменены без дополнительных вызовов различных методов модуля 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'] } copy

response.hasHeader(name)

• name <строка>
• Возвращает: <логическое значение>

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

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

response.headersSent

• <boolean>

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

response.removeHeader(name)

• name <string>

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

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

response.req

• <http2.Http2ServerRequest>

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

response.sendDate

• <boolean>

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

Это следует отключать только для тестирования; HTTP требует заголовка Date в ответах.

response.setHeader(name, value)

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

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

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

или

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

Попытка установить имя или значение поля заголовка, содержащие недопустимые символы, приведёт к тому, что будет выброшен 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');
}); copy

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 и Сокеты.

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

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

response.statusCode

• <number>

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

response.statusCode = 404; copy

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

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

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

• statusCode <число>
• statusMessage <строка>
• headers <Объект> | <Массив>
• Возвращает: <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',
}); copy

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

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

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

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

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

Свойство entryType экземпляра PerformanceEntry будет равно 'http2'.

Свойство name экземпляра PerformanceEntry будет равно либо 'Http2Stream', либо 'Http2Session'.

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

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

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

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

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

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

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