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

Возможна ситуация, когда 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') зарегистрирован до попытки загрузки модуля (например, с помощью модуля preload).

При использовании 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 совместимости) — да.

http2 Основной API гораздо более симметричен между клиентом и сервером, чем http API. Например, большинство событий, таких как '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> 8-байтовое полезное содержимое кадра PING

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

Событие: 'remoteSettings'

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

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

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

Событие: 'stream'

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

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

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

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

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

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

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

server.listen(8000); copy

Хотя потоки HTTP/2 и сокеты сети не находятся в соответствии 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 если Http2Session разрушается из-за ошибки.
• code <число> Код ошибки HTTP/2 для отправки в последнем кадре GOAWAY . Если не указано и error не является неопределённым, значение по умолчанию INTERNAL_ERROR, иначе по умолчанию NO_ERROR.

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

После уничтожения Http2Session выведет событие 'close'. Если error не неопределённо, событие '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-битное отметка времени (маленький порядок байтов), которая отмечает начало 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('connect', (session) => {

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

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.setTimeout()) для этого Http2Stream не поступало активности. Его обработчик не ожидает никаких аргументов.

Событие: 'trailers'

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

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

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

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

Событие: 'wantTrailers'

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

http2stream.aborted

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

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

http2stream.bufferSize

• <число>

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

http2stream.close(code[, callback])

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

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

http2stream.closed

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

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

http2stream.destroyed

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

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

http2stream.endAfterHeaders

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

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

http2stream.id

• <число> | <undefined>

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

http2stream.pending

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

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

http2stream.priority(options)

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

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

http2stream.rstCode

• <число>

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

http2stream.sentHeaders

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

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

http2stream.sentInfoHeaders

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

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

http2stream.sentTrailers

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

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

http2stream.session

• <Http2Session>

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

http2stream.setTimeout(msecs, callback)

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

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

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

http2stream.state

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

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

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

http2stream.sendTrailers(headers)

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

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

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond(undefined, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' });
  });
  stream.end('Hello World');
}); copy

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

Класс: ClientHttp2Stream

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

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

Событие: 'continue'

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

Событие: 'headers'

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

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

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

Событие: 'push'

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

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

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

Событие: 'response'

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

Событие 'response' генерируется при получении кадра ответа HEADERS для этого потока от подключённого HTTP/2 сервера. Обработчик вызывается с двумя аргументами: объектом, содержащим полученный Объект заголовков 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 <number> Указывает числовой идентификатор потока, от которого зависит вновь созданный поток.
• callback <Функция> Обратный вызов, который вызывается один раз после того, как поток отправки был инициирован.
  • err <Ошибка>
  • pushStream <ServerHttp2Stream> Возвращаемый pushStream объект.
  • headers <Объект заголовков HTTP/2> Объект заголовков, с которым был инициирован pushStream.

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

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

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

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

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

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

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

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

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
  stream.end('some data');
}); copy

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

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

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

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

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

const server = http2.createServer();
server.on('stream', (stream) => {
  const fd = fs.openSync('/some/file', 'r');

  const stat = fs.fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers);
  stream.on('close', () => fs.closeSync(fd));
}); copy

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

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

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

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

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

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

const server = http2.createServer();
server.on('stream', (stream) => {
  const fd = fs.openSync('/some/file', 'r');

  const stat = fs.fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });

  stream.on('close', () => fs.closeSync(fd));
}); copy

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

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

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

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

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

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

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

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString();
  }

  function onError(err) {
    // stream.respond() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.error(err);
    }
    stream.end();
  }

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

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

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

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

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

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

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

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

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
}); copy

Класс: Http2Server

• Расширяет: <net.Server>

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

Событие: 'checkContinue'

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

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

Обработка этого события включает вызов response.writeContinue(), если клиент должен продолжить отправку тела запроса, или генерацию соответствующего HTTP-ответа (например, 400 Bad Request), если клиент не должен продолжать отправку тела запроса.

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

Событие: 'connection'

• socket <stream.Duplex>

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

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

Событие: 'request'

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

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

Событие: 'session'

• session <ServerHttp2Session>

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

Событие: 'sessionError'

• error <Error>
• session <ServerHttp2Session>

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

Событие: 'stream'

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

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

См. также событие Http2Session '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.setTimeout([msecs][, callback])

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

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

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

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

server.timeout

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

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

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

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

server.updateSettings([settings])

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

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

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

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

Класс: Http2SecureServer

• Расширяет: <tls.Server>

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

Событие: 'checkContinue'

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

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

Обработка этого события включает вызов response.writeContinue(), если клиент должен продолжить отправку тела запроса, или генерацию соответствующего HTTP-ответа (например, 400 Bad Request), если клиент не должен продолжать отправку тела запроса.

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

Событие: 'connection'

• socket <stream.Duplex>

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

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

Событие: 'request'

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

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

Событие: 'session'

• session <ServerHttp2Session>

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

Событие: 'sessionError'

• error <Error>
• session <ServerHttp2Session>

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

Событие: 'stream'

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

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

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

const http2 = require('node:http2');
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = http2.constants;

const options = getOptionsSomehow();

const server = http2.createSecureServer(options);
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
}); copy

Событие: 'timeout'

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

Событие: 'unknownProtocol'

• socket <stream.Duplex>

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

server.close([callback])

• callback <Function>

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

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

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

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

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

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

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

server.timeout

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

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

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

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

server.updateSettings([settings])

• settings <HTTP/2 Settings Object>

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

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

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

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

• options <Объект>
  • maxDeflateDynamicTableSize <число> Устанавливает максимальный размер динамической таблицы для сжатия заголовков. По умолчанию: 4Kib.
  • maxSettings <число> Устанавливает максимальное количество записей настроек на один кадр SETTINGS. Минимальное значение 1. По умолчанию: 32.
  • maxSessionMemory<число> Устанавливает максимальный объём памяти, который разрешено использовать Http2Session. Значение выражено в мегабайтах, например, 1 равно 1 мегабайту. Минимальное значение 1. Это ограничение на основе кредитов; существующие Http2Stream могут привести к превышению этого предела, но новые экземпляры Http2Stream будут отклоняться, пока предел не будет превышен. Текущее количество Http2Stream сессий, текущее использование памяти таблицами сжатия заголовков, текущие данные в очереди на отправку и неподтверждённые PING и SETTINGS кадры учитываются в текущем лимите. По умолчанию: 10.
  • maxHeaderListPairs <число> Устанавливает максимальное количество записей заголовков. Аналогично server.maxHeadersCount или request.maxHeadersCount в модуле node:http. Минимальное значение 4. По умолчанию: 128.
  • maxOutstandingPings <число> Устанавливает максимальное количество открытых, но не подтверждённых пингов. По умолчанию: 10.
  • maxSendHeaderBlockLength <число> Устанавливает максимальный разрешённый размер сериализованного, сжатого блока заголовков. Попытки отправить заголовки, превышающие этот предел, приведут к тому, что будет выведено событие 'frameError' и поток будет закрыт и уничтожен. Хотя это устанавливает максимальный разрешённый размер всего блока заголовков, nghttp2 (внутренняя библиотека http2) имеет предел 65536 для каждой декомпрессированной пары ключ/значение.
  • paddingStrategy <число> Стратегия, используемая для определения количества заполнения для кадров HEADERS и DATA. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Значение может быть одним из:
    • http2.constants.PADDING_STRATEGY_NONE: Заполнение не применяется.
    • http2.constants.PADDING_STRATEGY_MAX: Применяется максимальное количество заполнения, определяемое внутренней реализацией.
    • http2.constants.PADDING_STRATEGY_ALIGNED: Попытка применить достаточное заполнение для обеспечения того, что общая длина кадра, включая 9-байтовый заголовок, является кратной 8. Для каждого кадра существует максимальное разрешённое количество байтов заполнения, которое определяется текущим состоянием и настройками управления потоком. Если это максимальное значение меньше рассчитанного значения, необходимого для обеспечения выравнивания, используется максимальное значение, и общая длина кадра необязательно выравнивается по 8 байтам.
  • peerMaxConcurrentStreams <число> Устанавливает максимальное количество одновременных потоков для удалённого узла, как если бы был получен кадр SETTINGS. Будет перезаписано, если удалённый узел установит собственное значение для maxConcurrentStreams. По умолчанию: 100.
  • maxSessionInvalidFrames <целое> Устанавливает максимальное количество недопустимых кадров, которые будут терпимы, прежде чем сессия будет закрыта. По умолчанию: 1000.
  • maxSessionRejectedStreams <целое> Устанавливает максимальное количество отклоненных при создании потоков, которые будут терпимы, прежде чем сессия будет закрыта. Каждое отклонение связано с ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна сказать узлу не открывать больше потоков, поэтому дальнейшее открытие потоков рассматривается как признак некорректного поведения узла. По умолчанию: 100.
  • settings <Объект настроек HTTP/2> Начальные настройки для отправки удалённому узлу при подключении.
  • Http1IncomingMessage <http.Приходящее сообщение> Указывает класс IncomingMessage для использования при отказе к HTTP/1. Полезно для расширения исходного http.IncomingMessage. По умолчанию: http.IncomingMessage.
  • Http1ServerResponse <http.Ответ сервера> Указывает класс ServerResponse для использования при отказе к HTTP/1. Полезно для расширения исходного http.ServerResponse. По умолчанию: http.ServerResponse.
  • Http2ServerRequest <http2.Запрос сервера HTTP/2> Указывает класс для использования. Полезно для расширения исходного Http2ServerRequest. По умолчанию: Http2ServerRequest.
  • Http2ServerResponse <http2.Ответ сервера HTTP/2> Указывает класс для использования. Полезно для расширения исходного Http2ServerResponse. По умолчанию: Http2ServerResponse.
  • unknownProtocolTimeout <число> Указывает таймаут в миллисекундах, который сервер должен ждать, когда выводится 'unknownProtocol'. Если сокет не был уничтожен к этому времени, сервер уничтожит его. По умолчанию: 10000.
  • ...: Любой параметр net.createServer() может быть указан.
• onRequestHandler <Функция> См. API совместимости
• Возвращает: <Сервер HTTP/2>

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

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

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

// Create an unencrypted HTTP/2 server.
// Since there are no browsers known that support
// unencrypted HTTP/2, the use of `http2.createSecureServer()`
// is necessary when communicating with browser clients.
const server = http2.createServer();

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

server.listen(8000); copy

http2.createSecureServer(options[, onRequestHandler])

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

• <символ>

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

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

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

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

stream.respond(headers); copy

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

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

• Заголовок :status преобразуется в number.
• Дубликаты :status, :method, :authority, :scheme, :path, :protocol, age, authorization, access-control-allow-credentials, access-control-max-age, access-control-request-method, content-encoding, content-language, content-length, content-location, content-md5, content-range, content-type, date, dnt, etag, expires, from, host, if-match, if-modified-since, if-none-match, if-range, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, range, referer,retry-after, tk, upgrade-insecure-requests, user-agent или x-content-type-options игнорируются.
• set-cookie всегда является массивом. Дубликаты добавляются в массив.
• Для дублирующих заголовков cookie значения объединяются с помощью '; '.
• Для всех остальных заголовков значения объединяются с помощью ', '.

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

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

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

const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  'cookie': 'some-cookie',
  'other-sensitive-header': 'very secret data',
  [http2.sensitiveHeaders]: ['cookie', 'other-sensitive-header'],
};

stream.respond(headers); copy

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

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

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

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

• headerTableSize <число> Указывает максимальное количество байтов, используемых для сжатия заголовков. Минимально допустимое значение равно 0. Максимальное допустимое значение равно 2³²-1. По умолчанию: 4096.
• enablePush <логическое> Указывает true , если потоки HTTP/2 Push должны быть разрешены на экземплярах Http2Session. По умолчанию: true.
• initialWindowSize <число> Указывает начальный размер окна отправителя в байтах для управления потоком на уровне потока. Минимально допустимое значение равно 0. Максимальное допустимое значение равно 2³²-1. По умолчанию: 65535.
• maxFrameSize <число> Указывает размер максимальной полезной нагрузки кадра в байтах. Минимально допустимое значение равно 16 384. Максимальное допустимое значение равно 2²⁴-1. По умолчанию: 16384.
• maxConcurrentStreams <число> Указывает максимальное количество одновременных потоков, разрешенных на Http2Session. Нет значения по умолчанию, что подразумевает, по крайней мере теоретически, что 2³²-1 потоков могут быть открыты одновременно в Http2Session в любой момент времени. Минимальное значение равно 0. Максимальное допустимое значение равно 2³²-1. По умолчанию: 4294967295.
• maxHeaderListSize <число> Указывает максимальный размер (нескомпрессированные октеты) списка заголовков, который будет принят. Минимально допустимое значение равно 0. Максимальное допустимое значение равно 2³²-1. По умолчанию: 65535.
• maxHeaderSize <число> Псевдоним для maxHeaderListSize.
• enableConnectProtocol<логическое> Указывает true , если расширенный протокол подключения, определенный в RFC 8441, должен быть включен. Это значение имеет смысл только в том случае, если оно отправлено сервером. После того, как настройка enableConnectProtocol была включена для данного Http2Session, её нельзя отключить. По умолчанию: false.

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

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

Существует несколько типов ошибок, которые могут возникнуть при использовании модуля 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, !, #, $, %, &, ', *, +, -, ., ^, _, ` (обратная ковычка), |, и ~.

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

Значения полей заголовков обрабатываются более лояльно, но не должны содержать символов новой строки или возврата каретки и должны быть ограничены символами 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 <Error>

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

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

request.headers

• <Object>

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

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

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

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

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

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

request.httpVersion

• <string>

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

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

request.method

• <string>

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

request.rawHeaders

• <string[]>

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

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

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

// Prints something like:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders); copy

request.rawTrailers

• <string[]>

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

request.scheme

• <string>

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

request.setTimeout(msecs, callback)

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

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

Если обработчик события 'timeout' не добавлен к запросу, ответу или серверу, то сокеты, превысившие лимит времени, уничтожаются. Если обработчик назначен для запроса, ответа или события '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.connection

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

См. response.socket.

response.createPushResponse(headers, callback)

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

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

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

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

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

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

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

response.finished

• <булево>

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

response.getHeader(name)

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

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

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

response.getHeaderNames()

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

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

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

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

response.getHeaders()

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

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

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

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

const headers = response.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } copy

response.hasHeader(name)

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

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

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

response.headersSent

• <булево>

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

response.removeHeader(name)

• name <строка>

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

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

response.req

• <http2.Запрос Http2Server>

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

response.sendDate

• <boolean>

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

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

response.setHeader(name, value)

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

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

response.setHeader('Content-Type', 'text/html; charset=utf-8'); 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', то сокеты, превысившие время ожидания, будут уничтожены. Если обработчик назначен для запроса, ответа или события 'timeout' сервера, сокеты, превысившие время ожидания, необходимо обработать явно.

response.socket

• <net.Socket> | <tls.TLSSocket>

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

Свойства destroyed, readable, и writable будут получены и установлены на объекте response.stream.

Методы destroy, emit, end, on и once будут вызваны на объекте response.stream.

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

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

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

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

response.statusCode

• <number>

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

response.statusCode = 404; copy

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

response.statusMessage

• <string>

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

response.stream

• <Http2Stream>

Объект Http2Stream, поддерживающий ответ.

response.writableEnded

• <boolean>

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

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

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

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

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

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

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

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

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

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

response.writeContinue()

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

response.writeEarlyHints(hints)

• hints <Object>

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

Пример

const earlyHintsLink = '</styles.css>; rel=preload; as=style';
response.writeEarlyHints({
  'link': earlyHintsLink,
});

const earlyHintsLinks = [
  '</styles.css>; rel=preload; as=style',
  '</scripts.js>; rel=preload; as=script',
];
response.writeEarlyHints({
  'link': earlyHintsLinks,
}); copy

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

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• Возвращает: <http2.Http2ServerResponse>

Отправляет заголовок ответа запросу. Код состояния — это 3-значный код состояния 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 напрямую), вам нужно реализовать поведение обратной совместимости самостоятельно.