Основной 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 собственного свойства alpnProtocol.

http2session.close([callback])

• callback <Функция>

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

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

http2session.closed

• <boolean>

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

http2session.connecting

• <boolean>

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

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

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

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

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

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

http2session.destroyed

• <boolean>

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

http2session.encrypted

• <boolean> | <undefined>

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

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

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

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

http2session.localSettings

• <HTTP/2 Settings Object>

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

http2session.originSet

• <string[]> | <undefined>

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

Свойство originSet доступно только при использовании безопасного подключения TLS.

http2session.pendingSettingsAck

• <boolean>

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

http2session.ping([payload, ]callback)

• payload <Buffer> | <TypedArray> | <DataView> Необязательная полезная нагрузка пинга.
• callback <Function>
• Возвращает: <boolean>

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

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

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

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

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

http2session.ref()

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

http2session.remoteSettings

• <HTTP/2 Settings Object>

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

http2session.setLocalWindowSize(windowSize)

• windowSize <number>

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

http2session.setTimeout(msecs, callback)

• msecs <number>
• callback <Function>

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

http2session.socket

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

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

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

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

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

http2session.state

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

• <Объект>
  • 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, который может быть использован для прерывания текущего запроса.

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

Только для экземпляров 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. В качестве рекомендации, рекомендуется устанавливать заголовок 'content-type' и указывать используемую кодировку символов при использовании экземпляра Http2Stream для отправки текста.

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

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

Событие: 'ready'

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

Событие: 'timeout'

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

Событие: 'trailers'

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

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

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

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

Событие: 'wantTrailers'

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

http2stream.aborted

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

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

http2stream.bufferSize

• <число>

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

http2stream.close(code[, callback])

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

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

http2stream.closed

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

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

http2stream.destroyed

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

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

http2stream.endAfterHeaders

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

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

http2stream.id

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

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

http2stream.pending

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

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

http2stream.priority(options)

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

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

http2stream.rstCode

• <число>

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

http2stream.sentHeaders

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

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

http2stream.sentInfoHeaders

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

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

http2stream.sentTrailers

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

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

http2stream.session

• <Http2Session>

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

http2stream.setTimeout(msecs, callback)

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

const http2 = require('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' событие. При отправке запроса или ответа 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' вызывается, когда получены заголовки ответа для потока серверной отправки. Обработчик события получает объект Объект заголовков 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

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

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

http2stream.pushAllowed

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Класс: Http2Server

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

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

Событие: 'checkContinue'

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

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

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

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

Событие: 'connection'

• socket <stream.Duplex>

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

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

Событие: 'request'

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

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

Событие: 'session'

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

Событие: 'sessionError'

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

Событие: 'stream'

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

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

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

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>

Используется для установки таймаута для запросов http2 сервера и устанавливает функцию обратного вызова, которая вызывается, когда на сервере Http2Server нет активности после 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 <Http2Stream> Ссылка на поток
• headers <Объект заголовков HTTP/2> Объект, описывающий заголовки
• flags <число> Соответствующие числовые флаги
• rawHeaders <Массив> Массив, содержащий исходные имена заголовков и соответствующие значения.

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

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

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

const options = getOptionsSomehow();

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

Событие: 'timeout'

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

Событие: 'unknownProtocol'

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

server.close([callback])

• callback <Функция>

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

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

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

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

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

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

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

/* Use the client */

client.close();

http2.constants

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

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

http2.getDefaultSettings()

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

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

http2.getPackedSettings([settings])

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

Возвращает экземпляр Buffer , содержащий сериализованное представление заданных настроек HTTP/2 в соответствии со спецификацией HTTP/2 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 <Буфер> | <Массив с типом данных> Сжатые настройки.
• Возвращает: <Объект настроек HTTP/2>

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

http2.sensitiveHeaders

• <символ>

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

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

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

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

stream.respond(headers);

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

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

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

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

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

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

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

stream.respond(headers);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const http2 = require('http2');

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

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

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

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

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

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

const net = require('net');

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

server.listen(8000);

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

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

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

proxy.listen(8001);

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

const http2 = require('http2');

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

// Must not specify the ':path' and ':scheme' headers
// for CONNECT requests or an error will be thrown.
const req = client.request({
  ':method': 'CONNECT',
  ':authority': `localhost:${port}`
});

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

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

RFC 8441 определяет расширение "Расширенный протокол 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 может использоваться, он может отправлять запросы CONNECT с использованием псевдозаголовка HTTP/2 ':protocol':

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

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

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

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

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

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

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

Переговоры ALPN

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

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

const { createSecureServer } = require('http2');
const { readFileSync } = require('fs');

const cert = readFileSync('./cert.pem');
const key = readFileSync('./key.pem');

const server = createSecureServer(
  { cert, key, allowHTTP1: true },
  onRequest
).listen(4443);

function onRequest(req, res) {
  // Detects if it is a HTTPS request or HTTP/2
  const { socket: { alpnProtocol } } = req.httpVersion === '2.0' ?
    req.stream.session : req;
  res.writeHead(200, { 'content-type': 'application/json' });
  res.end(JSON.stringify({
    alpnProtocol,
    httpVersion: req.httpVersion
  }));
}

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

Класс: http2.Http2ServerRequest

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

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

Событие: 'aborted'

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

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

Событие: 'close'

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

request.aborted

• <boolean>

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

request.authority

• <string>

Псевдополе заголовка authority запроса. Поскольку HTTP/2 позволяет запросам задавать либо :authority, либо host, это значение выводится из req.headers[':authority'], если оно присутствует. В противном случае оно выводится из req.headers['host'].

request.complete

• <boolean>

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

request.connection

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

См. request.socket.

request.destroy([error])

• error <Error>

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

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

request.headers

• <Object>

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

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

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

См. Объект заголовков 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>

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

request.setTimeout(msecs, callback)

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

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

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

request.socket

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

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

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

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

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

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

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

request.stream

• <Http2Stream>

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

request.trailers

• <Объект>

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

request.url

• <строка>

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

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

Тогда 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

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

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

Событие: 'close'

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

Событие: 'finish'

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

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

response.addTrailers(headers)

• headers <Объект>

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

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

response.connection

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

См. response.socket.

response.createPushResponse(headers, callback)

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

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

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

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

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

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

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

response.finished

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

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

response.getHeader(name)

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

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

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

response.getHeaderNames()

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

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

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

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

response.getHeaders()

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

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

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

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

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

response.hasHeader(name)

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

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

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

response.headersSent

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

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

response.removeHeader(name)

• name <строка>

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

response.removeHeader('Content-Encoding');

response.req

• <http2.Http2ЗапросСервера>

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

response.sendDate

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

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

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

response.setHeader(name, value)

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

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

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

или

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

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

Когда заголовки были установлены с помощью response.setHeader(), они будут объединены с любыми заголовками, переданными в response.writeHead(), при этом заголовки, переданные в response.writeHead(), имеют приоритет.

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

response.setTimeout(msecs[, callback])

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

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

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

response.socket

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

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

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

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

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

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

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

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

response.statusCode

• <число>

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

response.statusCode = 404;

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

response.statusMessage

• <строка>

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

response.stream

• <Http2Stream>

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

response.writableEnded

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

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

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

• chunk <строка> | <Буфер> | <Uint8Array>
• 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>

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

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

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

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

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.

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

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

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