HTTP/2

[История]

Версия	Изменения
v15.0.0	Теперь можно отправлять/получать запросы с заголовком `host` (с `:authority` или без него).
v15.3.0, v14.17.0	Возможно прерывание запроса с помощью AbortSignal.
v10.10.0	HTTP/2 теперь стабилен. Ранее он был экспериментальным.
v8.4.0	Добавлено в: v8.4.0

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

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

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

const http2 = require('node:http2')

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

Node.js может быть собран без включения поддержки модуля node:crypto. В таких случаях попытка import из node:http2 или вызов require('node:http2') приведет к ошибке.

При использовании CommonJS ошибку можно перехватить с помощью try/catch:

let http2
try {
  http2 = require('node:http2')
} catch (err) {
  console.error('Поддержка http2 отключена!')
}

При использовании лексического ключевого слова import ESM ошибку можно перехватить только в том случае, если обработчик для process.on('uncaughtException') зарегистрирован до любой попытки загрузки модуля (например, с помощью модуля предварительной загрузки).

При использовании ESM, если есть вероятность, что код может быть запущен в сборке Node.js, где поддержка криптографии не включена, рассмотрите возможность использования функции import() вместо лексического ключевого слова import:

let http2
try {
  http2 = await import('node:http2')
} catch (err) {
  console.error('Поддержка http2 отключена!')
}

Базовый API

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

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

Пример на стороне сервера

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

ESMCJS

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

const server = createSecureServer({
  key: readFileSync('localhost-privkey.pem'),
  cert: 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)

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

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

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

server.listen(8443)

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

bash

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

Пример на стороне клиента

Ниже показан HTTP/2 клиент:

ESMCJS

import { connect } from 'node:http2'
import { readFileSync } from 'node:fs'

const client = connect('https://localhost:8443', {
  ca: 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()

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

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

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

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

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

Класс: `Http2Session`

Добавлено в: v8.4.0

Расширяет: <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'`

Добавлено в: v8.4.0

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

Событие: `'connect'`

Добавлено в: v8.4.0

session <Http2Session>
socket <net.Socket>

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

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

Событие: `'error'`

Добавлено в: v8.4.0

error <Error>

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

Событие: `'frameError'`

Добавлено в: v8.4.0

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

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

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

Событие: `'goaway'`

Добавлено в: v8.4.0

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

Событие 'goaway' генерируется при получении фрейма GOAWAY.

Экземпляр Http2Session будет автоматически остановлен при генерации события 'goaway'.

Событие: `'localSettings'`

Добавлено в: v8.4.0

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

Событие 'localSettings' генерируется после получения подтверждающего фрейма SETTINGS.

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

session.settings({ enablePush: false })

session.on('localSettings', settings => {
  /* Используйте новые настройки */
})

Событие: `'ping'`

Добавлено в: v10.12.0

payload <Buffer> 8-байтовая полезная нагрузка фрейма PING

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

Событие: `'remoteSettings'`

Добавлено в: v8.4.0

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

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

session.on('remoteSettings', settings => {
  /* Используйте новые настройки */
})

Событие: `'stream'`

Добавлено в: v8.4.0

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

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

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() соответственно, как в примере ниже:

ESMCJS

import { createServer } from 'node:http2'

// Создание незашифрованного HTTP/2 сервера
const server = createServer()

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

server.listen(8000)

const http2 = require('node:http2')

// Создание незашифрованного HTTP/2 сервера
const server = http2.createServer()

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

server.listen(8000)

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

Событие: `'timeout'`

Добавлен в: v8.4.0

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

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

`http2session.alpnProtocol`

Добавлен в: v9.4.0

<string> | <undefined>

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

`http2session.close([callback])`

Добавлен в: v9.4.0

callback <Function>

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

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

`http2session.closed`

Добавлен в: v9.4.0

<boolean>

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

`http2session.connecting`

Добавлен в: v10.0.0

<boolean>

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

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

Добавлен в: v8.4.0

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`

Добавлен в: v8.4.0

<boolean>

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

`http2session.encrypted`

Добавлен в: v9.4.0

<boolean> | <undefined>

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

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

Добавлен в: v9.4.0

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

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

`http2session.localSettings`

Добавлен в: v8.4.0

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

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

`http2session.originSet`

Добавлен в: v9.4.0

<string[]> | <undefined>

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

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

`http2session.pendingSettingsAck`

Добавлено в: v8.4.0

<boolean>

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

`http2session.ping([payload, ]callback)`

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v8.9.3	Добавлено в: v8.9.3

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

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

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

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

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

session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`Ping подтвержден за ${duration} миллисекунд`)
    console.log(`С полезной нагрузкой '${payload.toString()}'`)
  }
})

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

`http2session.ref()`

Добавлено в: v9.4.0

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

`http2session.remoteSettings`

Добавлено в: v8.4.0

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

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

`http2session.setLocalWindowSize(windowSize)`

Добавлено в: v15.3.0, v14.18.0

windowSize <число>

Устанавливает размер окна конечной точки. windowSize — это общий размер окна для установки, а не дельта.

ESMCJS

import { createServer } from 'node:http2'

const server = createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // Установить размер локального окна равным 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

const http2 = require('node:http2')

const server = http2.createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // Установить размер локального окна равным 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

Для клиентов http2 соответствующим событием является либо 'connect', либо 'remoteSettings'.

`http2session.setTimeout(msecs, callback)`

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v8.4.0	Добавлено в: v8.4.0

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

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

`http2session.socket`

Добавлен в: v8.4.0

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

Добавлен в: v8.4.0

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

<Object>
- effectiveLocalWindowSize <number> Текущий размер окна управления потоком (прием) для Http2Session.
- effectiveRecvDataLength <number> Текущее количество байтов, полученных с момента последнего обновления управления потоком WINDOW_UPDATE.
- nextStreamID <number> Числовой идентификатор, который будет использоваться при следующем создании нового Http2Stream этим Http2Session.
- localWindowSize <number> Количество байтов, которые удаленный узел может отправить, не получив WINDOW_UPDATE.
- lastProcStreamID <number> Числовой идентификатор Http2Stream, для которого последний раз был получен кадр HEADERS или DATA.
- remoteWindowSize <number> Количество байтов, которые этот Http2Session может отправить, не получив WINDOW_UPDATE.
- outboundQueueSize <number> Количество кадров, находящихся в настоящее время в исходящей очереди для этого Http2Session.
- deflateDynamicTableSize <number> Текущий размер в байтах таблицы состояния сжатия исходящих заголовков.
- inflateDynamicTableSize <number> Текущий размер в байтах таблицы состояния сжатия входящих заголовков.

Объект, описывающий текущее состояние этого Http2Session.

`http2session.settings([settings][, callback])`

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает исключение `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v8.4.0	Добавлено в: v8.4.0

settings <Объект настроек HTTP/2>
callback <Функция> Обратный вызов, который вызывается после установления соединения сессии или сразу, если сессия уже подключена.
- err <Ошибка> | <null>
- settings <Объект настроек HTTP/2> Обновлённый объект settings.
- duration <целое число>

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

После вызова свойство http2session.pendingSettingsAck будет иметь значение true, пока сессия ожидает подтверждения новых настроек от удалённого узла.

Новые настройки не вступят в силу, пока не будет получено подтверждение SETTINGS и не будет отправлено событие 'localSettings'. Можно отправлять несколько фреймов SETTINGS, пока подтверждение всё ещё ожидается.

`http2session.type`

Добавлено в: v8.4.0

<число>

http2session.type будет равен http2.constants.NGHTTP2_SESSION_SERVER, если этот экземпляр Http2Session является сервером, и http2.constants.NGHTTP2_SESSION_CLIENT, если экземпляр является клиентом.

`http2session.unref()`

Добавлено в: v9.4.0

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

Класс: `ServerHttp2Session`

Добавлено в: v8.4.0

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

`serverhttp2session.altsvc(alt, originOrStream)`

Добавлено в: v9.4.0

alt <string> Описание конфигурации альтернативной службы, как определено в RFC 7838.
originOrStream <number> | <string> | <URL> | <Object> Либо строка URL, указывающая на источник (или Object со свойством origin), либо числовой идентификатор активного Http2Stream, заданный свойством http2stream.id.

Отправляет фрейм ALTSVC (как определено в RFC 7838) подключенному клиенту.

ESMCJS

import { createServer } from 'node:http2'

const server = createServer()
server.on('session', session => {
  // Установка altsvc для origin https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // Установка altsvc для конкретного потока
  stream.session.altsvc('h2=":8000"', stream.id)
})

const http2 = require('node:http2')

const server = http2.createServer()
server.on('session', session => {
  // Установка altsvc для origin https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // Установка altsvc для конкретного потока
  stream.session.altsvc('h2=":8000"', stream.id)
})

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

Строки alt и origin должны содержать только байты 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)`

Добавлено в: v10.12.0

origins <string> | <URL> | <Object> Одна или несколько URL-строк, передаваемые в виде отдельных аргументов.

Отправляет фрейм ORIGIN (как определено в RFC 8336) подключенному клиенту, чтобы сообщить набор источников, для которых сервер может предоставлять авторитетные ответы.

ESMCJS

import { createSecureServer } from 'node:http2'
const options = getSecureOptionsSomehow()
const server = createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})
server.on('session', session => {
  session.origin('https://example.com', 'https://example.org')
})

const http2 = require('node:http2')
const options = getSecureOptionsSomehow()
const server = http2.createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})
server.on('session', session => {
  session.origin('https://example.com', 'https://example.org')
})

Если в качестве 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():

ESMCJS

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

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

Класс: `ClientHttp2Session`

Добавлено в: v8.4.0

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

Событие: `'altsvc'`

Добавлено в: v9.4.0

alt <string>
origin <string>
streamId <number>

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

ESMCJS

import { connect } from 'node:http2'
const client = connect('https://example.org')

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

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

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

Событие: `'origin'`

Добавлено в: v10.12.0

origins <string[]>

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

ESMCJS

import { connect } from 'node:http2'
const client = connect('https://example.org')

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

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

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

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

`clienthttp2session.request(headers[, options])`

Добавлено в: v8.4.0

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

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

При первом создании ClientHttp2Session сокет может еще не быть подключен. Если clienthttp2session.request() вызывается в это время, фактический запрос будет отложен до тех пор, пока сокет не будет готов к работе. Если session закрывается до выполнения фактического запроса, генерируется ошибка ERR_HTTP2_GOAWAY_SESSION.

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

ESMCJS

import { connect, constants } from 'node:http2'
const clientSession = connect('https://localhost:1234')
const { HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS } = 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', () => {
    /* .. */
  })
})

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

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

Когда установлен параметр 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`

Добавлено в: v8.4.0

Расширяет: <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. Записываемая сторона Duplex используется для отправки данных подключенному узлу, а читаемая сторона используется для получения данных, отправленных подключенным узлом.

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

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

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

Создание

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

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

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

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

Уничтожение

Все экземпляры Http2Stream уничтожаются в следующих случаях:

При получении соединенным узлом фрейма RST_STREAM для потока и (только для клиентских потоков) после чтения ожидающих данных.
При вызове метода http2stream.close() и (только для клиентских потоков) после чтения ожидающих данных.
При вызове методов http2stream.destroy() или http2session.destroy().

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

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

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

Событие: `'aborted'`

Добавлено в: v8.4.0

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

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

Событие: `'close'`

Добавлено в: v8.4.0

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

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

Событие: `'error'`

Добавлено в: v8.4.0

error <Error>

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

Событие: `'frameError'`

Добавлено в: v8.4.0

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

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

Событие: `'ready'`

Добавлено в: v8.4.0

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

Событие: `'timeout'`

Добавлено в: v8.4.0

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

Событие: `'trailers'`

Добавлено в: v8.4.0

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

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

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

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

Событие: `'wantTrailers'`

Добавлено в: v10.0.0

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

`http2stream.aborted`

Добавлено в: v8.4.0

<boolean>

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

`http2stream.bufferSize`

Добавлено в: v11.2.0, v10.16.0

<number>

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

`http2stream.close(code[, callback])`

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v8.4.0	Добавлено в: v8.4.0

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

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

`http2stream.closed`

Добавлено в: v9.4.0

<boolean>

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

`http2stream.destroyed`

Добавлено в: v8.4.0

<boolean>

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

`http2stream.endAfterHeaders`

Добавлен в: v10.11.0

<boolean>

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

`http2stream.id`

Добавлен в: v8.4.0

<number> | <undefined>

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

`http2stream.pending`

Добавлен в: v9.4.0

<boolean>

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

`http2stream.priority(options)`

Добавлен в: v8.4.0

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

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

`http2stream.rstCode`

Добавлено в: v8.4.0

<число>

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

`http2stream.sentHeaders`

Добавлено в: v9.5.0

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

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

`http2stream.sentInfoHeaders`

Добавлено в: v9.5.0

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

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

`http2stream.sentTrailers`

Добавлено в: v9.5.0

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

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

`http2stream.session`

Добавлено в: v8.4.0

<Http2Session>

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

`http2stream.setTimeout(msecs, callback)`

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v8.4.0	Добавлено в: v8.4.0

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

ESMCJS

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

// Отменить поток, если нет активности после 5 секунд
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

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

// Отменить поток, если нет активности после 5 секунд
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

`http2stream.state`

Добавлен в: v8.4.0

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

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

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

`http2stream.sendTrailers(headers)`

Добавлен в: v10.0.0

headers <HTTP/2 Headers Object>

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

ESMCJS

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

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

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

Класс: `ClientHttp2Stream`

Добавлено в: v8.4.0

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

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

Событие: `'continue'`

Добавлено в: v8.5.0

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

Событие: `'headers'`

Добавлено в: v8.4.0

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

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

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

Событие: `'push'`

Добавлено в: v8.4.0

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

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

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

Событие: `'response'`

Добавлено в: v8.4.0

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

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

ESMCJS

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

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

Класс: `ServerHttp2Stream`

Добавлено в: v8.4.0

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

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

`http2stream.additionalHeaders(headers)`

Добавлено в: v8.4.0

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

Отправляет дополнительный информационный фрейм HEADERS подключенному узлу HTTP/2.

`http2stream.headersSent`

Добавлено в: v8.4.0

<boolean>

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

`http2stream.pushAllowed`

Добавлено в: v8.4.0

<boolean>

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

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

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v8.4.0	Добавлено в: v8.4.0

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

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

ESMCJS

import { createServer } from 'node:http2'
const server = 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')
})

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

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

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

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

[История]

Версия	Изменения
v14.5.0, v12.19.0	Разрешено явное задание заголовков даты.
v8.4.0	Добавлено в: v8.4.0

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

ESMCJS

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

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

ESMCJS

import { createServer } from 'node:http2'
const server = 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')
})

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

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

[История]

Версия	Изменения
v14.5.0, v12.19.0	Разрешено явное задание заголовков даты.
v12.12.0	Параметр `fd` теперь может быть `FileHandle`.
v10.0.0	Теперь поддерживается любой читаемый файловый дескриптор, необязательно для обычного файла.
v8.4.0	Добавлено в: v8.4.0

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

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

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

ESMCJS

import { createServer } from 'node:http2'
import { openSync, fstatSync, closeSync } from 'node:fs'

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

  const stat = 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', () => closeSync(fd))
})

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

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

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

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

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

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

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

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

ESMCJS

import { createServer } from 'node:http2'
import { openSync, fstatSync, closeSync } from 'node:fs'

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

  const stat = 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', () => closeSync(fd))
})

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

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

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

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

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

[История]

Версия	Изменения
v14.5.0, v12.19.0	Разрешено явное задание заголовков даты.
v10.0.0	Теперь поддерживается любой читаемый файл, необязательно обычный файл.
v8.4.0	Добавлено в: v8.4.0

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

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

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

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

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

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

ESMCJS

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

  function onError(err) {
    // stream.respond() может выбросить ошибку, если поток был уничтожен
    // другой стороной.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // Выполнить фактическую обработку ошибок.
      console.error(err)
    }
    stream.end()
  }

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

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

  function onError(err) {
    // stream.respond() может выбросить ошибку, если поток был уничтожен
    // другой стороной.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // Выполнить фактическую обработку ошибок.
      console.error(err)
    }
    stream.end()
  }

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

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

ESMCJS

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    // Проверить stat здесь...
    stream.respond({ ':status': 304 })
    return false // Отменить операцию отправки
  }
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck })
})

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    // Проверить stat здесь...
    stream.respond({ ':status': 304 })
    return false // Отменить операцию отправки
  }
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck })
})

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

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

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

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

ESMCJS

import { createServer } from 'node:http2'
const server = 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' })
  })
})

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

Класс: `Http2Server`

Добавлено в: v8.4.0

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

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

Событие: `'checkContinue'`

Добавлено в: v8.5.0

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

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

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

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

Событие: `'connection'`

Добавлено в: v8.4.0

socket <stream.Duplex>

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

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

Событие: `'request'`

Добавлено в: v8.4.0

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

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

Событие: `'session'`

Добавлено в: v8.4.0

session <ServerHttp2Session>

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

Событие: `'sessionError'`

Добавлено в: v8.4.0

error <Error>
session <ServerHttp2Session>

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

Событие: `'stream'`

Добавлено в: v8.4.0

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

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

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

ESMCJS

import { createServer, constants } from 'node:http2'
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = constants

const server = 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')
})

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

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

Событие: `'timeout'`

[История]

Версия	Изменения
v13.0.0	Время ожидания по умолчанию изменено с 120 секунд на 0 (без ожидания).
v8.4.0	Добавлено в: v8.4.0

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

`server.close([callback])`

Добавлено в: v8.4.0

callback <Function>

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

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

`server[Symbol.asyncDispose]()`

Добавлено в: v20.4.0

[Стабильность: 1 - Экспериментально]

Стабильность: 1 Стабильность: 1 - Экспериментально

Вызывает server.close() и возвращает promise, который выполняется после закрытия сервера.

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

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает ошибку `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v13.0.0	Время ожидания по умолчанию изменено с 120 секунд на 0 (без ожидания).
v8.4.0	Добавлено в: v8.4.0

msecs <number> По умолчанию: 0 (без ожидания)
callback <Function>
Возвращает: <Http2Server>

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

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

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

`server.timeout`

[История]

Версия	Изменения
v13.0.0	Время ожидания по умолчанию изменено с 120 с на 0 (без ожидания).
v8.4.0	Добавлено в: v8.4.0

<число> Время ожидания в миллисекундах. По умолчанию: 0 (без ожидания)

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

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

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

`server.updateSettings([settings])`

Добавлено в: v15.1.0, v14.17.0

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

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

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

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

Класс: `Http2SecureServer`

Добавлено в: v8.4.0

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

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

Событие: `'checkContinue'`

Добавлено в: v8.5.0

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

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

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

Событие: `'connection'`

Добавлено в: v8.4.0

socket <stream.Duplex>

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

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

Событие: `'request'`

Добавлено в: v8.4.0

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

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

Событие: `'session'`

Добавлено в: v8.4.0

session <ServerHttp2Session>

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

Событие: `'sessionError'`

Добавлено в: v8.4.0

error <Error>
session <ServerHttp2Session>

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

Событие: `'stream'`

Добавлено в: v8.4.0

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

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

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

ESMCJS

import { createSecureServer, constants } from 'node:http2'
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = constants

const options = getOptionsSomehow()

const server = 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')
})

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

const options = getOptionsSomehow()

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

Событие: `'timeout'`

Добавлено в: v8.4.0

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

Событие: `'unknownProtocol'`

[История]

Версия	Изменения
v19.0.0	Это событие будет генерироваться только в том случае, если клиент не передал расширение ALPN во время TLS-handshake.
v8.4.0	Добавлено в: v8.4.0

socket <stream.Duplex>

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

В более ранних версиях Node.js это событие генерировалось, если allowHTTP1 имеет значение false, и во время TLS-handshake клиент либо не отправляет расширение ALPN, либо отправляет расширение ALPN, которое не включает HTTP/2 (h2). В более новых версиях Node.js это событие генерируется только в том случае, если allowHTTP1 имеет значение false, и клиент не отправляет расширение ALPN. Если клиент отправляет расширение ALPN, которое не включает HTTP/2 (или HTTP/1.1, если allowHTTP1 имеет значение true), TLS-handshake завершится неудачей, и безопасное соединение не будет установлено.

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

`server.close([callback])`

Добавлено в: v8.4.0

callback <Function>

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

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

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает ошибку `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v8.4.0	Добавлено в: v8.4.0

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

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

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

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

`server.timeout`

[История]

Версия	Изменения
v13.0.0	Время ожидания по умолчанию изменено с 120 с на 0 (без времени ожидания).
v8.4.0	Добавлено в: v8.4.0

<число> Время ожидания в миллисекундах. По умолчанию: 0 (без времени ожидания)

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

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

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

`server.updateSettings([settings])`

Добавлено в: v15.1.0, v14.17.0

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

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

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

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

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

[История]

Версия	Изменения
v23.0.0	Добавлены `streamResetBurst` и `streamResetRate`.
v13.0.0	`PADDING_STRATEGY_CALLBACK` стал эквивалентен `PADDING_STRATEGY_ALIGNED`, а `selectPadding` удален.
v13.3.0, v12.16.0	Добавлен параметр `maxSessionRejectedStreams` со значением по умолчанию 100.
v13.3.0, v12.16.0	Добавлен параметр `maxSessionInvalidFrames` со значением по умолчанию 1000.
v12.4.0	Параметр `options` теперь поддерживает параметры `net.createServer()`.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Добавлен параметр `unknownProtocolTimeout` со значением по умолчанию 10000.
v14.4.0, v12.18.0, v10.21.0	Добавлен параметр `maxSettings` со значением по умолчанию 32.
v9.6.0	Добавлены параметры `Http1IncomingMessage` и `Http1ServerResponse`.
v8.9.3	Добавлен параметр `maxOutstandingPings` с предельным значением по умолчанию 10.
v8.9.3	Добавлен параметр `maxHeaderListPairs` с предельным значением по умолчанию 128 пар заголовков.
v8.4.0	Добавлено в: v8.4.0

options <Объект>
- maxDeflateDynamicTableSize <число> Устанавливает максимальный размер динамической таблицы для сжатия полей заголовков. По умолчанию: 4Kib.
- maxSettings <число> Устанавливает максимальное количество записей настроек на фрейм SETTINGS. Минимально допустимое значение — 1. По умолчанию: 32.
- maxSessionMemory<число> Устанавливает максимальный объем памяти, который может использовать Http2Session. Значение выражается в мегабайтах, например, 1 равно 1 мегабайту. Минимально допустимое значение — 1. Это ограничение на основе кредитов, существующие Http2Stream могут привести к превышению этого предела, но новые экземпляры Http2Stream будут отклонены, пока этот предел превышен. Текущее количество сеансов Http2Stream, текущее использование памяти таблицами сжатия заголовков, текущие данные, ожидающие отправки, и неподтвержденные фреймы PING и SETTINGS учитываются в текущем лимите. По умолчанию: 10.
- maxHeaderListPairs <число> Устанавливает максимальное количество записей заголовков. Это аналогично server.maxHeadersCount или request.maxHeadersCount в модуле node:http. Минимальное значение — 4. По умолчанию: 128.
- maxOutstandingPings <число> Устанавливает максимальное количество необработанных, неподтвержденных запросов ping. По умолчанию: 10.
- maxSendHeaderBlockLength <число> Устанавливает максимально допустимый размер сериализованного, сжатого блока заголовков. Попытки отправить заголовки, превышающие этот лимит, приведут к событию 'frameError' и закрытию и уничтожению потока. Хотя это устанавливает максимально допустимый размер для всего блока заголовков, nghttp2 (внутренняя библиотека http2) имеет ограничение 65536 для каждой декомпрессированной пары ключ/значение.
- paddingStrategy <число> Стратегия, используемая для определения количества заполнения, которое следует использовать для фреймов HEADERS и DATA. По умолчанию: http2.constants.PADDING_STRATEGY_NONE. Значение может быть одним из:
- http2.constants.PADDING_STRATEGY_NONE: Заполнение не применяется.
- http2.constants.PADDING_STRATEGY_MAX: Применяется максимальное количество заполнения, определяемое внутренней реализацией.
- http2.constants.PADDING_STRATEGY_ALIGNED: Пытается применить достаточно заполнения, чтобы убедиться, что общая длина фрейма, включая 9-байтовый заголовок, кратна 8. Для каждого фрейма существует максимальное допустимое количество байтов заполнения, которое определяется текущим состоянием и настройками управления потоком. Если этот максимум меньше рассчитанного количества, необходимого для обеспечения выравнивания, используется максимум, и общая длина фрейма не обязательно выравнивается по 8 байтам.
- peerMaxConcurrentStreams <число> Устанавливает максимальное количество одновременных потоков для удаленного узла, как если бы был получен фрейм SETTINGS. Будет переопределено, если удаленный узел установит собственное значение для maxConcurrentStreams. По умолчанию: 100.
- maxSessionInvalidFrames <целое число> Устанавливает максимальное количество недопустимых фреймов, которые будут допускаться, прежде чем сеанс будет закрыт. По умолчанию: 1000.
- maxSessionRejectedStreams <целое число> Устанавливает максимальное количество потоков, отклоненных при создании, которые будут допускаться, прежде чем сеанс будет закрыт. Каждое отклонение связано с ошибкой NGHTTP2_ENHANCE_YOUR_CALM, которая должна указать узлу не открывать больше потоков, поэтому продолжение открытия потоков рассматривается как признак неправильно работающего узла. По умолчанию: 100.
- settings <Объект настроек HTTP/2> Начальные настройки для отправки удаленному узлу при подключении.
- streamResetBurst <число> и streamResetRate <число> Устанавливает ограничение скорости для входящего сброса потока (фрейм RST_STREAM). Для того чтобы настройки имели эффект, необходимо установить оба параметра, по умолчанию они равны 1000 и 33 соответственно.
- remoteCustomSettings <Массив> Массив целых чисел определяет типы настроек, которые включены в свойство CustomSettings полученных remoteSettings. Для получения дополнительной информации о допустимых типах настроек см. свойство CustomSettings объекта Http2Settings.
- 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().

ESMCJS

import { createServer } from 'node:http2'

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

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

server.listen(8000)

const http2 = require('node:http2')

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

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

server.listen(8000)

`http2.createSecureServer(options[, onRequestHandler])`

[История]

Версия	Изменения
v13.0.0	`PADDING_STRATEGY_CALLBACK` стал эквивалентен `PADDING_STRATEGY_ALIGNED`, а `selectPadding` удален.
v13.3.0, v12.16.0	Добавлен параметр `maxSessionRejectedStreams` со значением по умолчанию 100.
v13.3.0, v12.16.0	Добавлен параметр `maxSessionInvalidFrames` со значением по умолчанию 1000.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Добавлен параметр `unknownProtocolTimeout` со значением по умолчанию 10000.
v14.4.0, v12.18.0, v10.21.0	Добавлен параметр `maxSettings` со значением по умолчанию 32.
v10.12.0	Добавлен параметр `origins` для автоматической отправки фрейма `ORIGIN` при запуске `Http2Session`.
v8.9.3	Добавлен параметр `maxOutstandingPings` с ограничением по умолчанию 10.
v8.9.3	Добавлен параметр `maxHeaderListPairs` с ограничением по умолчанию 128 пар заголовков.
v8.4.0	Добавлен в: v8.4.0

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

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

ESMCJS

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),
}

// Создаем защищенный HTTP/2 сервер
const server = createSecureServer(options)

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

server.listen(8443)

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

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
}

// Создаем защищенный HTTP/2 сервер
const server = http2.createSecureServer(options)

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

server.listen(8443)

`http2.connect(authority[, options][, listener])`

[История]

Версия	Изменения
v13.0.0	`PADDING_STRATEGY_CALLBACK` стал эквивалентен `PADDING_STRATEGY_ALIGNED`, а `selectPadding` удален.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	Добавлен параметр `unknownProtocolTimeout` со значением по умолчанию 10000.
v14.4.0, v12.18.0, v10.21.0	Добавлен параметр `maxSettings` со значением по умолчанию 32.
v8.9.3	Добавлен параметр `maxOutstandingPings` с ограничением по умолчанию 10.
v8.9.3	Добавлен параметр `maxHeaderListPairs` с ограничением по умолчанию 128 пар заголовков.
v8.4.0	Добавлен в: v8.4.0

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

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

ESMCJS

import { connect } from 'node:http2'
const client = connect('https://localhost:1234')

/* Использование клиента */

client.close()

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

/* Использование клиента */

client.close()

`http2.constants`

Добавлено в: v8.4.0

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

Значение	Название	Константа
`0x00`	Нет ошибки	`http2.constants.NGHTTP2_NO_ERROR`
`0x01`	Ошибка протокола	`http2.constants.NGHTTP2_PROTOCOL_ERROR`
`0x02`	Внутренняя ошибка	`http2.constants.NGHTTP2_INTERNAL_ERROR`
`0x03`	Ошибка контроля потока	`http2.constants.NGHTTP2_FLOW_CONTROL_ERROR`
`0x04`	Превышено время ожидания настроек	`http2.constants.NGHTTP2_SETTINGS_TIMEOUT`
`0x05`	Поток закрыт	`http2.constants.NGHTTP2_STREAM_CLOSED`
`0x06`	Ошибка размера фрейма	`http2.constants.NGHTTP2_FRAME_SIZE_ERROR`
`0x07`	Поток отклонен	`http2.constants.NGHTTP2_REFUSED_STREAM`
`0x08`	Отмена	`http2.constants.NGHTTP2_CANCEL`
`0x09`	Ошибка сжатия	`http2.constants.NGHTTP2_COMPRESSION_ERROR`
`0x0a`	Ошибка подключения	`http2.constants.NGHTTP2_CONNECT_ERROR`
`0x0b`	Успокойтесь	`http2.constants.NGHTTP2_ENHANCE_YOUR_CALM`
`0x0c`	Неадекватная безопасность	`http2.constants.NGHTTP2_INADEQUATE_SECURITY`
`0x0d`	Требуется HTTP/1.1	`http2.constants.NGHTTP2_HTTP_1_1_REQUIRED`

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

`http2.getDefaultSettings()`

Добавлено в: v8.4.0

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

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

`http2.getPackedSettings([settings])`

Добавлено в: v8.4.0

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

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

ESMCJS

import { getPackedSettings } from 'node:http2'

const packed = getPackedSettings({ enablePush: false })

console.log(packed.toString('base64'))
// Выводит: AAIAAAAA

const http2 = require('node:http2')

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

console.log(packed.toString('base64'))
// Выводит: AAIAAAAA

`http2.getUnpackedSettings(buf)`

Добавлен в: v8.4.0

buf <Buffer> | <TypedArray> Упакованные настройки.
Возвращает: <Объект настроек HTTP/2>

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

`http2.performServerHandshake(socket[, options])`

Добавлен в: v21.7.0, v20.12.0

socket <stream.Duplex>
options <Object>
- ...: Может быть предоставлен любой параметр http2.createServer().
Возвращает: <ServerHttp2Session>

Создает сеанс сервера HTTP/2 из существующего сокета.

`http2.sensitiveHeaders`

Добавлен в: v15.0.0, v14.18.0

<symbol>

Этот символ может быть установлен как свойство объекта заголовков 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 значения объединяются с помощью '; '.
Для всех остальных заголовков значения объединяются с помощью ', '.

ESMCJS

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

const http2 = require('node: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, этот флаг устанавливается автоматически.

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

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

[История]

Версия	Изменения
v12.12.0	Настройка `maxConcurrentStreams` стала более строгой.
v8.9.3	Настройка `maxHeaderListSize` теперь строго принуждается.
v8.4.0	Добавлено в: v8.4.0

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

headerTableSize <число> Указывает максимальное количество байтов, используемых для сжатия заголовков. Минимальное допустимое значение — 0. Максимальное допустимое значение — 2-1. По умолчанию: 4096.
enablePush <булево> Указывает true, если потоки Push HTTP/2 должны быть разрешены в экземплярах 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<булево> Указывает true, если должен быть включен "Расширенный протокол подключения", определенный в RFC 8441. Эта настройка имеет смысл только если отправляется сервером. После того, как настройка enableConnectProtocol была включена для данного Http2Session, ее нельзя отключить. По умолчанию: false.
customSettings <Объект> Указывает дополнительные настройки, которые еще не реализованы в node и базовых библиотеках. Ключ объекта определяет числовое значение типа настройки (как определено в реестре "HTTP/2 SETTINGS", установленном [RFC 7540]), а значения — фактическое числовое значение настроек. Тип настройки должен быть целым числом в диапазоне от 1 до 2^16-1. Это не должен быть тип настройки, уже обрабатываемый node, т.е. в настоящее время он должен быть больше 6, хотя это и не ошибка. Значения должны быть беззнаковыми целыми числами в диапазоне от 0 до 2^32-1. В настоящее время поддерживается максимум 10 пользовательских настроек. Он поддерживается только для отправки SETTINGS или для получения значений настроек, указанных в параметрах remoteCustomSettings объекта сервера или клиента. Не смешивайте механизм customSettings для идентификатора настройки с интерфейсами для собственных обработанных настроек, если настройка станет собственной в будущей версии node.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ESMCJS

import { connect } from 'node:http2'

const client = connect('http://localhost')

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', responseHeaders => {
    // Обработка заголовков ответа
  })
  pushedStream.on('data', chunk => {
    /* обработка данных push */
  })
})

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

const http2 = require('node:http2')

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

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', responseHeaders => {
    // Обработка заголовков ответа
  })
  pushedStream.on('data', chunk => {
    /* обработка данных push */
  })
})

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

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

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

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

ESMCJS

import { createServer } from 'node:net'

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

server.listen(8000)

const net = require('node:net')

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

server.listen(8000)

HTTP/2 CONNECT прокси:

ESMCJS

import { createServer, constants } from 'node:http2'
const { NGHTTP2_REFUSED_STREAM, NGHTTP2_CONNECT_ERROR } = constants
import { connect } from 'node:net'

const proxy = createServer()
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // Принимаются только запросы CONNECT
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // Очень желательно проверить, что hostname и port являются
  // теми, к которым должен подключаться этот прокси.
  const socket = connect(auth.port, auth.hostname, () => {
    stream.respond()
    socket.pipe(stream)
    stream.pipe(socket)
  })
  socket.on('error', error => {
    stream.close(NGHTTP2_CONNECT_ERROR)
  })
})

proxy.listen(8001)

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

const proxy = http2.createServer()
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // Принимаются только запросы CONNECT
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // Очень желательно проверить, что hostname и port являются
  // теми, к которым должен подключаться этот прокси.
  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 клиент:

ESMCJS

import { connect, constants } from 'node:http2'

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

// Нельзя указывать заголовки ':path' и ':scheme'
// для запросов CONNECT, иначе будет выброшена ошибка.
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
})

req.on('response', headers => {
  console.log(headers[constants.HTTP2_HEADER_STATUS])
})
let data = ''
req.setEncoding('utf8')
req.on('data', chunk => (data += chunk))
req.on('end', () => {
  console.log(`Сервер говорит: ${data}`)
  client.close()
})
req.end('Jane')

const http2 = require('node:http2')

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

// Нельзя указывать заголовки ':path' и ':scheme'
// для запросов CONNECT, иначе будет выброшена ошибка.
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
})

req.on('response', headers => {
  console.log(headers[http2.constants.HTTP2_HEADER_STATUS])
})
let data = ''
req.setEncoding('utf8')
req.on('data', chunk => (data += chunk))
req.on('end', () => {
  console.log(`Сервер говорит: ${data}`)
  client.close()
})
req.end('Jane')

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

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

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

ESMCJS

import { createServer } from 'node:http2'
const settings = { enableConnectProtocol: true }
const server = createServer({ settings })

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

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

ESMCJS

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

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

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

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

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

ESMCJS

import { createServer } from 'node:http2'
const server = 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')
})

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

Чтобы создать смешанный сервер 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.

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

ESMCJS

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

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

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

function onRequest(req, res) {
  // Определяет, является ли запрос HTTPS или 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,
    })
  )
}

const { createSecureServer } from 'require('node:http2');
const { readFileSync } from 'require('node:fs');

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

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

function onRequest(req, res) {
  // Определяет, является ли запрос HTTPS или 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`

Добавлен в: v8.4.0

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

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

Событие: `'aborted'`

Добавлено в: v8.4.0

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

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

Событие: `'close'`

Добавлено в: v8.4.0

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

`request.aborted`

Добавлено в: v10.1.0

<boolean>

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

`request.authority`

Добавлено в: v8.4.0

<string>

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

`request.complete`

Добавлено в: v12.10.0

<boolean>

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

`request.connection`

Добавлено в: v8.4.0

Устарело с: v13.0.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте request.socket.

<net.Socket> | <tls.TLSSocket>

См. request.socket.

`request.destroy([error])`

Добавлено в: v8.4.0

error <Error>

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

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

`request.headers`

Добавлен в: v8.4.0

<Object>

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

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

// Выводит что-то вроде:
//
// { '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) // Сбой, так как заголовок :path был удален

`request.httpVersion`

Добавлен в: v8.4.0

<string>

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

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

`request.method`

Добавлен в: v8.4.0

<string>

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

`request.rawHeaders`

Добавлен в: v8.4.0

<string[]>

Необработанный список заголовков запроса/ответа точно в том виде, в котором они были получены.

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

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

// Выводит что-то вроде:
//
// [ '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`

Добавлено в: v8.4.0

<string[]>

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

`request.scheme`

Добавлено в: v8.4.0

<string>

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

`request.setTimeout(msecs, callback)`

Добавлено в: v8.4.0

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

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

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

`request.socket`

Добавлено в: v8.4.0

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

Добавлено в: v8.4.0

<Http2Stream>

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

`request.trailers`

Добавлено в: v8.4.0

<Object>

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

`request.url`

Добавлено в: v8.4.0

<string>

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

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

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

'/status?name=ryan'

Для разбора URL на его составные части можно использовать new URL():

bash

$ 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`

Добавлено в: v8.4.0

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

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

Событие: `'close'`

Добавлено в: v8.4.0

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

Событие: `'finish'`

Добавлено в: v8.4.0

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

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

`response.addTrailers(headers)`

Добавлено в: v8.4.0

headers <Object>

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

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

`response.appendHeader(name, value)`

Добавлено в: v21.7.0, v20.12.0

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

Добавляет одно значение заголовка к объекту заголовка.

Если значение является массивом, это эквивалентно многократному вызову этого метода.

Если ранее для заголовка не было значений, это эквивалентно вызову response.setHeader().

// Возвращает заголовки, включая "set-cookie: a" и "set-cookie: b"
const server = http2.createServer((req, res) => {
  res.setHeader('set-cookie', 'a')
  res.appendHeader('set-cookie', 'b')
  res.writeHead(200)
  res.end('ok')
})

`response.connection`

Добавлено в: v8.4.0

Устарело с: v13.0.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте response.socket.

<net.Socket> | <tls.TLSSocket>

См. response.socket.

`response.createPushResponse(headers, callback)`

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v8.4.0	Добавлено в: v8.4.0

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

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

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

[История]

Версия	Изменения
v10.0.0	Этот метод теперь возвращает ссылку на `ServerResponse`.
v8.4.0	Добавлено в: v8.4.0

data <строка> | <Buffer> | <Uint8Array>
encoding <строка>
callback <Функция>
Возвращает: <this>

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

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

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

`response.finished`

Добавлено в: v8.4.0

Устарело с: v13.4.0, v12.16.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте response.writableEnded.

<булево>

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

`response.getHeader(name)`

Добавлено в: v8.4.0

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

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

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

`response.getHeaderNames()`

Добавлено в: v8.4.0

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

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

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

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

`response.getHeaders()`

Добавлено в: v8.4.0

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

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

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

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

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

`response.hasHeader(name)`

Добавлено в: v8.4.0

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

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

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

`response.headersSent`

Добавлено в: v8.4.0

<boolean>

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

`response.removeHeader(name)`

Добавлено в: v8.4.0

name <строка>

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

response.removeHeader('Content-Encoding')

`response.req`

Добавлено в: v15.7.0

<http2.Http2ServerRequest>

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

`response.sendDate`

Добавлено в: v8.4.0

<булево>

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

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

`response.setHeader(name, value)`

Добавлено в: v8.4.0

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

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

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

или

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

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

// Возвращает 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])`

Добавлено в: v8.4.0

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

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

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

`response.socket`

Добавлено в: v8.4.0

<net.Socket> | <tls.TLSSocket>

Свойства 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 и сокеты для получения дополнительной информации.

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

ESMCJS

import { createServer } from 'node:http2'
const server = createServer((req, res) => {
  const ip = req.socket.remoteAddress
  const port = req.socket.remotePort
  res.end(`Ваш IP-адрес: ${ip}, порт источника: ${port}.`)
}).listen(3000)

const http2 = require('node:http2')
const server = http2
  .createServer((req, res) => {
    const ip = req.socket.remoteAddress
    const port = req.socket.remotePort
    res.end(`Ваш IP-адрес: ${ip}, порт источника: ${port}.`)
  })
  .listen(3000)

`response.statusCode`

Добавлено в: v8.4.0

<число>

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

response.statusCode = 404

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

`response.statusMessage`

Добавлено в: v8.4.0

<строка>

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

`response.stream`

Добавлено в: v8.4.0

<Http2Stream>

Объект Http2Stream, являющийся основой ответа.

`response.writableEnded`

Добавлено в: v12.9.0

<булево>

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

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

Добавлено в: v8.4.0

chunk <строка> | <Buffer> | <Uint8Array>
encoding <строка>
callback <Функция>
Возвращает: <булево>

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

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

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

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

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

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

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

`response.writeContinue()`

Добавлено в: v8.4.0

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

`response.writeEarlyHints(hints)`

Добавлено в: v18.11.0

hints <Object>

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

Пример

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

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

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

[История]

Версия	Изменения
v11.10.0, v10.17.0	Возвращает `this` из `writeHead()`, чтобы позволить цепочку вызовов с `end()`.
v8.4.0	Добавлено в: v8.4.0

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

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

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

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

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

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(), будут иметь приоритет.

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

ESMCJS

import { PerformanceObserver } from 'node:perf_hooks'

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // выведет 'http2'
  if (entry.name === 'Http2Session') {
    // Запись содержит статистику о Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Запись содержит статистику о Http2Stream
  }
})
obs.observe({ entryTypes: ['http2'] })

const { PerformanceObserver } = require('node:perf_hooks')

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // выведет 'http2'
  if (entry.name === 'Http2Session') {
    // Запись содержит статистику о Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Запись содержит статистику о Http2Stream
  }
})
obs.observe({ entryTypes: ['http2'] })

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

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

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

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

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

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

Заметка о `:authority` и `host`

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

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

HTTP/2 ​

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

Базовый API ​

Пример на стороне сервера ​

Пример на стороне клиента ​

Класс: Http2Session ​

Http2Session и сокеты ​

Событие: 'close' ​

Событие: 'connect' ​

Событие: 'error' ​

Событие: 'frameError' ​

Событие: 'goaway' ​

Событие: 'localSettings' ​

Событие: 'ping' ​

Событие: 'remoteSettings' ​

Событие: 'stream' ​

Событие: 'timeout' ​

http2session.alpnProtocol ​

http2session.close([callback]) ​

http2session.closed ​

http2session.connecting ​

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

http2session.destroyed ​

http2session.encrypted ​

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

http2session.localSettings ​

http2session.originSet ​

http2session.pendingSettingsAck ​

http2session.ping([payload, ]callback) ​

http2session.ref() ​

http2session.remoteSettings ​

http2session.setLocalWindowSize(windowSize) ​

http2session.setTimeout(msecs, callback) ​

http2session.socket ​

http2session.state ​

http2session.settings([settings][, callback]) ​

http2session.type ​

http2session.unref() ​

Класс: ServerHttp2Session ​

serverhttp2session.altsvc(alt, originOrStream) ​

Указание альтернативных служб ​

serverhttp2session.origin(...origins) ​

Класс: ClientHttp2Session ​

Событие: 'altsvc' ​

Событие: 'origin' ​

clienthttp2session.request(headers[, options]) ​

Класс: Http2Stream ​

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

Создание ​

Уничтожение ​

Событие: 'aborted' ​

Событие: 'close' ​

Событие: 'error' ​

Событие: 'frameError' ​

Событие: 'ready' ​

Событие: 'timeout' ​

Событие: 'trailers' ​

Событие: 'wantTrailers' ​

http2stream.aborted ​

http2stream.bufferSize ​

http2stream.close(code[, callback]) ​

http2stream.closed ​

http2stream.destroyed ​

http2stream.endAfterHeaders ​

http2stream.id ​

http2stream.pending ​

http2stream.priority(options) ​

http2stream.rstCode ​

http2stream.sentHeaders ​

http2stream.sentInfoHeaders ​

http2stream.sentTrailers ​

http2stream.session ​

http2stream.setTimeout(msecs, callback) ​

http2stream.state ​

http2stream.sendTrailers(headers) ​

Класс: ClientHttp2Stream ​

Событие: 'continue' ​

Событие: 'headers' ​

Событие: 'push' ​

Событие: 'response' ​

HTTP/2

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

Базовый API

Пример на стороне сервера

Пример на стороне клиента

Класс: `Http2Session`

`Http2Session` и сокеты

Событие: `'close'`

Событие: `'connect'`

Событие: `'error'`

Событие: `'frameError'`

Событие: `'goaway'`

Событие: `'localSettings'`

Событие: `'ping'`

Событие: `'remoteSettings'`

Событие: `'stream'`

Событие: `'timeout'`

`http2session.alpnProtocol`

`http2session.close([callback])`

`http2session.closed`

`http2session.connecting`

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

`http2session.destroyed`

`http2session.encrypted`

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

`http2session.localSettings`

`http2session.originSet`

`http2session.pendingSettingsAck`

`http2session.ping([payload, ]callback)`

`http2session.ref()`

`http2session.remoteSettings`

`http2session.setLocalWindowSize(windowSize)`

`http2session.setTimeout(msecs, callback)`

`http2session.socket`

`http2session.state`

`http2session.settings([settings][, callback])`

`http2session.type`

`http2session.unref()`

Класс: `ServerHttp2Session`

`serverhttp2session.altsvc(alt, originOrStream)`

Указание альтернативных служб

`serverhttp2session.origin(...origins)`

Класс: `ClientHttp2Session`

Событие: `'altsvc'`

Событие: `'origin'`

`clienthttp2session.request(headers[, options])`

Класс: `Http2Stream`

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

Создание

Уничтожение

Событие: `'aborted'`

Событие: `'close'`

Событие: `'error'`

Событие: `'frameError'`

Событие: `'ready'`

Событие: `'timeout'`

Событие: `'trailers'`

Событие: `'wantTrailers'`

`http2stream.aborted`

`http2stream.bufferSize`

`http2stream.close(code[, callback])`

`http2stream.closed`

`http2stream.destroyed`

`http2stream.endAfterHeaders`

`http2stream.id`

`http2stream.pending`

`http2stream.priority(options)`

`http2stream.rstCode`

`http2stream.sentHeaders`

`http2stream.sentInfoHeaders`

`http2stream.sentTrailers`

`http2stream.session`

`http2stream.setTimeout(msecs, callback)`

`http2stream.state`

`http2stream.sendTrailers(headers)`

Класс: `ClientHttp2Stream`

Событие: `'continue'`

Событие: `'headers'`

Событие: `'push'`

Событие: `'response'`