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

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 ядра значительно симметричнее между клиентом и сервером, чем 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>

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

Событие: 'frameError'

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

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

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

Событие: 'goaway'

• errorCode <число> Код ошибки HTTP/2, указанный в фрейме GOAWAY.
• lastStreamID <число> Идентификатор последнего успешно обработанного удалённым узлом потока (или 0, если идентификатор не указан).
• opaqueData <Buffer> Если в фрейме 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 <Buffer> Загрузка фрейма PING размером 8 байт

Событие '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-потоки и сетевые сокеты не находятся в соответствии 1:1, сетевая ошибка уничтожит каждый отдельный поток и должна обрабатываться на уровне потока, как показано выше.

Событие: 'timeout'

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

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

http2session.alpnProtocol

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

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

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, если сокет сессии 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

• <массив строк> | <неопределено>

Если 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() на базовом net.Socket экземпляра Http2Session.

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, и источник будет получен. Например, источник для HTTP-URL '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() для отправки завершающих заголовков партнёру.

Когда 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. Сторона Writable экземпляра Duplex используется для отправки данных подключенному партнёру, а сторона Readable используется для получения данных, отправленных подключённым партнёром.

По умолчанию кодировка символов текста для 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 уничтожаются, когда:

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

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

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

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

Событие: 'aborted'

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

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

Событие: 'close'

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

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

Событие: 'error'

• error <Ошибка>

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

Событие: 'frameError'

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

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

Событие: 'ready'

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

Событие: 'timeout'

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

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

Объект, содержащий исходящие фрагменты (trailers) отправленные для этого 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>

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

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 запрещает фрагментам (trailers) содержать псевдозаголовки 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. Функция обратного вызова получает объект, содержащий полученный Объект заголовков 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 <Серверный поток HTTP/2> Возвращённый 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() можно использовать для отправки заголовков хвостового фрейма peer.

Когда 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 объекта будет закрыт автоматически.

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 деталей данного дескриптора файла. Если функция statCheck предоставлена, метод http2stream.respondWithFD() выполнит вызов fs.fstat() для получения подробной информации о предоставленном дескрипторе файла.

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

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

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

Когда 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 объекта будет закрыт автоматически.

Опциональная функция 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. Например, условный запрос может проверить результаты статуса, чтобы определить, был ли файл изменён, и вернуть соответствующий ответ 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> Объект, описывающий заголовки
• 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 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 равно false), TLS-рукопожатие завершится неудачей, и безопасное соединение не будет установлено.

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

server.close([callback])

• callback <Функция>

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

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

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

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

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

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.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 <логическое> Входящие клиентские подключения, не поддерживающие HTTP/2, будут понижены до HTTP/1.x, если установлено значение true. См. событие 'unknownProtocol'. См. переговоры ALPN. По умолчанию: false.
  • 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', закрытию и уничтожению потока.
  • 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.
  • ...: Любые параметры tls.createServer() могут быть предоставлены. Для серверов обычно требуются параметры идентификации (pfx или key/cert).
  • origins <массив строк> Массив строк-источников для отправки в кадре ORIGIN сразу после создания нового серверного Http2Session.
  • unknownProtocolTimeout <число> Устанавливает таймаут в миллисекундах, в течение которого сервер ждёт при возникновении события '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://, именем хоста и номером IP-порта (если используется нестандартный порт). Информация о пользователе (идентификатор пользователя и пароль), путь, строка запроса и фрагмент в 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 <число> Устанавливает максимальное количество незавершенных, неподтверждённых пингов. По умолчанию: 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. Ключи свойств будут сериализованы в нижний регистр. Значения свойств должны быть строками (если это не так, они будут приведены к строкам) или Array строк (чтобы отправить более одного значения для каждого поля заголовка).

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 <число> Указывает максимальный размер (нескомпрессированные октеты) списка заголовков, который будет принят. Минимальное допустимое значение равно 0. Максимальное допустимое значение равно 2³²-1. По умолчанию: 65535.
• maxHeaderSize <число> Псевдоним для maxHeaderListSize.
• enableConnectProtocol<логическое> Указывает true, должен ли быть включен "Расширенный протокол подключения", определенный в 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. Обновление с не-TLS HTTP/1 серверов не поддерживается.

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

Переговоры ALPN

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

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

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 <Ошибка>

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

Не выполняет никаких действий, если поток уже был уничтожен.

request.headers

• <Объект>

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

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

// 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

• <строка>

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

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

request.method

• <строка>

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

request.rawHeaders

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

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

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

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

// 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

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

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

request.scheme

• <строка>

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

request.setTimeout(msecs, callback)

• msecs <число>
• callback <Функция>
• Возвращает: <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.Socket> | <tls.TLSSocket>

См. response.socket.

response.createPushResponse(headers, callback)

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

Вызов http2stream.pushStream() с заданными заголовками и обертка заданного Http2Stream в качестве параметра обратного вызова при успехе. При закрытии 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>

Истинно после вызова 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. Предпочитайте использовать :authority при непосредственном построении запроса HTTP/2 и host при преобразовании из HTTP/1 (например, в прокси-серверах).

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