QUIC¶
Стабильность: 1 – Экспериментальная
1.0 — ранняя разработка. Возможность ещё не завершена и может существенно измениться. Эта возможность не подпадает под правила семантического версионирования.
Модуль node:quic реализует протокол QUIC. Чтобы им пользоваться, запустите Node.js с опцией --experimental-quic:
1 | |
1 | |
Модуль доступен только в схеме node:.
quic.connect(address[, options])¶
address<string>|<net.SocketAddress>options<quic.SessionOptions>- Возвращает:
<Promise>промис с quic.QuicSession
Инициирует новую клиентскую сессию.
1 2 3 4 5 6 7 8 9 | |
По умолчанию каждый вызов connect(...) создаёт новый локальный экземпляр QuicEndpoint, привязанный к новому случайному локальному IP-порту. Чтобы задать точный локальный адрес или мультиплексировать несколько сессий QUIC через один локальный порт, передайте опцию endpoint со значением QuicEndpoint или EndpointOptions.
1 2 3 4 5 6 7 | |
quic.listen(onsession,[options])¶
onsession<quic.OnSessionCallback>options<quic.SessionOptions>- Возвращает:
<Promise>промис с quic.QuicEndpoint
Настраивает endpoint на прослушивание как сервер. Когда удалённый пир инициирует новую сессию, вызывается переданный callback onsession с созданной сессией.
1 2 3 4 5 6 7 8 9 10 11 | |
По умолчанию каждый вызов listen(...) создаёт новый локальный QuicEndpoint, привязанный к новому случайному локальному IP-порту. Чтобы задать точный локальный адрес или мультиплексировать несколько сессий QUIC через один локальный порт, передайте опцию endpoint со значением QuicEndpoint или EndpointOptions.
Один QuicEndpoint можно настроить на прослушивание как сервер не более одного раза.
Класс: QuicEndpoint¶
QuicEndpoint инкапсулирует локальную привязку UDP-порта для QUIC. Может использоваться и как клиент, и как сервер.
new QuicEndpoint([options])¶
options<quic.EndpointOptions>
endpoint.address¶
- Тип:
<net.SocketAddress>| undefined
Локальный UDP-адрес сокета, к которому привязан endpoint, если есть.
Если endpoint сейчас не привязан, значение будет undefined. Только для чтения.
endpoint.busy¶
- Тип:
<boolean>
Если endpoint.busy равен true, endpoint временно отклоняет создание новых сессий. Чтение и запись.
1 2 3 4 5 | |
Свойство busy полезно при высокой нагрузке на endpoint, когда нужно временно отклонять новые сессии, пока он не разгрузится.
endpoint.close()¶
- Возвращает:
<Promise>
Корректно закрывает endpoint. Endpoint закроется и уничтожится, когда закроются все текущие сессии. После вызова новые сессии отклоняются.
Возвращает промис, выполняющийся после уничтожения endpoint.
endpoint.closed¶
- Тип:
<Promise>
Промис, выполняющийся после уничтожения endpoint. Это тот же промис, что возвращает endpoint.close(). Только для чтения.
endpoint.closing¶
- Тип:
<boolean>
true, если вызван endpoint.close() и закрытие endpoint ещё не завершилось. Только для чтения.
endpoint.destroy([error])¶
error<any>
Принудительно закрывает endpoint, немедленно закрывая все открытые сессии.
endpoint.destroyed¶
- Тип:
<boolean>
true, если вызван endpoint.destroy(). Только для чтения.
endpoint.setSNIContexts(entries[, options])¶
entries<object>Объект «имя хоста — параметры TLS-идентичности». В каждой записи должны бытьkeysиcerts.options<object>replace<boolean>Еслиtrue, заменяет всю карту SNI. Еслиfalse(по умолчанию), объединяет записи с существующей картой.
Заменяет или обновляет TLS-контексты SNI для этого endpoint. Позволяет менять TLS-идентичность (ключ/сертификат) для имён хостов без перезапуска endpoint. Существующие сессии не затрагиваются — обновлённые контексты используют только новые сессии.
1 2 3 4 5 6 7 8 | |
endpoint.stats¶
Статистика, собранная для активной сессии. Только для чтения.
endpoint[Symbol.asyncDispose]()¶
Вызывает endpoint.close() и возвращает промис, выполняющийся после закрытия endpoint.
Класс: QuicEndpoint.Stats¶
Представление собранной статистики для endpoint.
endpointStats.createdAt¶
- Тип:
<bigint>Метка времени создания endpoint. Только для чтения.
endpointStats.destroyedAt¶
- Тип:
<bigint>Метка времени уничтожения endpoint. Только для чтения.
endpointStats.bytesReceived¶
- Тип:
<bigint>Общее число байт, полученных этим endpoint. Только для чтения.
endpointStats.bytesSent¶
- Тип:
<bigint>Общее число байт, отправленных этим endpoint. Только для чтения.
endpointStats.packetsReceived¶
- Тип:
<bigint>Общее число успешно принятых этим endpoint QUIC-пакетов. Только для чтения.
endpointStats.packetsSent¶
- Тип:
<bigint>Общее число успешно отправленных этим endpoint QUIC-пакетов. Только для чтения.
endpointStats.serverSessions¶
- Тип:
<bigint>Общее число сессий, инициированных пиром и принятых этим endpoint. Только для чтения.
endpointStats.clientSessions¶
- Тип:
<bigint>Общее число сессий, инициированных этим endpoint. Только для чтения.
endpointStats.serverBusyCount¶
- Тип:
<bigint>Сколько раз начальный пакет был отклонён из-за пометки endpoint как занятого. Только для чтения.
endpointStats.retryCount¶
- Тип:
<bigint>Общее число попыток QUIC retry на этом endpoint. Только для чтения.
endpointStats.versionNegotiationCount¶
- Тип:
<bigint>Общее число сессий, отклонённых из-за несовпадения версии QUIC. Только для чтения.
endpointStats.statelessResetCount¶
- Тип:
<bigint>Общее число обработанных этим endpoint stateless reset. Только для чтения.
endpointStats.immediateCloseCount¶
- Тип:
<bigint>Общее число сессий, закрытых до завершения рукопожатия. Только для чтения.
Класс: QuicSession¶
QuicSession представляет локальную сторону QUIC-соединения.
session.close()¶
- Возвращает:
<Promise>
Инициирует корректное закрытие сессии. Уже открытые потоки могут завершиться, новые не открываются. Когда все потоки закроются, сессия будет уничтожена. Промис выполнится после уничтожения сессии.
session.closed¶
- Тип:
<Promise>
Промис, выполняющийся после уничтожения сессии.
session.destroy([error])¶
error<any>
Немедленно уничтожает сессию. Все потоки уничтожаются, сессия закрывается.
session.destroyed¶
- Тип:
<boolean>
true, если вызван session.destroy(). Только для чтения.
session.endpoint¶
- Тип:
<quic.QuicEndpoint>
Конечная точка, создавшая эту сессию. Только для чтения.
session.onstream¶
Вызывается при инициации нового потока удалённым пиром. Чтение и запись.
session.ondatagram¶
Вызывается при получении новой датаграммы от удалённого пира. Чтение и запись.
session.ondatagramstatus¶
Вызывается при изменении статуса датаграммы. Чтение и запись.
session.onpathvalidation¶
Вызывается при обновлении проверки пути. Чтение и запись.
session.onsessionticket¶
Вызывается при получении нового session ticket. Чтение и запись.
session.onversionnegotiation¶
Вызывается при начале согласования версии. Чтение и запись.
session.onhandshake¶
Вызывается при завершении TLS-рукопожатия. Чтение и запись.
session.createBidirectionalStream([options])¶
options<Object>body<ArrayBuffer>|<ArrayBufferView>|<Blob>sendOrder<number>
- Возвращает:
<Promise>с quic.QuicStream
Открывает новый двунаправленный поток. Если опция body не указана, исходящий поток будет полузакрыт.
session.createUnidirectionalStream([options])¶
options<Object>body<ArrayBuffer>|<ArrayBufferView>|<Blob>sendOrder<number>
- Возвращает:
<Promise>с quic.QuicStream
Открывает новый однонаправленный поток. Если опция body не указана, исходящий поток будет закрыт.
session.path¶
- Тип:
<Object>| undefinedlocal<net.SocketAddress>remote<net.SocketAddress>
Локальный и удалённый адреса сокета, связанные с сессией. Только для чтения.
session.sendDatagram(datagram)¶
datagram<string>|<ArrayBufferView>- Возвращает:
<bigint>
Отправляет ненадёжную датаграмму удалённому пиру, возвращая идентификатор датаграммы. Если полезная нагрузка задана как ArrayBufferView, владение этим представлением передаётся нижележащему потоку.
session.stats¶
Текущая статистика сессии. Только для чтения.
session.updateKey()¶
Инициирует обновление ключа для сессии.
session[Symbol.asyncDispose]()¶
Вызывает session.close() и возвращает промис, выполняющийся после закрытия сессии.
Класс: QuicSession.Stats¶
sessionStats.createdAt¶
- Тип:
<bigint>
sessionStats.closingAt¶
- Тип:
<bigint>
sessionStats.handshakeCompletedAt¶
- Тип:
<bigint>
sessionStats.handshakeConfirmedAt¶
- Тип:
<bigint>
sessionStats.bytesReceived¶
- Тип:
<bigint>
sessionStats.bytesSent¶
- Тип:
<bigint>
sessionStats.bidiInStreamCount¶
- Тип:
<bigint>
sessionStats.bidiOutStreamCount¶
- Тип:
<bigint>
sessionStats.uniInStreamCount¶
- Тип:
<bigint>
sessionStats.uniOutStreamCount¶
- Тип:
<bigint>
sessionStats.maxBytesInFlights¶
- Тип:
<bigint>
sessionStats.bytesInFlight¶
- Тип:
<bigint>
sessionStats.blockCount¶
- Тип:
<bigint>
sessionStats.cwnd¶
- Тип:
<bigint>
sessionStats.latestRtt¶
- Тип:
<bigint>
sessionStats.minRtt¶
- Тип:
<bigint>
sessionStats.rttVar¶
- Тип:
<bigint>
sessionStats.smoothedRtt¶
- Тип:
<bigint>
sessionStats.ssthresh¶
- Тип:
<bigint>
sessionStats.datagramsReceived¶
- Тип:
<bigint>
sessionStats.datagramsSent¶
- Тип:
<bigint>
sessionStats.datagramsAcknowledged¶
- Тип:
<bigint>
sessionStats.datagramsLost¶
- Тип:
<bigint>
Класс: QuicStream¶
stream.closed¶
- Тип:
<Promise>
Промис, выполняющийся после полного закрытия потока.
stream.destroy([error])¶
error<any>
Немедленно и аварийно уничтожает поток.
stream.destroyed¶
- Тип:
<boolean>
true, если вызван stream.destroy().
stream.direction¶
- Тип:
<string>Одно из значений:'bidi'или'uni'.
Направленность потока. Только для чтения.
stream.id¶
- Тип:
<bigint>
Идентификатор потока. Только для чтения.
stream.onblocked¶
Вызывается, когда поток заблокирован. Чтение и запись.
stream.onreset¶
Вызывается при сбросе потока. Чтение и запись.
stream.readable¶
- Тип:
<ReadableStream>
stream.session¶
- Тип:
<quic.QuicSession>
Сессия, создавшая этот поток. Только для чтения.
stream.stats¶
Текущая статистика потока. Только для чтения.
Класс: QuicStream.Stats¶
streamStats.ackedAt¶
- Тип:
<bigint>
streamStats.bytesReceived¶
- Тип:
<bigint>
streamStats.bytesSent¶
- Тип:
<bigint>
streamStats.createdAt¶
- Тип:
<bigint>
streamStats.destroyedAt¶
- Тип:
<bigint>
streamStats.finalSize¶
- Тип:
<bigint>
streamStats.isConnected¶
- Тип:
<bigint>
streamStats.maxOffset¶
- Тип:
<bigint>
streamStats.maxOffsetAcknowledged¶
- Тип:
<bigint>
streamStats.maxOffsetReceived¶
- Тип:
<bigint>
streamStats.openedAt¶
- Тип:
<bigint>
streamStats.receivedAt¶
- Тип:
<bigint>
Типы¶
Тип: EndpointOptions¶
- Тип:
<Object>
Параметры конфигурации endpoint, передаваемые при создании QuicEndpoint.
endpointOptions.address¶
- Тип:
<net.SocketAddress>|<string>Локальный UDP-адрес и порт для привязки endpoint.
Если не указано, endpoint привяжется к IPv4 localhost на случайном порту.
endpointOptions.addressLRUSize¶
Конечная точка хранит внутренний кэш проверенных адресов сокетов для оптимизации. Эта опция задаёт максимальное число адресов в кэше. Расширенная опция, обычно не требуется.
endpointOptions.ipv6Only¶
- Тип:
<boolean>
При true endpoint привязывается только к IPv6-адресам.
endpointOptions.maxConnectionsPerHost¶
Максимальное число одновременных сессий на один удалённый адрес пира.
endpointOptions.maxConnectionsTotal¶
Максимальное общее число одновременных сессий.
endpointOptions.maxRetries¶
Максимальное число попыток QUIC retry на один удалённый адрес пира.
endpointOptions.maxStatelessResetsPerHost¶
Максимальное число stateless reset на один удалённый адрес пира.
endpointOptions.retryTokenExpiration¶
Время, в течение которого считается действительным QUIC retry token.
endpointOptions.resetTokenSecret¶
- Тип:
<ArrayBufferView>
16-байтовый секрет для генерации QUIC retry token.
endpointOptions.tokenExpiration¶
Время, в течение которого считается действительным QUIC token.
endpointOptions.tokenSecret¶
- Тип:
<ArrayBufferView>
16-байтовый секрет для генерации QUIC token.
endpointOptions.udpReceiveBufferSize¶
- Тип:
<number>
endpointOptions.udpSendBufferSize¶
- Тип:
<number>
endpointOptions.udpTTL¶
- Тип:
<number>
endpointOptions.validateAddress¶
- Тип:
<boolean>
При true endpoint должен проверять адреса пиров через retry-пакеты при установлении нового соединения.
Тип: SessionOptions¶
sessionOptions.alpn¶
Идентификатор(ы) ALPN (согласование протокола прикладного уровня).
Для клиентских сессий — одна строка с желаемым протоколом (например 'h3').
Для серверных сессий — массив имён протоколов в порядке предпочтения, которые поддерживает сервер (например ['h3', 'h3-29']). При TLS-рукопожатии сервер выбирает первый протокол из своего списка, который поддерживает и клиент.
Согласованный ALPN определяет прикладную реализацию для сессии. Варианты 'h3' и 'h3-*' выбирают HTTP/3; остальные значения — реализацию по умолчанию.
По умолчанию: 'h3'
sessionOptions.ca (только клиент)¶
Сертификаты центра сертификации (CA) для клиентских сессий. Для серверных сертификаты CA задаются по идентичности в карте sessionOptions.sni.
sessionOptions.cc¶
- Тип:
<string>
Алгоритм контроля перегрузки; должен быть одним из 'reno', 'cubic' или 'bbr'.
Расширенная опция, обычно не требуется.
sessionOptions.certs (только клиент)¶
TLS-сертификаты для клиентских сессий. Для серверных сессий сертификаты задаются по идентичности в sessionOptions.sni.
sessionOptions.ciphers¶
- Тип:
<string>
Список поддерживаемых шифров TLS 1.3.
sessionOptions.crl (только клиент)¶
Списки отзыва сертификатов (CRL) для клиентских сессий. Для серверных CRL задаются по идентичности в sessionOptions.sni.
sessionOptions.groups¶
- Тип:
<string>
Список групп шифров TLS 1.3.
sessionOptions.keylog¶
- Тип:
<boolean>
true — включить вывод TLS key logging.
sessionOptions.keys (только клиент)¶
- Тип:
<KeyObject>|<KeyObject[]>
Криптографические ключи TLS для клиентских сессий. Для серверных ключи задаются по идентичности в sessionOptions.sni.
sessionOptions.maxPayloadSize¶
Максимальный размер полезной нагрузки UDP-пакета.
sessionOptions.maxStreamWindow¶
Максимальный размер окна управления потоком.
sessionOptions.maxWindow¶
Максимальный размер окна управления сессией.
sessionOptions.minVersion¶
- Тип:
<number>
Минимально допустимый номер версии QUIC. Расширенная опция, обычно не требуется.
sessionOptions.preferredAddressPolicy¶
- Тип:
<string>Одно из'use','ignore'или'default'.
Если удалённый пир объявляет preferred address, опция задаёт, использовать его или игнорировать.
sessionOptions.qlog¶
- Тип:
<boolean>
true — включить вывод qlog.
sessionOptions.sessionTicket¶
- Тип:
<ArrayBufferView>Билет сессии для возобновления сессии 0-RTT.
sessionOptions.handshakeTimeout¶
Максимальное время в миллисекундах на TLS-рукопожатие до тайм-аута.
sessionOptions.servername (только клиент)¶
- Тип:
<string>
Имя сервера пира (SNI). По умолчанию 'localhost'.
sessionOptions.sni (только сервер)¶
- Тип:
<Object>
Объект «имя хоста — параметры TLS-идентичности» для поддержки указания имени сервера (SNI). Обязателен для серверных сессий. Специальный ключ '*' задаёт идентичность по умолчанию, если не подошло другое имя. В записи могут быть:
keys<KeyObject>|<KeyObject[]>Закрытые ключи TLS. Обязательно.certs<ArrayBuffer>|<ArrayBufferView>|<ArrayBuffer[]>|<ArrayBufferView[]>Сертификаты TLS. Обязательно.ca<ArrayBuffer>|<ArrayBufferView>|<ArrayBuffer[]>|<ArrayBufferView[]>Необязательные переопределения CA.crl<ArrayBuffer>|<ArrayBufferView>|<ArrayBuffer[]>|<ArrayBufferView[]>Необязательные списки отзыва сертификатов.verifyPrivateKey<boolean>Проверять закрытый ключ. По умолчанию:false.
1 2 3 4 5 6 7 | |
Общие параметры TLS (ciphers, groups, keylog, verifyClient и др.) задаются на верхнем уровне опций сессии и применяются ко всем идентичностям. Каждая запись SNI переопределяет только поля сертификата.
Карту SNI можно заменить во время выполнения через endpoint.setSNIContexts(): карта атомарно меняется для новых сессий, существующие продолжают использовать прежнюю идентичность.
sessionOptions.tlsTrace¶
- Тип:
<boolean>
true — включить трассировку TLS.
sessionOptions.transportParams¶
Параметры транспорта QUIC для сессии.
sessionOptions.unacknowledgedPacketThreshold¶
Максимальное число неподтверждённых пакетов, допустимое для сессии.
sessionOptions.verifyClient¶
- Тип:
<boolean>
true — требовать проверку клиентского TLS-сертификата.
sessionOptions.verifyPrivateKey (только клиент)¶
- Тип:
<boolean>
true — требовать проверку закрытого ключа для клиентских сессий. Для серверных эта опция задаётся по идентичности в sessionOptions.sni.
sessionOptions.version¶
- Тип:
<number>
Номер версии QUIC. Расширенная опция, обычно не требуется.
Тип: TransportParams¶
transportParams.preferredAddressIpv4¶
- Тип:
<net.SocketAddress>Предпочитаемый объявляемый IPv4-адрес.
transportParams.preferredAddressIpv6¶
- Тип:
<net.SocketAddress>Предпочитаемый объявляемый IPv6-адрес.
transportParams.initialMaxStreamDataBidiLocal¶
transportParams.initialMaxStreamDataBidiRemote¶
transportParams.initialMaxStreamDataUni¶
transportParams.initialMaxData¶
transportParams.initialMaxStreamsBidi¶
transportParams.initialMaxStreamsUni¶
transportParams.maxIdleTimeout¶
transportParams.activeConnectionIDLimit¶
transportParams.ackDelayExponent¶
transportParams.maxAckDelay¶
transportParams.maxDatagramFrameSize¶
Обратные вызовы¶
Callback: OnSessionCallback¶
this<quic.QuicEndpoint>session<quic.QuicSession>
Вызывается при инициации новой сессии удалённым пиром.
Callback: OnStreamCallback¶
this<quic.QuicSession>stream<quic.QuicStream>
Callback: OnDatagramCallback¶
this<quic.QuicSession>datagram<Uint8Array>early<boolean>
Callback: OnDatagramStatusCallback¶
this<quic.QuicSession>id<bigint>status<string>Одно из значений:'lost'или'acknowledged'.
Callback: OnPathValidationCallback¶
this<quic.QuicSession>result<string>Одно из значений:'success','failure'или'aborted'.newLocalAddress<net.SocketAddress>newRemoteAddress<net.SocketAddress>oldLocalAddress<net.SocketAddress>oldRemoteAddress<net.SocketAddress>preferredAddress<boolean>
Callback: OnSessionTicketCallback¶
this<quic.QuicSession>ticket<Object>
Callback: OnVersionNegotiationCallback¶
this<quic.QuicSession>version<number>requestedVersions<number[]>supportedVersions<number[]>
Callback: OnHandshakeCallback¶
this<quic.QuicSession>sni<string>alpn<string>cipher<string>cipherVersion<string>validationErrorReason<string>validationErrorCode<number>earlyDataAccepted<boolean>
Callback: OnBlockedCallback¶
this<quic.QuicStream>
Callback: OnStreamErrorCallback¶
this<quic.QuicStream>error<any>
Диагностические каналы¶
Channel: quic.endpoint.created¶
endpoint<quic.QuicEndpoint>config<quic.EndpointOptions>
Channel: quic.endpoint.listen¶
endpoint<quic.QuicEndpoint>options<quic.SessionOptions>
Channel: quic.endpoint.closing¶
endpoint<quic.QuicEndpoint>hasPendingError<boolean>
Channel: quic.endpoint.closed¶
endpoint<quic.QuicEndpoint>
Channel: quic.endpoint.error¶
endpoint<quic.QuicEndpoint>error<any>
Channel: quic.endpoint.busy.change¶
endpoint<quic.QuicEndpoint>busy<boolean>
