HTTP/2

Исходный код: lib/http2.js

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

const http2 = require('http2');

Основной API

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

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

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

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

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

const server = http2.createSecureServer({
  key: fs.readFileSync('localhost-privkey.pem'),
  cert: fs.readFileSync('localhost-cert.pem')
});
server.on('error', (err) => console.error(err));

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

server.listen(8443);

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

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

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

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

const http2 = require('http2');
const fs = require('fs');
const client = http2.connect('https://localhost:8443', {
  ca: fs.readFileSync('localhost-cert.pem')
});
client.on('error', (err) => console.error(err));

const req = client.request({ ':path': '/' });

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`);
  }
});

req.setEncoding('utf8');
let data = '';
req.on('data', (chunk) => { data += chunk; });
req.on('end', () => {
  console.log(`\n${data}`);
  client.close();
});
req.end();

Класс: Http2Session

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

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

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

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

Http2Session и сокеты

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

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

После того, как Socket связан с Http2Session, код пользователя должен полагаться только на API объекта Http2Session.

Событие: 'close'

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

Событие: 'connect'

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

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

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

Событие: 'error'

• error <Error>

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

Событие: 'frameError'

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

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

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

Событие: 'goaway'

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

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

Объект Http2Session будет автоматически закрыт, когда будет вызвано событие 'goaway'.

Событие: 'localSettings'

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

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

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

session.settings({ enablePush: false });

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

Событие: 'ping'

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

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

Событие: 'remoteSettings'

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

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

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

Событие: 'stream'

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

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

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

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

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

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

Событие: 'timeout'

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

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

http2session.alpnProtocol

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

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

http2session.close([callback])

• callback <Функция>

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

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

http2session.closed

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

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

http2session.connecting

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

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

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

• error <Объект ошибки> если Error разрушается из-за ошибки.
• 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.

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

http2session.ref()

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

http2session.remoteSettings

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

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

http2session.setTimeout(msecs, callback)

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

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

http2session.socket

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

Возвращает объект 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.

• <Объект>
  • 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('http2');

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

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

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

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

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

Объект 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('http2');
const options = getSecureOptionsSomehow();
const server = http2.createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});
server.on('session', (session) => {
  session.origin('https://example.com', 'https://example.org');
});

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

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

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

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

Класс: ClientHttp2Session

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

Событие: 'altsvc'

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

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

const http2 = require('http2');
const client = http2.connect('https://example.org');

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt);
  console.log(origin);
  console.log(streamId);
});

Событие: 'origin'

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

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

const http2 = require('http2');
const client = http2.connect('https://example.org');

client.on('origin', (origins) => {
  for (let n = 0; n < origins.length; n++)
    console.log(origins[n]);
});

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

clienthttp2session.request(headers[, options])

• headers <HTTP/2 Headers Object>

• options <Объект>

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

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

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

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

const http2 = require('http2');
const clientSession = http2.connect('https://localhost:1234');
const {
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS
} = http2.constants;

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' });
req.on('response', (headers) => {
  console.log(headers[HTTP2_HEADER_STATUS]);
  req.on('data', (chunk) => { /* .. */ });
  req.on('end', () => { /* .. */ });
});

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

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

Псевдозаголовки :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
});

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

Создание

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

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

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

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

Удаление

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

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

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

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

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

Событие: 'aborted'

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

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

Событие: 'close'

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

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

Событие: 'error'

• error <Ошибка>

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

Событие: 'frameError'

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

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

Событие: 'ready'

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

Событие: 'timeout'

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

Событие: 'trailers'

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

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

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

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

Событие: 'wantTrailers'

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

http2stream.aborted

• <boolean>

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

http2stream.bufferSize

• <number>

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

http2stream.close(code[, callback])

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

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

http2stream.closed

• <boolean>

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

http2stream.destroyed

• <boolean>

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

http2stream.endAfterHeaders

• <boolean>

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

http2stream.id

• <number> | <undefined>

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

http2stream.pending

• <boolean>

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

http2stream.priority(options)

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

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

http2stream.rstCode

• <number>

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

http2stream.sentHeaders

• <HTTP/2 Headers Object>

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

http2stream.sentInfoHeaders

• <HTTP/2 Headers Object[]>

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

http2stream.sentTrailers

• <HTTP/2 Headers Object>

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

http2stream.session

• <Http2Session>

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

http2stream.setTimeout(msecs, callback)

• msecs <number>
• callback <Function>

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

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

http2stream.state

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

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

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

http2stream.sendTrailers(headers)

• headers <HTTP/2 Headers Object>

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

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

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

Класс: ClientHttp2Stream

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

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

Событие: 'continue'

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

Событие: 'headers'

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

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

Событие: 'push'

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

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

Событие: 'response'

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

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

Класс: ServerHttp2Stream

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

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

http2stream.additionalHeaders(headers)

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

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

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

const http2 = require('http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err;
    pushStream.respond({ ':status': 200 });
    pushStream.end('some pushed data');
  });
  stream.end('some data');
});

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительная функция options.statCheck может быть указана, чтобы дать коду пользователя возможность установить дополнительные заголовки содержимого на основе fs.Stat деталей заданного дескриптора файла. Если функция 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('http2');
const fs = require('fs');

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

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

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

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

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

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

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

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

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

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

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

  function onError(err) {
    if (err.code === 'ENOENT') {
      stream.respond({ ':status': 404 });
    } else {
      stream.respond({ ':status': 500 });
    }
    stream.end();
  }

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

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

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

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

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

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

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

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

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

Класс: Http2Server

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

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

Событие: 'checkContinue'

• request <http2.ЗапросHttp2Сервера>
• response <http2.ОтветHttp2Сервера>

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

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

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

Событие: 'connection'

• socket <stream.Дуплексный>

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

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

Событие: 'request'

• request <http2.ЗапросHttp2Сервера>
• response <http2.ОтветHttp2Сервера>

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

Событие: 'session'

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

Событие: 'sessionError'

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

Событие: 'stream'

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

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

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

Событие: 'timeout'

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

Чтобы изменить время ожидания по умолчанию, используйте флаг --http-server-default-timeout.

server.close([callback])

• callback <Функция>

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

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

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

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

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

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

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

Чтобы изменить время ожидания по умолчанию, используйте флаг --http-server-default-timeout.

Класс: Http2SecureServer

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

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

Событие: 'checkContinue'

• request <http2.ЗапросHttp2Сервера>
• response <http2.ОтветHttp2Сервера>

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

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

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

Событие: 'connection'

• socket <stream.Дуплексный>

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

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

Событие: 'request'

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

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

Событие: 'session'

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

Событие: 'sessionError'

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

Событие: 'stream'

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

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

const options = getOptionsSomehow();

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

Событие: 'timeout'

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

Событие: 'unknownProtocol'

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

server.close([callback])

• callback <Функция>

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

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

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

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

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

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

В случае отсутствия функции обратного вызова будет выброшено новое ошибку ERR_INVALID_CALLBACK.

http2.createServer(options[, onRequestHandler])

• options <Объект>
  • maxDeflateDynamicTableSize <число> Устанавливает максимальный размер динамической таблицы для сжатия заголовков. По умолчанию: 4Kib.
  • maxSettings <число> Устанавливает максимальное количество записей настроек на кадр SETTINGS. Минимальное допустимое значение — 1. По умолчанию: 32.
  • maxSessionMemory<число> Устанавливает максимальный объем памяти, который может использовать Http2Session. Значение выражается в мегабайтах, например, 1 равно 1 мегабайту. Минимальное допустимое значение — 1. Это лимит на основе кредитов; существующие Http2Stream могут привести к превышению этого лимита, но новые экземпляры Http2Stream будут отклоняться, пока этот лимит превышен. Текущее число сессий Http2Stream, текущее использование памяти таблицами сжатия заголовков, текущие данные, ожидающие отправки, и неподтвержденные кадры PING и SETTINGS учитываются в текущем лимите. По умолчанию: 10.
  • maxHeaderListPairs <число> Устанавливает максимальное количество заголовков. Аналогично http.Server#maxHeadersCount или http.ClientRequest#maxHeadersCount. Минимальное значение — 4. По умолчанию: 128.
  • maxOutstandingPings <число> Устанавливает максимальное количество незавершенных, неподтвержденных запросов ping. По умолчанию: 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_CALLBACK: Указывает, что для определения объема заполнения используется предоставленная пользователем функция обратного вызова options.selectPadding().
    • http2.constants.PADDING_STRATEGY_ALIGNED: Попытается применить достаточное заполнение для обеспечения того, что общая длина кадра, включая 9-байтовый заголовок, кратна 8. Однако для каждого кадра существует максимальное количество байтов заполнения, определяемое текущим состоянием и настройками управления потоком. Если это максимальное значение меньше рассчитанного значения, необходимого для обеспечения выравнивания, будет использоваться максимальное значение, и общая длина кадра не обязательно будет выровнена по 8 байтам.
  • peerMaxConcurrentStreams <число> Устанавливает максимальное количество одновременных потоков для удаленного узла, как если бы был получен кадр SETTINGS. Будет переопределено, если удаленный узел установит собственное значение для maxConcurrentStreams. По умолчанию: 100.
  • maxSessionInvalidFrames <целое число> Устанавливает максимальное количество недопустимых кадров, которые будут терпеть, прежде чем сессия будет закрыта. По умолчанию: 1000.
  • maxSessionRejectedStreams <целое число> Устанавливает максимальное количество потоков, отклоненных при создании, которые будут терпеть, прежде чем сессия будет закрыта. Каждое отклонение связано с ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна сообщить узлу не открывать больше потоков. Продолжение открытия потоков, следовательно, рассматривается как признак неправильного поведения узла. По умолчанию: 100.
  • selectPadding <Функция> Когда options.paddingStrategy равно http2.constants.PADDING_STRATEGY_CALLBACK, предоставляет функцию обратного вызова, используемую для определения заполнения. См. Использование options.selectPadding().
  • settings <Объект настроек HTTP/2> Начальные настройки для отправки удалённому узлу при подключении.
  • Http1IncomingMessage <http.IncomingMessage> Указывает класс IncomingMessage для использования в случае обратной совместимости с HTTP/1. Полезно для расширения исходного http.IncomingMessage. По умолчанию: http.IncomingMessage.
  • Http1ServerResponse <http.ServerResponse> Указывает класс ServerResponse для использования в случае обратной совместимости с HTTP/1. Полезно для расширения исходного http.ServerResponse. По умолчанию: http.ServerResponse.
  • Http2ServerRequest <http2.Http2ServerRequest> Указывает класс Http2ServerRequest для использования. Полезно для расширения исходного Http2ServerRequest. По умолчанию: Http2ServerRequest.
  • Http2ServerResponse <http2.Http2ServerResponse> Указывает класс Http2ServerResponse для использования. Полезно для расширения исходного Http2ServerResponse. По умолчанию: Http2ServerResponse.
  • unknownProtocolTimeout <число> Указывает таймаут в миллисекундах, который сервер должен ожидать при отправке события 'unknownProtocol'. Если сокет не был уничтожен к этому времени, сервер уничтожит его. По умолчанию: 10000.
  • ...: Любой параметр net.createServer() может быть предоставлен.
• onRequestHandler <Функция> См. API совместимости
• Возвращает: <Http2Server>

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

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

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

http2.createSecureServer(options[, onRequestHandler])

• options <Object>
  • allowHTTP1 <boolean> Входящие клиентские подключения, которые не поддерживают HTTP/2, будут понижены до HTTP/1.x, если установлено значение true. См. событие 'unknownProtocol'. См. переговоры ALPN. По умолчанию: false.
  • maxDeflateDynamicTableSize <number> Устанавливает максимальный размер динамической таблицы для сжатия заголовков. По умолчанию: 4Kib.
  • maxSettings <number> Устанавливает максимальное количество записей настроек на один SETTINGS кадр. Минимальное значение равно 1. По умолчанию: 32.
  • maxSessionMemory<number> Устанавливает максимальный объем памяти, который разрешено использовать Http2Session. Значение выражается в мегабайтах, например, 1 равно 1 мегабайту. Минимальное значение равно 1. Это лимит на основе кредитов; существующие Http2Stream могут привести к превышению этого лимита, но новые экземпляры Http2Stream будут отклонены, пока этот лимит превышен. К текущему лимиту относятся: текущее количество Http2Stream сессий, текущее использование памяти таблицами сжатия заголовков, текущие данные, ожидающие отправки, и неподтвержденные PING и SETTINGS кадры. По умолчанию: 10.
  • maxHeaderListPairs <number> Устанавливает максимальное количество заголовков. Это аналогично http.Server#maxHeadersCount или http.ClientRequest#maxHeadersCount. Минимальное значение равно 4. По умолчанию: 128.
  • maxOutstandingPings <number> Устанавливает максимальное количество открытых, неподтвержденных запросов на проверку состояния. По умолчанию: 10.
  • maxSendHeaderBlockLength <number> Устанавливает максимальный разрешенный размер сериализованного, сжатого блока заголовков. Попытки отправить заголовки, превышающие этот лимит, приведут к тому, что будет испущено событие 'frameError' и поток будет закрыт и уничтожен.
  • paddingStrategy <number> Стратегия для определения количества используемого заполнения для HEADERS и DATA кадров. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Значение может быть одним из:
    • http2.constants.PADDING_STRATEGY_NONE: Указывает, что заполнение не применяется.
    • http2.constants.PADDING_STRATEGY_MAX: Указывает, что применяется максимальное количество заполнения, определяемое внутренней реализацией.
    • http2.constants.PADDING_STRATEGY_CALLBACK: Указывает, что используется предоставленный пользователем callback options.selectPadding() для определения количества заполнения.
    • http2.constants.PADDING_STRATEGY_ALIGNED: Попытается применить достаточное количество заполнения для того, чтобы общая длина кадра, включая 9-байтовый заголовок, была кратной 8. Однако для каждого кадра есть максимальное разрешенное количество байтов заполнения, которое определяется текущим состоянием управления потоком и настройками. Если это максимальное значение меньше вычисленного значения, необходимого для выравнивания, будет использоваться максимальное значение, и общая длина кадра не обязательно будет выровнена на 8 байт.
  • peerMaxConcurrentStreams <number> Устанавливает максимальное количество одновременных потоков для удалённого узла, как если бы был получен SETTINGS кадр. Будет перезаписано, если удалённый узел установит своё собственное значение для maxConcurrentStreams. По умолчанию: 100.
  • maxSessionInvalidFrames <integer> Устанавливает максимальное количество недействительных кадров, которые будут допущены перед закрытием сессии. По умолчанию: 1000.
  • maxSessionRejectedStreams <integer> Устанавливает максимальное количество отклоненных потоков при создании, которые будут допущены перед закрытием сессии. Каждое отклонение связано с ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна сообщить узлу не открывать больше потоков. Продолжение открытия потоков, следовательно, рассматривается как признак некорректного поведения узла. По умолчанию: 100.
  • selectPadding <Function> Когда options.paddingStrategy равно http2.constants.PADDING_STRATEGY_CALLBACK, предоставляет функцию обратного вызова, используемую для определения заполнения. См. Использование options.selectPadding().
  • settings <Настройки HTTP/2> Начальные настройки для отправки удалённому узлу при подключении.
  • ...: Любые опции tls.createServer() могут быть предоставлены. Для серверов обычно требуются опции идентификации (pfx или key/cert).
  • origins <string[]> Массив строк происхождения для отправки в ORIGIN кадре сразу после создания нового серверного Http2Session.
  • unknownProtocolTimeout <number> Устанавливает таймаут в миллисекундах, который сервер должен ожидать, когда испускается событие 'unknownProtocol'. Если сокет не был уничтожен к этому времени, сервер уничтожит его. По умолчанию: 10000.
• onRequestHandler <Function> См. API совместимости
• Возвращает: <Http2SecureServer>

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

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

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 <число> Устанавливает максимальное количество открытых, неопознанных пингов. По умолчанию: 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_CALLBACK: Указывает, что для определения размера заполнения будет использована предоставленная пользователем функция обратного вызова options.selectPadding().
    • http2.constants.PADDING_STRATEGY_ALIGNED: Попытается применить достаточно заполнения для обеспечения того, что общая длина кадра, включая 9-байтовый заголовок, кратна 8. Однако для каждого кадра существует максимальное допустимое количество байтов заполнения, определяемое текущим состоянием и параметрами управления потоком. Если это максимальное значение меньше рассчитанного количества, необходимого для обеспечения выравнивания, используется максимальное значение, а общая длина кадра не обязательно будет выровнена по 8 байтам.
  • peerMaxConcurrentStreams <число> Устанавливает максимальное количество одновременных потоков для удалённого участника, как если бы был получен кадр SETTINGS . Будет переопределено, если удалённый участник установит собственное значение для maxConcurrentStreams. По умолчанию: 100.
  • selectPadding <Функция> Когда options.paddingStrategy равно http2.constants.PADDING_STRATEGY_CALLBACK, предоставляет функцию обратного вызова, используемую для определения заполнения. См. Использование options.selectPadding().
  • 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('http2');
const client = http2.connect('https://localhost:1234');

/* Use the client */

client.close();

http2.constants

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

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

http2.getDefaultSettings()

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

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

http2.getPackedSettings([settings])

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

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

const http2 = require('http2');

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

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

http2.getUnpackedSettings(buf)

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

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

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

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

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

stream.respond(headers);

Объекты заголовков, передаваемые в функции обратного вызова, будут иметь прототип 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-language, content-length, content-location, content-md5, content-range, content-type, date, dnt, etag, expires, from, 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('http2');
const server = http2.createServer();
server.on('stream', (stream, headers) => {
  console.log(headers[':path']);
  console.log(headers.ABC);
});

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

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.

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

Использование options.selectPadding()

Когда options.paddingStrategy равно http2.constants.PADDING_STRATEGY_CALLBACK, реализация HTTP/2 обратится к функции обратного вызова options.selectPadding(), если она предоставлена, чтобы определить конкретное количество заполнения для каждого кадра HEADERS и DATA.

Функция options.selectPadding() получает два числовых аргумента, frameLen и maxFrameLen, и должна вернуть число N, такое что frameLen <= N <= maxFrameLen.

const http2 = require('http2');
const server = http2.createServer({
  paddingStrategy: http2.constants.PADDING_STRATEGY_CALLBACK,
  selectPadding(frameLen, maxFrameLen) {
    return maxFrameLen;
  }
});

Функция options.selectPadding() вызывается один раз для каждого кадра HEADERS и DATA. Это оказывает заметное влияние на производительность.

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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы получить потоки push на клиенте, установите обработчик события 'stream' на ClientHttp2Session:

const http2 = require('http2');

const client = http2.connect('http://localhost');

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', (responseHeaders) => {
    // Process response headers
  });
  pushedStream.on('data', (chunk) => { /* handle pushed data */ });
});

const req = client.request({ ':path': '/' });

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

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

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

const net = require('net');

const server = net.createServer((socket) => {
  let name = '';
  socket.setEncoding('utf8');
  socket.on('data', (chunk) => name += chunk);
  socket.on('end', () => socket.end(`hello ${name}`));
});

server.listen(8000);

HTTP/2 прокси CONNECT:

const http2 = require('http2');
const { NGHTTP2_REFUSED_STREAM } = http2.constants;
const net = require('net');

const proxy = http2.createServer();
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // Only accept CONNECT requests
    stream.close(NGHTTP2_REFUSED_STREAM);
    return;
  }
  const auth = new URL(`tcp://${headers[':authority']}`);
  // It's a very good idea to verify that hostname and port are
  // things this proxy should be connecting to.
  const socket = net.connect(auth.port, auth.hostname, () => {
    stream.respond();
    socket.pipe(stream);
    stream.pipe(socket);
  });
  socket.on('error', (error) => {
    stream.close(http2.constants.NGHTTP2_CONNECT_ERROR);
  });
});

proxy.listen(8001);

HTTP/2 клиент CONNECT:

const http2 = require('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:${port}`
});

req.on('response', (headers) => {
  console.log(headers[http2.constants.HTTP2_HEADER_STATUS]);
});
let data = '';
req.setEncoding('utf8');
req.on('data', (chunk) => data += chunk);
req.on('end', () => {
  console.log(`The server says: ${data}`);
  client.close();
});
req.end('Jane');

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

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

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

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

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

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

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

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

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

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

Для создания смешанного HTTPS и HTTP/2 сервера обратитесь к разделу Переговоры ALPN. Обновление с не-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('http2');
const { readFileSync } = require('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
  }));
}

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

Класс: http2.Http2ServerRequest

• Расширяет: <stream.Readable>

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

Событие: 'aborted'

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

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

Событие: 'close'

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

request.aborted

• <boolean>

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

request.authority

• <string>

Псевдополе заголовка запроса authority. Его также можно получить через req.headers[':authority'].

request.complete

• <boolean>

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

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

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

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

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

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

request.rawTrailers

• <string[]>

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

request.scheme

• <string>

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

request.setTimeout(msecs, callback)

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

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

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

request.socket

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

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

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

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

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

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

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

request.stream

• <Http2Stream>

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

request.trailers

• <Object>

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

request.url

• <string>

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

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

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

'/status?name=ryan'

Для разбора URL на части можно использовать require('url').parse(request.url):

$ node
> require('url').parse('/status?name=ryan')
Url {
  protocol: null,
  slashes: null,
  auth: null,
  host: null,
  port: null,
  hostname: null,
  hash: null,
  search: '?name=ryan',
  query: 'name=ryan',
  pathname: '/status',
  path: '/status?name=ryan',
  href: '/status?name=ryan' }

Чтобы получить параметры из строки запроса, используйте функцию require('querystring').parse() или передайте true в качестве второго аргумента функции require('url').parse().

$ node
> require('url').parse('/status?name=ryan', true)
Url {
  protocol: null,
  slashes: null,
  auth: null,
  host: null,
  port: null,
  hostname: null,
  hash: null,
  search: '?name=ryan',
  query: { name: 'ryan' },
  pathname: '/status',
  path: '/status?name=ryan',
  href: '/status?name=ryan' }

Класс: http2.Http2ServerResponse

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

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

Событие: 'close'

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

Событие: 'finish'

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

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

response.addTrailers(headers)

• headers <Object>

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

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

response.connection

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

См. response.socket.

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

• data <строка> | <Buffer> | <Uint8Array>
• 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');

response.getHeaderNames()

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

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

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

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

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

response.hasHeader(name)

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

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

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

response.headersSent

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

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

response.removeHeader(name)

• name <строка>

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

response.removeHeader('Content-Encoding');

response.sendDate

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

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

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

response.setHeader(name, value)

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

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

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

или

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

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

response.setTimeout(msecs[, callback])

• msecs <число>
• callback <Функция>
• Возвращает: <http2.Http2ServerResponse>

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

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

response.socket

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

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

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

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

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

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

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

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

response.statusCode

• <число>

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

response.statusCode = 404;

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

response.statusMessage

• <строка>

Сообщение состояния не поддерживается 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() ещё не вызывался, он переключается на режим неявных заголовков и сбрасывает неявные заголовки.

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

В модуле 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.writeHead(statusCode[, statusMessage][, headers])

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

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

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

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

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

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

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

response.createPushResponse(headers, callback)

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

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

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

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

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

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

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

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

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

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

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

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