Основной API

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

http2 Основной API гораздо более симметричен между клиентом и сервером, чем 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' генерируется, когда возникает ошибка во время обработки 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 <Буфер> Загрузка кадра PING 8-байтовый payload

Событие '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 's собственного свойства alpnProtocol.

http2session.close([callback])

• callback <Функция>

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

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

http2session.closed

• <булево>

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

http2session.connecting

• <булево>

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

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

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

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

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

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

http2session.destroyed

• <булево>

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

http2session.encrypted

• <булево> | <не определено>

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

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

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

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

http2session.localSettings

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

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

http2session.originSet

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

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

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

http2session.pendingSettingsAck

• <булево>

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

http2session.ping([payload, ]callback)

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

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

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

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

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

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

Если аргумент 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>

• options <Объект>

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

• Возвращает: <Поток Клиента HTTP/2>

Только для экземпляров HTTP/2 Клиента 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.

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

Псевдозаголовки :method и :path не указаны в headers, они по умолчанию:

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

Класс: Http2Stream

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

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

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

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

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

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

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

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 writable не была завершена.

Событие: 'close'

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

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

Событие: 'error'

• error <Ошибка>

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

Событие: 'frameError'

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

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

Событие: 'ready'

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

Событие: 'timeout'

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

Событие: 'trailers'

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

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

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

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

Событие: 'wantTrailers'

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

http2stream.aborted

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

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

http2stream.bufferSize

• <число>

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

http2stream.close(code[, callback])

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

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

http2stream.closed

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

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

http2stream.destroyed

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

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

http2stream.endAfterHeaders

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

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

http2stream.id

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

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

http2stream.pending

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

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

http2stream.priority(options)

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

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

http2stream.rstCode

• <число>

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

http2stream.sentHeaders

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

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

http2stream.sentInfoHeaders

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

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

http2stream.sentTrailers

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

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

http2stream.session

• <Http2Session>

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

http2stream.setTimeout(msecs, callback)

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

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

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

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

http2stream.sendTrailers(headers)

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

Отправляет фрейм заключительных данных HEADERS подключённому узлу HTTP/2. Этот метод закроет Http2Stream немедленно и должен вызываться только после того, как был отправлен 'wantTrailers' event. При отправке запроса или ответа, опция 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 и флаги, связанные с заголовками.

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

Событие: 'push'

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

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

Событие: 'response'

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

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

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

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

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

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

При использовании интерфейс объекта 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);
  stream.on('close', () => fs.closeSync(fd));
});

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

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

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

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

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

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

При использовании интерфейс объекта 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() для отправки дополнительных заголовков в peer.

Когда 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.Duplex>

Это событие издается при установлении нового 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(). По умолчанию: 0 (без таймаута)

server.close([callback])

• callback <Функция>

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

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

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

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

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

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

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

server.timeout

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

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

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

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

server.updateSettings([settings])

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

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

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

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

Класс: Http2SecureServer

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

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

Событие: 'checkContinue'

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

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

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

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

Событие: 'connection'

• socket <stream.Duplex>

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

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

Событие: 'request'

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

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

Событие: 'session'

Событие 'session' излучается при создании новой 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>

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

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

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

server.timeout

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

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

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

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

server.updateSettings([settings])

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

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

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

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

http2.createServer(options[, onRequestHandler])

• options <Объект>
  • maxDeflateDynamicTableSize <число> Устанавливает максимальный размер динамической таблицы для сжатия заголовков. По умолчанию: 4Kib.
  • maxSettings <число> Устанавливает максимальное количество записей настроек на один кадр SETTINGS. Минимальное допустимое значение 1. По умолчанию: 32.
  • maxSessionMemory<число> Устанавливает максимальную память, которую может использовать Http2Session. Значение выражается в мегабайтах, например, 1 равно 1 мегабайту. Минимальное допустимое значение 1. Это ограничение на основе кредитов, существующие Http2Stream могут привести к превышению этого лимита, но новые Http2Stream будут отклоняться, пока этот лимит превышен. Текущее количество Http2Stream сессий, текущее использование памяти таблицами сжатия заголовков, текущие данные, ожидающие отправки, и неподтверждённые PING и SETTINGS кадры учитываются в текущем лимите. По умолчанию: 10.
  • maxHeaderListPairs <число> Устанавливает максимальное количество записей заголовков. Это аналогично http.Server#maxHeadersCount или http.ClientRequest#maxHeadersCount. Минимальное значение 4. По умолчанию: 128.
  • maxOutstandingPings <число> Устанавливает максимальное количество активных, неподтверждённых пингов. По умолчанию: 10.
  • maxSendHeaderBlockLength <число> Устанавливает максимальный разрешённый размер сериализованного, сжатого блока заголовков. Попытки отправить заголовки, превышающие этот лимит, приведут к тому, что будет отправлено событие 'frameError' и поток будет закрыт и уничтожен.
  • paddingStrategy <число> Стратегия определения размера заполнения для HEADERS и DATA кадров. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Значение может быть одним из:
    • http2.constants.PADDING_STRATEGY_NONE: Заполнение не применяется.
    • http2.constants.PADDING_STRATEGY_MAX: Применяется максимальное количество заполнения, определяемое внутренней реализацией.
    • http2.constants.PADDING_STRATEGY_ALIGNED: Попытка применить достаточное количество заполнения, чтобы общая длина кадра, включая 9-байтовый заголовок, была кратна 8. Для каждого кадра существует максимальное допустимое количество байтов заполнения, определяемое текущим состоянием управления потоком и настройками. Если это максимальное значение меньше рассчитанного количества, необходимого для выравнивания, используется максимальное значение, и общая длина кадра не обязательно выравнивается на 8 байт.
  • peerMaxConcurrentStreams <число> Устанавливает максимальное количество одновременных потоков для удалённого узла, как если бы был получен кадр SETTINGS. Будет переопределено, если удалённый узел установит своё значение для maxConcurrentStreams. По умолчанию: 100.
  • maxSessionInvalidFrames <целое> Устанавливает максимальное количество невалидных кадров, которые будут допущены перед закрытием сессии. По умолчанию: 1000.
  • maxSessionRejectedStreams <целое> Устанавливает максимальное количество потоков, отклоненных при создании, которые будут допущены перед закрытием сессии. Каждое отклонение связано с ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна сказать узлу не открывать больше потоков. Продолжение открытия потоков, следовательно, рассматривается как признак некорректного поведения узла. По умолчанию: 100.
  • settings <Объект настроек HTTP/2> Начальные настройки для отправки удалённому узлу при подключении.
  • 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 <Объект>
  • allowHTTP1 <логическое> Входящие подключения клиентов, которые не поддерживают HTTP/2, будут понижены до HTTP/1.x, если установлено значение true. См. событие 'unknownProtocol'. См. Переговоры ALPN. По умолчанию: false.
  • maxDeflateDynamicTableSize <число> Устанавливает максимальный размер динамической таблицы для сжатия заголовков. По умолчанию: 4Kib.
  • maxSettings <число> Устанавливает максимальное количество записей настроек на кадр SETTINGS. Минимальное допустимое значение 1. По умолчанию: 32.
  • maxSessionMemory <число> Устанавливает максимальный объем памяти, который может использовать Http2Session. Значение выражается в мегабайтах, например, 1 равно 1 мегабайту. Минимальное допустимое значение 1. Это ограничение на основе кредитов, существующие Http2Stream могут привести к превышению этого лимита, но новые Http2Stream будут отклонены, пока этот лимит превышен. Текущее число Http2Stream сессий, текущее использование памяти таблицами сжатия заголовков, текущие данные, ожидающие отправки, и неподтвержденные PING и SETTINGS кадры учитываются в текущем лимите. По умолчанию: 10.
  • maxHeaderListPairs <число> Устанавливает максимальное количество записей заголовков. Аналогично http.Server#maxHeadersCount или http.ClientRequest#maxHeadersCount. Минимальное значение 4. По умолчанию: 128.
  • maxOutstandingPings <число> Устанавливает максимальное количество ожидающих, неподтвержденных пингов. По умолчанию: 10.
  • maxSendHeaderBlockLength <число> Устанавливает максимальный разрешенный размер сериализованного, сжатого блока заголовков. Попытки отправки заголовков, превышающих этот лимит, приведут к тому, что будет выброшено событие 'frameError', и поток будет закрыт и уничтожен.
  • paddingStrategy <число> Стратегия, используемая для определения количества заполнения для кадров HEADERS и DATA. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Значение может быть одним из следующих:
    • http2.constants.PADDING_STRATEGY_NONE: Заполнение не применяется.
    • http2.constants.PADDING_STRATEGY_MAX: Применяется максимальное количество заполнения, определяемое внутренней реализацией.
    • http2.constants.PADDING_STRATEGY_ALIGNED: Попытка применить достаточное количество заполнения для обеспечения того, что длина всего кадра, включая 9-байтовый заголовок, кратна 8. Для каждого кадра существует максимальное разрешенное количество байтов заполнения, определяемое текущим состоянием управления потоком и настройками. Если это максимальное значение меньше вычисленного количества, необходимого для обеспечения выравнивания, используется максимальное значение, и общая длина кадра не обязательно выравнивается на 8 байтах.
  • peerMaxConcurrentStreams <число> Устанавливает максимальное количество одновременных потоков для удаленного узла, как если бы был получен кадр SETTINGS. Будет переопределено, если удаленный узел установит собственное значение для maxConcurrentStreams. По умолчанию: 100.
  • maxSessionInvalidFrames <целое> Устанавливает максимальное количество недействительных кадров, которые будут допущены, прежде чем сессия будет закрыта. По умолчанию: 1000.
  • maxSessionRejectedStreams <целое> Устанавливает максимальное количество отклоненных при создании потоков, которые будут допущены, прежде чем сессия будет закрыта. Каждое отклонение связано с ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна сообщить удаленному узлу не открывать больше потоков. Продолжение открытия потоков, следовательно, рассматривается как признак некорректного поведения узла. По умолчанию: 100.
  • settings <Объект настроек HTTP/2> Начальные настройки, которые нужно отправить удаленному узлу при подключении.
  • ...: Любые параметры tls.createServer() могут быть предоставлены. Для серверов обычно требуются параметры идентификации (pfx или key/cert).
  • origins <массив строк> Массив строк origin, которые нужно отправить в кадре ORIGIN сразу после создания нового серверного Http2Session.
  • unknownProtocolTimeout <число> Указывает время ожидания в миллисекундах, которое сервер должен подождать при получении события 'unknownProtocol'. Если сокет не был уничтожен к этому времени, сервер уничтожит его. По умолчанию: 10000.
• onRequestHandler <Функция> См. 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 <string> | <URL> Удаленный сервер HTTP/2 для подключения. Он должен быть представлен в виде минимальной, валидной URL-адреса с префиксом http:// или https://, именем хоста и номером порта (если используется нестандартный порт). Информация о пользователе (идентификатор пользователя и пароль), путь, строка запроса и фрагмент в URL будут игнорироваться.
• options <Object>
  • maxDeflateDynamicTableSize <number> Устанавливает максимальный размер динамической таблицы для сжатия заголовков. По умолчанию: 4Kib.
  • maxSettings <number> Устанавливает максимальное количество записей настроек на один кадр SETTINGS. Минимальное значение равно 1. По умолчанию: 32.
  • maxSessionMemory<number> Устанавливает максимальный объем памяти, который может использовать Http2Session. Значение выражается в мегабайтах, например, 1 равно 1 мегабайту. Минимальное значение равно 1. Это ограничение на основе кредитов; существующие Http2Stream могут привести к превышению этого предела, но новые экземпляры Http2Stream будут отклоняться, пока этот предел не будет превышен. Текущее количество Http2Stream сессий, текущее использование памяти таблицами сжатия заголовков, текущие данные, ожидающие отправки, и неподтверждённые PING и SETTINGS кадры учитываются в текущем пределе. По умолчанию: 10.
  • maxHeaderListPairs <number> Устанавливает максимальное количество открытых, неподтверждённых пингов. По умолчанию: 10.
  • maxReservedRemoteStreams <number> Устанавливает максимальное количество резервируемых push-потоков, которые клиент примет в любой момент времени. После того, как текущее количество резервируемых push-потоков превысит этот предел, новые push-потоки, отправленные сервером, будут автоматически отклоняться. Минимальное допустимое значение равно 0. Максимальное допустимое значение равно 2³²-1. Отрицательное значение устанавливает этот параметр на максимальное допустимое значение. По умолчанию: 200.
  • maxSendHeaderBlockLength <number> Устанавливает максимальный допустимый размер сериализованного, сжатого блока заголовков. Попытки отправки заголовков, превышающих этот предел, приведут к тому, что будет отправлено событие 'frameError' и поток будет закрыт и уничтожен.
  • paddingStrategy <number> Стратегия определения количества используемого заполнителя для HEADERS и DATA кадров. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Значение может быть одним из:
    • http2.constants.PADDING_STRATEGY_NONE: Заполнение не применяется.
    • http2.constants.PADDING_STRATEGY_MAX: Применяется максимальное количество заполнителя, определяемое внутренней реализацией.
    • http2.constants.PADDING_STRATEGY_ALIGNED: Попытка применить достаточно заполнителя для того, чтобы общая длина кадра, включая 9-байтовый заголовок, была кратна 8. Для каждого кадра существует максимальное допустимое количество байтов заполнителя, определяемое текущим состоянием и настройками управления потоком. Если это максимальное значение меньше рассчитанного количества, необходимого для выравнивания, используется максимальное значение, и общая длина кадра не обязательно выравнивается по 8 байтам.
  • peerMaxConcurrentStreams <number> Устанавливает максимальное количество одновременных потоков для удалённого узла, как если бы был получен кадр SETTINGS. Будет перезаписано, если удалённый узел установит собственное значение для maxConcurrentStreams. По умолчанию: 100.
  • protocol <string> Протокол для подключения, если он не задан в authority. Значение может быть либо 'http:' или 'https:'. По умолчанию: 'https:'
  • settings <HTTP/2 Settings Object> Начальные настройки для отправки удалённому узлу при подключении.
  • createConnection <Function> Дополнительный обработчик, который получает экземпляр URL , переданный в connect и объект options, и возвращает любой поток Duplex, который должен использоваться в качестве подключения для этой сессии.
  • ...: Любые опции для net.connect() или tls.connect() могут быть предоставлены.
  • unknownProtocolTimeout <number> Устанавливает таймаут в миллисекундах, который сервер должен ждать при получении события 'unknownProtocol'. Если сокет не был уничтожен к этому времени, сервер уничтожит его. По умолчанию: 10000.
• listener <Function> Будет зарегистрирован как одноразовый обработчик события '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 Settings Object>

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

http2.getPackedSettings([settings])

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

Возвращает экземпляр 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 <Buffer> | <Uint8Array> Упакованные настройки.
• Возвращает: <HTTP/2 Settings Object>

Возвращает объект HTTP/2 Settings Object, содержащий десериализованные настройки из заданного 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-encoding, 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 игнорируются.
• 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.

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

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

Существует несколько типов ошибок, которые могут возникнуть при использовании модуля http2:

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

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

Внутренние ошибки возникают, когда сессия 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, !, #, $, %, &, ', *, +, -, ., ^, _, ` (backtick), |, и ~.

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

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

Потоки 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 определяет расширение "Расширенный протокол CONNECT" для HTTP/2, которое можно использовать для начальной настройки использования Http2Stream с помощью метода CONNECT в качестве туннеля для других протоколов связи (например, WebSockets).

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

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

После того, как клиент получит фрейм SETTINGS от сервера, указывающий, что расширенное подключение может быть использовано, он может отправлять запросы 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. Обновление с серверов HTTP/1 без TLS не поддерживается.

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

Переговоры ALPN

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

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

const { createSecureServer } = require('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.connection

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

См. request.socket.

request.destroy([error])

• error <Error>

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

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

request.headers

• <Object>

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

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

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

См. Объект заголовков 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 на составляющие части, можно использовать new URL():

$ node
> new URL('/status?name=ryan', 'http://example.com')
URL {
  href: 'http://example.com/status?name=ryan',
  origin: 'http://example.com',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'example.com',
  hostname: 'example.com',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

Класс: 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.createPushResponse(headers, callback)

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

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

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

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

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

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

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

response.finished

• <boolean>

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

response.getHeader(name)

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

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

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

response.getHeaderNames()

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

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

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

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

response.getHeaders()

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

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

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

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

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

response.hasHeader(name)

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

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

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

response.headersSent

• <boolean>

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

response.removeHeader(name)

• name <string>

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

response.removeHeader('Content-Encoding');

response.sendDate

• <boolean>

Если истинно, заголовок 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.Сокет> | <tls.TLSСокет>

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

• <Http2Поток>

Объект Http2Stream, обеспечивающий работу ответа.

response.writableEnded

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

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

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

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

Если этот метод вызывается, а 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 <число>
• statusMessage <строка>
• headers <Объект>
• Возвращает: <http2.Http2ServerResponse>

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

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

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

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

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.

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