Перейти к содержанию

QUIC

latest

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

1.0 — ранняя разработка. Возможность ещё не завершена и может существенно измениться. Эта возможность не подпадает под правила семантического версионирования.

Модуль node:quic реализует протокол QUIC. Чтобы им пользоваться, запустите Node.js с опцией --experimental-quic:

1
import quic from 'node:quic';

1
const quic = require('node:quic');

Модуль доступен только в схеме node:.

quic.connect(address[, options])

Инициирует новую клиентскую сессию.

1
2
3
4
5
6
7
8
9
import { connect } from 'node:quic';
import { Buffer } from 'node:buffer';

const enc = new TextEncoder();
const alpn = 'foo';
const client = await connect('123.123.123.123:8888', { alpn });
await client.createUnidirectionalStream({
  body: enc.encode('hello world'),
});

По умолчанию каждый вызов connect(...) создаёт новый локальный экземпляр QuicEndpoint, привязанный к новому случайному локальному IP-порту. Чтобы задать точный локальный адрес или мультиплексировать несколько сессий QUIC через один локальный порт, передайте опцию endpoint со значением QuicEndpoint или EndpointOptions.

1
2
3
4
5
6
7
import { QuicEndpoint, connect } from 'node:quic';

const endpoint = new QuicEndpoint({
  address: '127.0.0.1:1234',
});

const client = await connect('123.123.123.123:8888', { endpoint });

quic.listen(onsession,[options])

  • onsession {quic.OnSessionCallback}
  • options
  • Возвращает: промис с quic.QuicEndpoint

Настраивает endpoint на прослушивание как сервер. Когда удалённый пир инициирует новую сессию, вызывается переданный callback onsession с созданной сессией.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { listen } from 'node:quic';

const endpoint = await listen((session) => {
  // ... обработка сессии
});

// Закрытие endpoint позволяет завершить уже открытые на момент close
// сессии естественным образом и не принимать новые.
// Когда все сессии завершатся, endpoint будет уничтожен.
// Вызов возвращает промис, который выполнится после уничтожения endpoint.
await endpoint.close();

По умолчанию каждый вызов listen(...) создаёт новый локальный QuicEndpoint, привязанный к новому случайному локальному IP-порту. Чтобы задать точный локальный адрес или мультиплексировать несколько сессий QUIC через один локальный порт, передайте опцию endpoint со значением QuicEndpoint или EndpointOptions.

Один QuicEndpoint можно настроить на прослушивание как сервер не более одного раза.

Класс: QuicEndpoint

QuicEndpoint инкапсулирует локальную привязку UDP-порта для QUIC. Может использоваться и как клиент, и как сервер.

new QuicEndpoint([options])

  • options

endpoint.address

  • Тип: | undefined

Локальный UDP-адрес сокета, к которому привязан endpoint, если есть.

Если endpoint сейчас не привязан, значение будет undefined. Только для чтения.

endpoint.busy

  • Тип:

Если endpoint.busy равен true, endpoint временно отклоняет создание новых сессий. Чтение и запись.

1
2
3
4
5
// Пометить endpoint занятым — новые сессии не принимаются
endpoint.busy = true;

// Снять занятость — новые сессии снова разрешены
endpoint.busy = false;

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

endpoint.close()

  • Возвращает:

Корректно закрывает endpoint. Endpoint закроется и уничтожится, когда закроются все текущие сессии. После вызова новые сессии отклоняются.

Возвращает промис, выполняющийся после уничтожения endpoint.

endpoint.closed

  • Тип:

Промис, выполняющийся после уничтожения endpoint. Это тот же промис, что возвращает endpoint.close(). Только для чтения.

endpoint.closing

  • Тип:

true, если вызван endpoint.close() и закрытие endpoint ещё не завершилось. Только для чтения.

endpoint.destroy([error])

  • error {any}

Принудительно закрывает endpoint, немедленно закрывая все открытые сессии.

endpoint.destroyed

  • Тип:

true, если вызван endpoint.destroy(). Только для чтения.

endpoint.setSNIContexts(entries[, options])

  • entries {object} Объект «имя хоста — параметры TLS-идентичности». В каждой записи должны быть keys и certs.
  • options {object}
  • replace Если true, заменяет всю карту SNI. Если false (по умолчанию), объединяет записи с существующей картой.

Заменяет или обновляет TLS-контексты SNI для этого endpoint. Позволяет менять TLS-идентичность (ключ/сертификат) для имён хостов без перезапуска endpoint. Существующие сессии не затрагиваются — обновлённые контексты используют только новые сессии.

1
2
3
4
5
6
7
8
endpoint.setSNIContexts({
  'api.example.com': { keys: [newApiKey], certs: [newApiCert] },
});

// Заменить всю карту SNI
endpoint.setSNIContexts({
  'api.example.com': { keys: [newApiKey], certs: [newApiCert] },
}, { replace: true });

endpoint.stats

  • Тип:

Статистика, собранная для активной сессии. Только для чтения.

endpoint[Symbol.asyncDispose]()

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

Класс: QuicEndpoint.Stats

Представление собранной статистики для endpoint.

endpointStats.createdAt

  • Тип: Метка времени создания endpoint. Только для чтения.

endpointStats.destroyedAt

  • Тип: Метка времени уничтожения endpoint. Только для чтения.

endpointStats.bytesReceived

  • Тип: Общее число байт, полученных этим endpoint. Только для чтения.

endpointStats.bytesSent

  • Тип: Общее число байт, отправленных этим endpoint. Только для чтения.

endpointStats.packetsReceived

  • Тип: Общее число успешно принятых этим endpoint QUIC-пакетов. Только для чтения.

endpointStats.packetsSent

  • Тип: Общее число успешно отправленных этим endpoint QUIC-пакетов. Только для чтения.

endpointStats.serverSessions

  • Тип: Общее число сессий, инициированных пиром и принятых этим endpoint. Только для чтения.

endpointStats.clientSessions

  • Тип: Общее число сессий, инициированных этим endpoint. Только для чтения.

endpointStats.serverBusyCount

  • Тип: Сколько раз начальный пакет был отклонён из-за пометки endpoint как занятого. Только для чтения.

endpointStats.retryCount

  • Тип: Общее число попыток QUIC retry на этом endpoint. Только для чтения.

endpointStats.versionNegotiationCount

  • Тип: Общее число сессий, отклонённых из-за несовпадения версии QUIC. Только для чтения.

endpointStats.statelessResetCount

  • Тип: Общее число обработанных этим endpoint stateless reset. Только для чтения.

endpointStats.immediateCloseCount

  • Тип: Общее число сессий, закрытых до завершения рукопожатия. Только для чтения.

Класс: QuicSession

QuicSession представляет локальную сторону QUIC-соединения.

session.close()

  • Возвращает:

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

session.closed

  • Тип:

Промис, выполняющийся после уничтожения сессии.

session.destroy([error])

  • error {any}

Немедленно уничтожает сессию. Все потоки уничтожаются, сессия закрывается.

session.destroyed

  • Тип:

true, если вызван session.destroy(). Только для чтения.

session.endpoint

  • Тип:

Endpoint, создавший эту сессию. Только для чтения.

session.onstream

  • Тип: {quic.OnStreamCallback}

Вызывается при инициации нового потока удалённым пиром. Чтение и запись.

session.ondatagram

  • Тип: {quic.OnDatagramCallback}

Вызывается при получении новой датаграммы от удалённого пира. Чтение и запись.

session.ondatagramstatus

  • Тип: {quic.OnDatagramStatusCallback}

Вызывается при изменении статуса датаграммы. Чтение и запись.

session.onpathvalidation

  • Тип: {quic.OnPathValidationCallback}

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

session.onsessionticket

  • Тип: {quic.OnSessionTicketCallback}

Вызывается при получении нового session ticket. Чтение и запись.

session.onversionnegotiation

  • Тип: {quic.OnVersionNegotiationCallback}

Вызывается при начале согласования версии. Чтение и запись.

session.onhandshake

  • Тип: {quic.OnHandshakeCallback}

Вызывается при завершении TLS-рукопожатия. Чтение и запись.

session.createBidirectionalStream([options])

Комментарии