The 'node:quic' module provides an implementation of the QUIC protocol.\nTo access it, start Node.js with the --experimental-quic option and:
import quic from 'node:quic';\nconst quic = require('node:quic');\nThe module is only available under the node: scheme.
The quic module provides APIs for creating QUIC clients and servers.
The QUIC and HTTP/3 protocols are defined by a collection of RFCs produced\nprimarily by the IETF QUIC Working Group. A familiarity with these documents\nis strongly recommended for users of this module.
\nCore QUIC transport:
\nCore HTTP/3:
\n\nQUIC extensions:
\nHTTP/3 extensions:
\nOperational and informational:
\nThe quic module is built around three core abstractions:
QuicEndpoint: represents the local UDP socket binding for QUIC. It is\nused to send and receive QUIC packets and can be shared across multiple\nsessions. A single endpoint can be used as both a client and a server\nsimultaneously.
QuicSession: represents a QUIC connection between the local endpoint and\na remote peer. A session is created either by initiating a connection to a\nremote peer using quic.connect() or by accepting an incoming connection\nfrom a remote peer via quic.listen().
QuicStream: represents a QUIC stream within a session. Streams are\ncreated by either local or remote peers and can be bidirectional or\nunidirectional.
Unlike traditional TCP-based protocols, QUIC \"connections\" are not inherently\ntied to a specific local port / remote port pair. A session is initiated via\na QUIC endpoint but may be migrated to a different local or remote address\nover its lifetime, outlive the endpoint that created it, and may even be\nassociated with multiple endpoints simultaneously. This flexibility allows for\nadvanced use cases such as connection migration, multi-homing, and load balancing.\nMost often, however, a simple one-to-one relationship between endpoint and session\nis sufficient.
", "modules": [ { "textRaw": "Integrated TLS 1.3", "name": "integrated_tls_1.3", "type": "module", "desc": "The QUIC protocol integrates TLS 1.3 directly into the protocol for connection\nestablishment and security. The quic module's API reflects this integration\nby exposing TLS-related information and configuration options. It is currently\nnot possible to use QUIC without TLS or to use a different version of TLS.
Every QUIC session starts with the client and server performing a TLS handshake\nto negotiate the application protocol (via ALPN), authenticate the server (and\noptionally the client), exchange transport parameters, and establish shared keys\nfor encryption.
", "displayName": "Integrated TLS 1.3" }, { "textRaw": "Applications", "name": "applications", "type": "module", "desc": "Every QuicSession is associated with a single application protocol, negotiated\nvia ALPN during the TLS handshake. The quic module is designed to be\napplication-agnostic in general but includes built-in support for HTTP/3 as a\nspecific application protocol. When using HTTP/3, the quic module provides\nadditional APIs for handling HTTP/3-specific features such as headers, trailers,\nand prioritization. For other application protocols, users can implement their\nown message framing and multiplexing on top of the core QUIC transport features.
When initiating a TLS handshake, the client will include a list of supported\nALPN protocols in the ClientHello. The server selects one of these protocols\n(if any) and includes it in the ServerHello. The negotiated protocol determines\nhow the QuicSession and QuicStream APIs behave. For example, when the h3\nprotocol is negotiated for HTTP/3, the QuicSession and QuicStream will support\nHTTP/3-specific features.
Currently, the quic module only supports HTTP/3 as a built-in application protocol.\nAll other protocols must be implemented by the user on top of the provided JavaScript\nAPI.
The QUIC API is designed to be flexible and highly configurable to support a wide\nrange of use cases. Users can configure various aspects of the QUIC transport,\nTLS handshake, and application behavior via options passed to the quic.connect()\nand quic.listen() functions, as well as dynamically on QuicEndpoint and\nQuicSession instances. The API also provides access to detailed statistics and\nevents for monitoring and debugging.
QUIC transport parameters are exchanged during the TLS handshake to negotiate\nvarious transport-level settings such as maximum stream counts, idle timeouts,\nand datagram support. The quic module allows users to configure the transport\nparameters their endpoint advertises to peers, as well as access the transport\nparameters advertised by peers. These configure the capabilities and limits of\nthe QUIC connection in coordination with the peer.
A rich set of local settings is also available for configuring the behavior of\nthe local endpoint and sessions. These include settings for connection limits,\ncongestion control, stream prioritization, and more.
", "displayName": "Configuration" }, { "textRaw": "Callbacks and Promises", "name": "callbacks_and_promises", "type": "module", "desc": "The quic module uses a combination of callbacks and promises for asynchronous\noperations. For example, initiating a connection with quic.connect() returns\na promise for the established session, while incoming sessions on the server\nside are handled via a callback passed to quic.listen(). Within a session,\nevents such as incoming streams, datagrams, and session state changes are handled\nvia callbacks on the QuicSession instance. Promises are used for operations\nthat have a clear completion point, such as completion of the TLS handshake or\ngraceful closure of a session.
All callbacks are invoked synchronously and may either return synchronously or\nreturn a promise. If a callback returns a promise that rejects, or throws an error,\nthe object will be destroyed with the error as the reason if an onerror callback\nis not specified.
Streams are the primary data-carrying abstraction in QUIC. A stream can be\ninitiated by either the local endpoint or the remote peer once a session is\nestablished.
\nStreams can be either bidirectional (data flows in both directions) or\nunidirectional (data flows in only one direction). The quic module provides\nseparate APIs for creating each kind:\nsession.createBidirectionalStream() and\nsession.createUnidirectionalStream(). Streams initiated by a remote\npeer are delivered via the session.onstream callback.
There are two ways to write data to a stream:
\nbody option when creating the stream (or call\nstream.setBody()). The body can be a string, ArrayBuffer,\nArrayBufferView, Blob, FileHandle, AsyncIterable, sync Iterable,\nor Promise resolving to any of these. A null body closes the writable\nside immediately. This is the simplest approach when the data is available\nup front or can be expressed as an iterable.stream.writer to push data incrementally. The\nwriter exposes synchronous methods (writeSync(), writevSync(),\nendSync()) that return immediately, as well as async equivalents\n(write(), writev(), end()) that wait for drain when backpressured.\nwriteSync() returns false when the write buffer is full; the caller\nshould wait for drain before retrying.These two approaches are mutually exclusive for a given stream.
\nReading is done by iterating the stream as an async iterable. Each iteration\nyields a batch of Uint8Array chunks:
for await (const chunks of stream) {\n for (const chunk of chunks) {\n // Process each Uint8Array chunk\n }\n}\nOnly one async iterator can be obtained per stream. The stream is also\ncompatible with node:stream/iter utilities such as Stream.bytes(),\nStream.text(), and Stream.pipeTo().
In addition to streams, QUIC supports unreliable datagrams (RFC 9221) for\nuse cases that require low-latency, best-effort messaging.
\nDatagram support is enabled at two levels. At the QUIC transport level, both\npeers must advertise a non-zero maxDatagramFrameSize transport parameter\nduring the handshake. For HTTP/3 sessions, both peers must additionally set\napplication.enableDatagrams to true, which exchanges the\nSETTINGS_H3_DATAGRAM setting on the HTTP/3 control stream.
A datagram is sent with a single call to session.sendDatagram(). Each\ndatagram must fit within a single QUIC packet — datagrams cannot be\nfragmented. The maximum payload size is determined by the peer's\nmaxDatagramFrameSize and the path MTU. If a datagram is too large or the\npeer does not support datagrams, sendDatagram() returns 0n rather than\nthrowing an error.
There is no guarantee of delivery. Datagrams may be lost, duplicated, or\ndelivered out of order. The session.ondatagramstatus callback reports\nwhether each sent datagram was 'acknowledged', 'lost', or 'abandoned'\n(never sent on the wire).
QUIC supports 0-RTT early data, allowing a client that has previously connected\nto a server to send application data with its very first packet, without waiting\nfor the handshake to complete. This can eliminate a full round-trip of latency on\nreconnection.
\nTwo pieces of state from a prior connection make this possible:
\nsession.onsessionticket callback,\nenables TLS session resumption and 0-RTT encryption. Pass it as the\nsessionOptions.sessionTicket option on a subsequent connection to the\nsame server.session.onnewtoken\ncallback, allows the client to skip the server's address validation step\n(avoiding a Retry round-trip). Pass it as the sessionOptions.token\noption.If the server accepts the session ticket, any data sent before the handshake\ncompletes is 0-RTT early data. On the server side, stream.early is true\nfor streams carrying early data. The server can reject the 0-RTT attempt\n(for example, if its configuration has changed since the ticket was issued).\nWhen this happens, all streams opened during the 0-RTT phase are destroyed and\nthe client's session.onearlyrejected callback fires. The connection\nfalls back to a normal 1-RTT handshake and the application can reopen streams.
Early data is less secure than data sent after the handshake completes — it\ncan potentially be replayed by an attacker. Applications should treat 0-RTT\ndata with appropriate caution and avoid performing non-idempotent operations\nduring the early data phase.
", "displayName": "0-RTT early data and session resumption" }, { "textRaw": "Connection lifecycle", "name": "connection_lifecycle", "type": "module", "desc": "A typical client session progresses through these stages:
\nquic.connect() with a server address and options. This returns a\nQuicSession.session.opened resolves when the\nhandshake completes, providing the negotiated ALPN, cipher, and certificate\nvalidation results.session.close() to initiate a graceful shutdown. Existing streams\nare allowed to finish, then the session is destroyed. The returned promise\n(also available as session.closed) resolves when teardown is complete.On the server side, call quic.listen() with a callback. The callback\nfires for each incoming session after the TLS handshake begins. Incoming\nstreams arrive via the session.onstream callback.
session.destroy() is available for immediate teardown — all open streams\nare destroyed and the session is closed without waiting for them to finish.
QuicEndpoint and QuicSession support Symbol.asyncDispose, so they can\nbe used with await using for automatic cleanup.
Errors in the quic module are communicated through two complementary\nmechanisms: the onerror callback and the closed promise.
Both QuicSession and QuicStream expose an optional onerror callback.\nWhen a session or stream is destroyed with an error — including errors thrown\nby other user callbacks — the onerror callback is invoked with the error\nbefore the object is torn down. Setting onerror also marks the closed\npromise as handled, preventing unhandled rejection warnings. If onerror\nis not set, the error is delivered solely through the rejection of the\nclosed promise.
The QuicError class carries an explicit numeric QUIC error code\n(error.errorCode) alongside the usual message and code properties.\nWhen a QuicError is passed to stream.destroy() or\nwriter.fail(), its errorCode is used in the RESET_STREAM or\nSTOP_SENDING frame sent to the peer. Any other error type falls back to\nthe negotiated protocol's generic internal error code.
When using the Permission Model, the --allow-net flag must be passed to\nallow QUIC network operations. Without it, calling quic.connect() or\nquic.listen() will throw an ERR_ACCESS_DENIED error.
$ node --permission --allow-fs-read=* --experimental-quic index.mjs\nError: Access to this API has been restricted. Use --allow-net to manage permissions.\n code: 'ERR_ACCESS_DENIED',\n permission: 'Net',\n}\nCreating a QuicEndpoint instance without connecting or listening\nis permitted even without --allow-net, since no network I/O occurs until\nquic.connect() or quic.listen() is called.
<Object>The endpoint configuration options passed when constructing a new QuicEndpoint instance.
If not specified the endpoint will bind to IPv4 localhost on a random port.
The endpoint maintains an internal cache of validated socket addresses as a\nperformance optimization. This option sets the maximum number of addresses\nthat are cached. This is an advanced option that users typically won't have\nneed to specify.
" }, { "textRaw": "Type: {boolean}", "name": "disableStatelessReset", "type": "boolean", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "When true, the endpoint will not send stateless reset packets in response\nto packets from unknown connections. Stateless resets allow a peer to detect\nthat a connection has been lost even when the server has no state for it.\nDisabling them may be useful in testing or when stateless resets are handled\nat a different layer.
The number of seconds an endpoint will remain alive after all sessions have\nclosed and it is no longer listening. A value of 0 (default) means the\nendpoint is only destroyed when explicitly closed via endpoint.close() or\nendpoint.destroy(). A positive value starts an idle timer when the endpoint\nbecomes idle; if no new sessions are created before the timer fires, the\nendpoint is automatically destroyed. This is useful for connection pooling\nwhere endpoints should linger briefly for reuse by future connect() calls.
When true, indicates that the endpoint should bind only to IPv6 addresses.
Specifies the maximum number of concurrent sessions allowed per remote IP\naddress (ignoring port). When the limit is reached, new connections from the\nsame IP are refused with CONNECTION_REFUSED. A value of 0 disables the\nlimit. The maximum value is 65535.
This limit can also be changed dynamically after construction via\nendpoint.maxConnectionsPerHost.
Specifies the maximum total number of concurrent sessions across all remote\naddresses. When the limit is reached, new connections are refused with\nCONNECTION_REFUSED. A value of 0 disables the limit. The maximum value is\n65535.
This limit can also be changed dynamically after construction via\nendpoint.maxConnectionsTotal.
Specifies the maximum number of QUIC retry attempts allowed per remote peer address.
" }, { "textRaw": "Type: {bigint|number}", "name": "maxStatelessResetsPerHost", "type": "bigint|number", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "Specifies the maximum number of stateless resets that are allowed per remote peer address.
" }, { "textRaw": "Type: {bigint|number}", "name": "retryTokenExpiration", "type": "bigint|number", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "Specifies the length of time a QUIC retry token is considered valid.
" }, { "textRaw": "Type: {ArrayBufferView}", "name": "resetTokenSecret", "type": "ArrayBufferView", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "Specifies the 16-byte secret used to generate QUIC retry tokens.
" }, { "textRaw": "Type: {bigint|number}", "name": "tokenExpiration", "type": "bigint|number", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "Specifies the length of time a QUIC token is considered valid.
" }, { "textRaw": "Type: {ArrayBufferView}", "name": "tokenSecret", "type": "ArrayBufferView", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "Specifies the 16-byte secret used to generate QUIC tokens.
" }, { "textRaw": "Type: {number}", "name": "udpReceiveBufferSize", "type": "number", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {number}", "name": "udpSendBufferSize", "type": "number", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {number}", "name": "udpTTL", "type": "number", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {boolean}", "name": "validateAddress", "type": "boolean", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "When true, requires that the endpoint validate peer addresses using retry packets\nwhile establishing a new connection.
The ALPN (Application-Layer Protocol Negotiation) identifier(s).
\nFor client sessions, this is a single string specifying the protocol\nthe client wants to use (e.g. 'h3').
For server sessions, this is an array of protocol names in preference\norder that the server supports (e.g. ['h3', 'h3-29']). During the TLS\nhandshake, the server selects the first protocol from its list that the\nclient also supports.
The negotiated ALPN determines which Application implementation is used\nfor the session. 'h3' and 'h3-*' variants select the HTTP/3\napplication; all other values select the default application.
Default: 'h3'
HTTP/3 application-specific options. These only apply when the negotiated\nALPN selects the HTTP/3 application ('h3').
maxHeaderPairs <number> Maximum number of header name-value pairs\naccepted per header block. Headers beyond this limit are silently\ndropped. Default: 128maxHeaderLength <number> Maximum total byte length of all header\nnames and values combined per header block. Headers that would push\nthe total over this limit are silently dropped. Default: 8192maxFieldSectionSize <number> Maximum size of a compressed header\nfield section (QPACK). 0 means unlimited. Default: 0qpackMaxDTableCapacity <number> QPACK dynamic table capacity in\nbytes. Set to 0 to disable the dynamic table. Default: 4096qpackEncoderMaxDTableCapacity <number> QPACK encoder maximum\ndynamic table capacity. Default: 4096qpackBlockedStreams <number> Maximum number of streams that can\nbe blocked waiting for QPACK dynamic table updates. Default: 100enableConnectProtocol <boolean> Enable the extended CONNECT\nprotocol (RFC 9220). Default: falseenableDatagrams <boolean> Enable HTTP/3 datagrams (RFC 9297). Default: falseconst { listen } = await import('node:quic');\n\nawait listen((session) => { /* ... */ }, {\n application: {\n maxHeaderPairs: 64,\n qpackMaxDTableCapacity: 8192,\n enableDatagrams: true,\n },\n // ... other session options\n});\nSpecifies the congestion control algorithm that will be used.\nMust be set to one of either 'reno', 'cubic', or 'bbr'.
This is an advanced option that users typically won't have need to specify.
" }, { "textRaw": "Type: {string}", "name": "ciphers", "type": "string", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The list of supported TLS 1.3 cipher algorithms.
" }, { "textRaw": "Type: {boolean} **Default:** `true`", "name": "enableEarlyData", "type": "boolean", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "default": "`true`", "desc": "When true, enables TLS 0-RTT early data for this session. Early data\nallows the client to send application data before the TLS handshake\ncompletes, reducing latency on reconnection when a valid session ticket\nis available. Set to false to disable early data support.
The list of supported TLS 1.3 cipher groups.
" }, { "textRaw": "Type: {boolean}", "name": "keylog", "type": "boolean", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "When true, enables TLS key logging for the session. Key material is\ndelivered to the session.onkeylog callback in NSS Key Log Format.\nEach callback invocation receives a single line of key material. The output\ncan be used with tools such as Wireshark to decrypt captured QUIC traffic.
Specifies the maximum UDP packet payload size.
" }, { "textRaw": "Type: {bigint|number}", "name": "maxStreamWindow", "type": "bigint|number", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "Specifies the maximum stream flow-control window size.
" }, { "textRaw": "Type: {bigint|number}", "name": "maxWindow", "type": "bigint|number", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "Specifies the maximum session flow-control window size.
" }, { "textRaw": "Type: {number}", "name": "minVersion", "type": "number", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The minimum QUIC version number to allow. This is an advanced option that users\ntypically won't have need to specify.
" }, { "textRaw": "Type: {string} One of `'use'`, `'ignore'`, or `'default'`.", "name": "preferredAddressPolicy", "type": "string", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "When the remote peer advertises a preferred address, this option specifies whether\nto use it or ignore it.
", "shortDesc": "One of `'use'`, `'ignore'`, or `'default'`." }, { "textRaw": "Type: {boolean}", "name": "qlog", "type": "boolean", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "When true, enables qlog diagnostic output for the session. Qlog data\nis delivered to the session.onqlog callback as chunks of JSON-SEQ\nformatted text. The output can be analyzed with qlog visualization tools\nsuch as qvis.
Controls which datagram to drop when the pending datagram queue\n(sized by session.maxPendingDatagrams) is full. Must be one of\n'drop-oldest' (discard the oldest queued datagram to make room) or\n'drop-newest' (reject the incoming datagram). Dropped datagrams are\nreported as lost via the ondatagramstatus callback.
This option is immutable after session creation.
" }, { "textRaw": "Type: {number}", "name": "maxDatagramSendAttempts", "type": "number", "desc": "The maximum number of SendPendingData cycles a datagram can survive\nwithout being sent before it is abandoned. When a datagram cannot be\nsent due to congestion control or packet size constraints, it remains\nin the queue and the attempt counter increments. Once the limit is\nreached, the datagram is dropped and reported as 'abandoned' via the\nondatagramstatus callback. Valid range: 1 to 255.
A multiplier applied to the Probe Timeout (PTO) to compute the draining\nperiod duration after receiving a CONNECTION_CLOSE frame from the peer.\nRFC 9000 Section 10.2 requires the draining period to persist for at least\nthree times the current PTO. The valid range is 3 to 255. Values below\n3 are clamped to 3.
Specifies the maximum number of milliseconds a TLS handshake is permitted to take\nto complete before timing out.
" }, { "textRaw": "Type: {bigint|number}", "name": "keepAlive", "type": "bigint|number", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "Specifies the keep-alive timeout in milliseconds. When set to a non-zero\nvalue, PING frames will be sent automatically to keep the connection alive\nbefore the idle timeout fires. The value should be less than the effective\nidle timeout (maxIdleTimeout transport parameter) to be useful.
True to enable TLS tracing output.
" }, { "textRaw": "Type: {quic.TransportParams}", "name": "transportParams", "type": "quic.TransportParams", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The QUIC transport parameters to use for the session.
" }, { "textRaw": "Type: {bigint|number}", "name": "unacknowledgedPacketThreshold", "type": "bigint|number", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "Specifies the maximum number of unacknowledged packets a session should allow.
" }, { "textRaw": "Type: {boolean} **Default:** `true`", "name": "rejectUnauthorized", "type": "boolean", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "default": "`true`", "desc": "If true, the peer certificate is verified against the list of supplied CAs.\nAn error is emitted if verification fails; the error can be inspected via\nthe validationErrorReason and validationErrorCode fields in the\nhandshake callback. If false, peer certificate verification errors are\nignored.
When true (the default), connect() will attempt to reuse an existing\nendpoint rather than creating a new one for each session. This provides\nconnection pooling behavior — multiple sessions can share a single UDP\nsocket. The reuse logic will not return an endpoint that is listening on\nthe same address as the connect target (to prevent CID routing conflicts).
Set to false to force creation of a new endpoint for the session. This\nis useful when endpoint isolation is required (e.g., testing stateless\nreset behavior where source port identity matters).
True to require verification of TLS client certificate.
" }, { "textRaw": "Type: {number}", "name": "version", "type": "number", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The QUIC version number to use. This is an advanced option that users typically\nwon't have need to specify.
" } ], "modules": [ { "textRaw": "`sessionOptions.ca` (client only)", "name": "`sessionoptions.ca`_(client_only)", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "<ArrayBuffer> | <ArrayBuffer[]>The CA certificates to use for client sessions. For server sessions, CA\ncertificates are specified per-identity in the sessionOptions.sni map.
<ArrayBuffer> | <ArrayBuffer[]>The TLS certificates to use for client sessions. For server sessions,\ncertificates are specified per-identity in the sessionOptions.sni map.
<ArrayBuffer> | <ArrayBuffer[]>The CRL to use for client sessions. For server sessions, CRLs are specified\nper-identity in the sessionOptions.sni map.
<KeyObject> | <KeyObject[]>The TLS crypto keys to use for client sessions. For server sessions,\nkeys are specified per-identity in the sessionOptions.sni map.
<string>The peer server name to target (SNI). Defaults to 'localhost'.
<Object>An object mapping host names to TLS identity options for Server Name\nIndication (SNI) support. This is required for server sessions and must\ncontain at least one entry. The special key '*' specifies the optional\ndefault/fallback identity used when no other host name matches. If no\nwildcard entry is provided, connections with unrecognized server names\nwill be rejected with a TLS unrecognized_name alert. Each entry may\ncontain:
keys <KeyObject> | <KeyObject[]> The TLS private keys. Required.certs <ArrayBuffer> | <ArrayBuffer[]>\nThe TLS certificates. Required.\nOptional certificate revocation lists.verifyPrivateKey <boolean> Verify the private key. Default: false.port <number> The port to advertise in ORIGIN frames (RFC 9412) for\nthis host name. Default: 443. Only used for HTTP/3 sessions.authoritative <boolean> Whether to include this host name in ORIGIN\nframes. Default: true. Set to false to exclude a host name\nfrom ORIGIN advertisements. Wildcard ('*') entries are always\nexcluded regardless of this setting.const endpoint = await listen(callback, {\n sni: {\n '*': { keys: [defaultKey], certs: [defaultCert] },\n 'api.example.com': { keys: [apiKey], certs: [apiCert], port: 8443 },\n 'www.example.com': { keys: [wwwKey], certs: [wwwCert], ca: [customCA] },\n 'internal.example.com': { keys: [intKey], certs: [intCert], authoritative: false },\n },\n});\nShared TLS options (such as ciphers, groups, keylog, and verifyClient)\nare specified at the top level of the session options and apply to all\nidentities. Each SNI entry overrides only the per-identity certificate\nfields.
The SNI map can be replaced at runtime using endpoint.setSNIContexts(),\nwhich atomically swaps the map for new sessions while existing sessions\ncontinue to use their original identity.
An opaque address validation token previously received from the server\nvia the session.onnewtoken callback. Providing a valid token on\nreconnection allows the client to skip the server's address validation,\nreducing handshake latency.
<boolean>True to require private key verification for client sessions. For server\nsessions, this option is specified per-identity in the\nsessionOptions.sni map.
The maximum size in bytes of a DATAGRAM frame payload that this endpoint\nis willing to receive. Set to 0 to disable datagram support. The peer\nwill not send datagrams larger than this value. The actual maximum size of\na datagram that can be sent is determined by the peer's\nmaxDatagramFrameSize, not this endpoint's value.
All session and stream callbacks may be synchronous functions or async\nfunctions. If a callback throws synchronously or returns a promise that\nrejects, the error is caught and the owning session or stream is destroyed\nwith that error:
\nonblocked, onreset, onheaders, ontrailers,\noninfo, onwanttrailers): the stream is destroyed.onstream, ondatagram, ondatagramstatus,\nonpathvalidation, onsessionticket, onnewtoken,\nonversionnegotiation, onorigin, ongoaway, onhandshake,\nonkeylog, onqlog): the session is destroyed along with all of its\nstreams.Before destruction, the optional session.onerror or\nstream.onerror callback is invoked (if set), giving the application a\nchance to observe or log the error. The session.closed or stream.closed\npromise will reject with the error.
If the onerror callback itself throws or returns a promise that rejects,\nthe error from onerror is surfaced as an uncaught exception.
this <quic.QuicEndpoint>session <quic.QuicSession>The callback function that is invoked when a new session is initiated by a remote peer.
", "displayName": "Callback: `OnSessionCallback`" }, { "textRaw": "Callback: `OnStreamCallback`", "name": "callback:_`onstreamcallback`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "this <quic.QuicSession>stream <quic.QuicStream>this <quic.QuicSession>datagram <Uint8Array>early <boolean>this <quic.QuicSession>id <bigint>status <string> One of 'acknowledged', 'lost', or 'abandoned'.\n'acknowledged' means the peer confirmed receipt. 'lost' means the\ndatagram was sent but the network lost it. 'abandoned' means the\ndatagram was never sent on the wire (dropped due to queue overflow,\nsend attempt limit exceeded, or frame size rejection).this <quic.QuicSession>result <string> One of either 'success', 'failure', or 'aborted'.newLocalAddress <net.SocketAddress> The local address of the validated path.newRemoteAddress <net.SocketAddress> The remote address of the validated path.oldLocalAddress <net.SocketAddress> | <null> The local address of the previous\npath, or null if this is the first path validation (e.g., preferred address\nmigration from the client's perspective).oldRemoteAddress <net.SocketAddress> | <null> The remote address of the previous\npath, or null.preferredAddress <boolean> true if the path validation was triggered by\na preferred address migration on the client side. undefined on the server side.this <quic.QuicSession>ticket <Object>this <quic.QuicSession>version <number> The QUIC version that was configured for this session\n(the version that the server did not support).requestedVersions <number[]> The versions advertised by the server in\nthe Version Negotiation packet. These are the versions the server supports.supportedVersions <number[]> The versions supported locally, expressed\nas a two-element array [minVersion, maxVersion].Called when the server responds to the client's Initial packet with a\nVersion Negotiation packet, indicating that the version used by the client\nis not supported. The session is always destroyed immediately after this\ncallback returns.
", "displayName": "Callback: `OnVersionNegotiationCallback`" }, { "textRaw": "Callback: `OnHandshakeCallback`", "name": "callback:_`onhandshakecallback`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "this <quic.QuicSession>info <Object> The same object that session.opened resolves with.\nlocal <net.SocketAddress> The local socket address.remote <net.SocketAddress> The remote socket address.servername <string> The SNI server name negotiated during the handshake.protocol <string> The ALPN protocol negotiated during the handshake.cipher <string> The name of the negotiated TLS cipher suite.cipherVersion <string> The TLS protocol version of the cipher suite.validationErrorReason <string> If certificate validation failed, the\nreason string. Empty string if validation succeeded.validationErrorCode <number> If certificate validation failed, the\nerror code. 0 if validation succeeded.earlyDataAttempted <boolean> Whether 0-RTT early data was attempted.earlyDataAccepted <boolean> Whether 0-RTT early data was accepted.this <quic.QuicSession>token <Buffer> The NEW_TOKEN token data.address {SocketAddress} The remote address the token is associated with.this <quic.QuicSession>origins <string[]> The list of origins the server is authoritative for.this <quic.QuicSession>line <string> A single line of NSS Key Log Format text, including\na trailing newline character.Called when TLS key material is available. Only fires when\nsessionOptions.keylog is true. Multiple lines are emitted during the\nTLS 1.3 handshake, each containing a secret label, the client random, and\nthe secret value.
this <quic.QuicSession>data <string> A chunk of JSON-SEQ formatted qlog data.fin <boolean> true if this is the final qlog chunk for the session.Called when qlog diagnostic data is available. Only fires when\nsessionOptions.qlog is true. The data chunks should be\nconcatenated in order to produce the complete qlog output. When fin is\ntrue, no more chunks will be emitted and the concatenated result is a\ncomplete JSON-SEQ document.
this <quic.QuicStream>this <quic.QuicStream>error <any>this <quic.QuicStream>headers <Object> Header object with lowercase string keys and\nstring or string-array values.Called when initial request or response headers are received. For HTTP/3,\nthis delivers request pseudo-headers on the server and response headers\non the client.
", "displayName": "Callback: `OnHeadersCallback`" }, { "textRaw": "Callback: `OnTrailersCallback`", "name": "callback:_`ontrailerscallback`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "this <quic.QuicStream>trailers <Object> Trailing header object.Called when trailing headers are received from the peer.
", "displayName": "Callback: `OnTrailersCallback`" }, { "textRaw": "Callback: `OnInfoCallback`", "name": "callback:_`oninfocallback`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "this <quic.QuicStream>headers <Object> Informational header object.Called when informational (1xx) headers are received from the server\n(e.g., 103 Early Hints).
", "displayName": "Callback: `OnInfoCallback`" } ], "displayName": "Callbacks" }, { "textRaw": "HTTP/3 support", "name": "http/3_support", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "When the negotiated ALPN identifier is 'h3' (or one of the 'h3-*'\ndraft variants), the QUIC session runs the HTTP/3 application backed\nby nghttp3. 'h3' is the default ALPN for quic.connect() and\nquic.listen(), so HTTP/3 is what you get unless you select a\ndifferent ALPN explicitly.
Selecting the HTTP/3 application enables a number of stream- and\nsession-level capabilities that are not available to non-HTTP/3\napplications:
\n:method, :path, :scheme,\n:authority, and :status), trailing headers, and informational\n(1xx) responses. See stream.sendHeaders(),\nstream.sendTrailers(), and\nstream.sendInformationalHeaders().stream.priority and\nstream.setPriority().SETTINGS_H3_DATAGRAM=1, which\nis enabled by setting application.enableDatagrams to true\non both peers. See session.sendDatagram() and\nsession.ondatagram.sessionOptions.sni map (entries with\nauthoritative: true); clients receive the list via\nsession.onorigin.GOAWAY as part\nof session.close(); the client observes it via\nsession.ongoaway and stops opening new bidirectional streams.SETTINGS_ENABLE_CONNECT_PROTOCOL setting can be enabled via\napplication.enableConnectProtocol. The setting is exchanged\nbut the application is responsible for handling the :protocol\npseudo-header and any payload framing on top.application.qpackMaxDTableCapacity and friends.import { connect } from 'node:quic';\nimport process from 'node:process';\n\nconst session = await connect('example.com:443', {\n // ALPN defaults to 'h3'.\n servername: 'example.com',\n});\nawait session.opened;\n\nconst stream = await session.createBidirectionalStream({\n headers: {\n ':method': 'GET',\n ':path': '/',\n ':scheme': 'https',\n ':authority': 'example.com',\n },\n onheaders(headers) {\n console.log('status:', headers[':status']);\n },\n});\n\nconst decoder = new TextDecoder();\nfor await (const chunks of stream) {\n for (const chunk of chunks) {\n process.stdout.write(decoder.decode(chunk, { stream: true }));\n }\n}\n\nawait session.close();\nA few things to note:
\nsession.createBidirectionalStream({ headers }) automatically\nmarks the HEADERS frame as terminal when no body is provided —\nthe request is HEADERS followed by END_STREAM.onheaders callback receives the response pseudo-headers and\nregular headers in a single object with lowercase string keys.\nAfter the callback returns, the same object is also accessible\nvia stream.headers.for await (const chunks of stream) consumes the response\nbody. Each iteration yields a Uint8Array[] batch of chunks.import { listen } from 'node:quic';\n\nconst encoder = new TextEncoder();\n\nconst endpoint = await listen((session) => {\n // The session.onstream callback fires for each new client-initiated stream.\n}, {\n sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },\n // ALPN defaults to 'h3'.\n onheaders(headers) {\n // `this` is the QuicStream. Pseudo-headers are available on the\n // request header block (`:method`, `:path`, `:scheme`,\n // `:authority`).\n if (headers[':path'] === '/health') {\n this.sendHeaders({ ':status': '200', 'content-type': 'text/plain' });\n const w = this.writer;\n w.writeSync(encoder.encode('ok\\n'));\n w.endSync();\n } else {\n this.sendHeaders({ ':status': '404' }, { terminal: true });\n }\n },\n});\n\nconsole.log('listening on', endpoint.address);\nServer-side notes:
\nonheaders at the listen() level\napplies it to every incoming stream (it is wired up before\nonstream fires). Setting it inside onstream is too late for\nHTTP/3, where the request HEADERS frame is the first thing that\narrives on the stream.this.sendHeaders(headers, { terminal: true }) marks the\nresponse HEADERS frame as terminal (no body follows).this.writer and call endSync() to send the body and close the\nstream cleanly.PUSH_PROMISE and the related push-stream\nmachinery are not implemented and are not on the near-term\nroadmap. Server push has limited deployment in practice, and most\nuse cases are better served by Early Hints (103) or by direct\nfetches from the client.SETTINGS_ENABLE_CONNECT_PROTOCOL setting can be negotiated but\nthere is no built-in support for the :protocol pseudo-header,\nWebTransport datagram demultiplexing, or capsule framing.node:quic.QUIC sessions, streams, and endpoints emit PerformanceEntry objects\nwith entryType set to 'quic'. These entries are only created when a\nPerformanceObserver is observing the 'quic' entry type, ensuring\nzero overhead when not in use.
Each entry provides:
\nname <string> One of 'QuicEndpoint', 'QuicSession', or 'QuicStream'.entryType <string> Always 'quic'.startTime <number> High-resolution timestamp (ms) when the object was created.duration <number> Lifetime in milliseconds from creation to destruction.detail <Object> Entry-specific metadata (see below).detail.stats {QuicEndpointStats} The endpoint's statistics object\n(frozen at destruction time).detail.stats {QuicSessionStats} The session's statistics object\n(frozen at destruction time). Includes bytes sent/received, RTT\nmeasurements, congestion window, packet counts, and more.detail.handshake <Object> | <undefined> Timing-relevant handshake metadata,\nor undefined if the handshake did not complete before destruction.\n\ndetail.path <Object> | <undefined> The session's network path, or undefined if not yet established.\nlocal <net.SocketAddress>remote <net.SocketAddress>detail.stats {QuicStreamStats} The stream's statistics object\n(frozen at destruction time). Includes bytes sent/received, timing\ntimestamps, and offset tracking.detail.direction <string> Either 'bidi' or 'uni'.import { PerformanceObserver } from 'node:perf_hooks';\n\nconst obs = new PerformanceObserver((list) => {\n for (const entry of list.getEntries()) {\n console.log(`${entry.name}: ${entry.duration.toFixed(1)}ms`);\n if (entry.name === 'QuicSession') {\n const { stats, handshake } = entry.detail;\n console.log(` protocol: ${handshake?.protocol}`);\n console.log(` bytes sent: ${stats.bytesSent}`);\n console.log(` smoothed RTT: ${stats.smoothedRtt}ns`);\n }\n }\n});\nobs.observe({ entryTypes: ['quic'] });\nendpoint <quic.QuicEndpoint>config <quic.EndpointOptions>Published when a new endpoint is created.
", "displayName": "Channel: `quic.endpoint.created`" }, { "textRaw": "Channel: `quic.endpoint.listen`", "name": "channel:_`quic.endpoint.listen`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "endpoint <quic.QuicEndpoint>options <quic.SessionOptions>Published when an endpoint begins listening for incoming connections.
", "displayName": "Channel: `quic.endpoint.listen`" }, { "textRaw": "Channel: `quic.endpoint.connect`", "name": "channel:_`quic.endpoint.connect`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "endpoint <quic.QuicEndpoint>address <net.SocketAddress> The target server address.options <quic.SessionOptions>Published when quic.connect() is about to create a client session.\nFires before the ngtcp2 connection is established, allowing diagnostic\nsubscribers to observe the connection intent.
endpoint <quic.QuicEndpoint>hasPendingError <boolean>Published when an endpoint begins gracefully closing.
", "displayName": "Channel: `quic.endpoint.closing`" }, { "textRaw": "Channel: `quic.endpoint.closed`", "name": "channel:_`quic.endpoint.closed`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "endpoint <quic.QuicEndpoint>stats <quic.QuicEndpoint.Stats> Final endpoint statistics.Published when an endpoint has finished closing and is destroyed.
", "displayName": "Channel: `quic.endpoint.closed`" }, { "textRaw": "Channel: `quic.endpoint.error`", "name": "channel:_`quic.endpoint.error`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "endpoint <quic.QuicEndpoint>error <any>Published when an endpoint encounters an error that causes it to close.
", "displayName": "Channel: `quic.endpoint.error`" }, { "textRaw": "Channel: `quic.endpoint.busy.change`", "name": "channel:_`quic.endpoint.busy.change`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "endpoint <quic.QuicEndpoint>busy <boolean>Published when an endpoint's busy state changes.
", "displayName": "Channel: `quic.endpoint.busy.change`" }, { "textRaw": "Channel: `quic.session.created.client`", "name": "channel:_`quic.session.created.client`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "endpoint <quic.QuicEndpoint>session <quic.QuicSession>address <net.SocketAddress> The remote server address.options <quic.SessionOptions>Published when a client-initiated session is created.
", "displayName": "Channel: `quic.session.created.client`" }, { "textRaw": "Channel: `quic.session.created.server`", "name": "channel:_`quic.session.created.server`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "endpoint <quic.QuicEndpoint>session <quic.QuicSession>address <net.SocketAddress> | <undefined> The remote peer address.Published when a server-side session is created for an incoming connection.
", "displayName": "Channel: `quic.session.created.server`" }, { "textRaw": "Channel: `quic.session.open.stream`", "name": "channel:_`quic.session.open.stream`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "stream <quic.QuicStream>session <quic.QuicSession>direction <string> Either 'bidi' or 'uni'.Published when a locally-initiated stream is opened.
", "displayName": "Channel: `quic.session.open.stream`" }, { "textRaw": "Channel: `quic.session.received.stream`", "name": "channel:_`quic.session.received.stream`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "stream <quic.QuicStream>session <quic.QuicSession>direction <string> Either 'bidi' or 'uni'.Published when a remotely-initiated stream is received.
", "displayName": "Channel: `quic.session.received.stream`" }, { "textRaw": "Channel: `quic.session.send.datagram`", "name": "channel:_`quic.session.send.datagram`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "id <bigint> The datagram ID.length <number> The datagram payload size in bytes.session <quic.QuicSession>Published when a datagram is queued for sending.
", "displayName": "Channel: `quic.session.send.datagram`" }, { "textRaw": "Channel: `quic.session.update.key`", "name": "channel:_`quic.session.update.key`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "session <quic.QuicSession>Published when a TLS key update is initiated.
", "displayName": "Channel: `quic.session.update.key`" }, { "textRaw": "Channel: `quic.session.closing`", "name": "channel:_`quic.session.closing`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "session <quic.QuicSession>Published when a session begins gracefully closing (including when a\nGOAWAY frame is received from the peer).
", "displayName": "Channel: `quic.session.closing`" }, { "textRaw": "Channel: `quic.session.closed`", "name": "channel:_`quic.session.closed`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "session <quic.QuicSession>error <any> The error that caused the close, or undefined if clean.stats <quic.QuicSession.Stats> Final session statistics.Published when a session is destroyed. The stats object is a snapshot\nof the final statistics at the time of destruction.
session <quic.QuicSession>error <any> The error that caused the session to be destroyed.Published when a session is destroyed due to an error. Fires before the\nonerror callback and before streams are torn down. Unlike\nquic.session.closed (which fires for both clean and error closes), this\nchannel fires only when an error is present, making it suitable for\nerror-only alerting.
length <number> The datagram payload size in bytes.early <boolean> Whether the datagram was received as 0-RTT early data.session <quic.QuicSession>Published when a datagram is received from the remote peer.
", "displayName": "Channel: `quic.session.receive.datagram`" }, { "textRaw": "Channel: `quic.session.receive.datagram.status`", "name": "channel:_`quic.session.receive.datagram.status`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "id <bigint> The datagram ID.status <string> One of 'acknowledged', 'lost', or 'abandoned'.session <quic.QuicSession>Published when the delivery status of a sent datagram is updated.
", "displayName": "Channel: `quic.session.receive.datagram.status`" }, { "textRaw": "Channel: `quic.session.path.validation`", "name": "channel:_`quic.session.path.validation`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "result <string> One of 'success', 'failure', or 'aborted'.newLocalAddress <net.SocketAddress>newRemoteAddress <net.SocketAddress>oldLocalAddress <net.SocketAddress> | <null>oldRemoteAddress <net.SocketAddress> | <null>preferredAddress <boolean>session <quic.QuicSession>Published when a path validation attempt completes.
", "displayName": "Channel: `quic.session.path.validation`" }, { "textRaw": "Channel: `quic.session.new.token`", "name": "channel:_`quic.session.new.token`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "token <Buffer> The NEW_TOKEN token data.address <net.SocketAddress> The remote server address.session <quic.QuicSession>Published when a client session receives a NEW_TOKEN frame from the\nserver.
", "displayName": "Channel: `quic.session.new.token`" }, { "textRaw": "Channel: `quic.session.ticket`", "name": "channel:_`quic.session.ticket`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "ticket <Object> The opaque session ticket.session <quic.QuicSession>Published when a new TLS session ticket is received.
", "displayName": "Channel: `quic.session.ticket`" }, { "textRaw": "Channel: `quic.session.version.negotiation`", "name": "channel:_`quic.session.version.negotiation`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "version <number> The QUIC version that was configured for this session.requestedVersions <number[]> The versions advertised by the server.supportedVersions <number[]> The versions supported locally.session <quic.QuicSession>Published when the client receives a Version Negotiation packet from the\nserver. The session is always destroyed immediately after.
", "displayName": "Channel: `quic.session.version.negotiation`" }, { "textRaw": "Channel: `quic.session.receive.origin`", "name": "channel:_`quic.session.receive.origin`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "origins <string[]> The list of origins the server is authoritative for.session <quic.QuicSession>Published when the session receives an ORIGIN frame (RFC 9412) from\nthe peer.
", "displayName": "Channel: `quic.session.receive.origin`" }, { "textRaw": "Channel: `quic.session.handshake`", "name": "channel:_`quic.session.handshake`", "type": "module", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "session <quic.QuicSession>servername <string>protocol <string>cipher <string>cipherVersion <string>validationErrorReason <string>validationErrorCode <number>earlyDataAttempted <boolean>earlyDataAccepted <boolean>Published when the TLS handshake completes.
", "displayName": "Channel: `quic.session.handshake`" }, { "textRaw": "Channel: `quic.session.goaway`", "name": "channel:_`quic.session.goaway`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "session <quic.QuicSession>lastStreamId <bigint> The highest stream ID the peer may have processed.Published when the peer sends an HTTP/3 GOAWAY frame. Streams with IDs\nabove lastStreamId were not processed and can be retried on a new\nconnection. A lastStreamId of -1n indicates a shutdown notice without\na stream boundary.
session <quic.QuicSession>Published when the server rejects 0-RTT early data. All streams that were\nopened during the 0-RTT phase have been destroyed. Useful for diagnosing\nlatency regressions when 0-RTT is expected to succeed.
", "displayName": "Channel: `quic.session.early.rejected`" }, { "textRaw": "Channel: `quic.stream.closed`", "name": "channel:_`quic.stream.closed`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "stream <quic.QuicStream>session <quic.QuicSession>error <any> The error that caused the close, or undefined if clean.stats <quic.QuicStream.Stats> Final stream statistics.Published when a stream is destroyed. The stats object is a snapshot\nof the final statistics at the time of destruction.
stream <quic.QuicStream>session <quic.QuicSession>headers <Object> The initial request or response headers.Published when initial headers are received on a stream. For HTTP/3\nserver-side streams, this contains request pseudo-headers (:method,\n:path, etc.). For client-side streams, this contains response headers\n(:status, etc.).
stream <quic.QuicStream>session <quic.QuicSession>trailers <Object> The trailing headers.Published when trailing headers are received on a stream.
", "displayName": "Channel: `quic.stream.trailers`" }, { "textRaw": "Channel: `quic.stream.info`", "name": "channel:_`quic.stream.info`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "stream <quic.QuicStream>session <quic.QuicSession>headers <Object> The informational headers.Published when informational (1xx) headers are received on a stream\n(e.g., 103 Early Hints).
", "displayName": "Channel: `quic.stream.info`" }, { "textRaw": "Channel: `quic.stream.reset`", "name": "channel:_`quic.stream.reset`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "stream <quic.QuicStream>session <quic.QuicSession>error <any> The QUIC error associated with the reset.Published when a stream receives a STOP_SENDING or RESET_STREAM frame\nfrom the peer, indicating the peer has aborted the stream. This is a\nkey signal for diagnosing application-level issues such as cancelled\nrequests.
", "displayName": "Channel: `quic.stream.reset`" }, { "textRaw": "Channel: `quic.stream.blocked`", "name": "channel:_`quic.stream.blocked`", "type": "module", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "stream <quic.QuicStream>session <quic.QuicSession>Published when a stream is flow-control blocked and cannot send data\nuntil the peer increases the flow control window. Useful for diagnosing\nthroughput issues caused by flow control.
", "displayName": "Channel: `quic.stream.blocked`" } ], "displayName": "Diagnostic Channels" } ], "methods": [ { "textRaw": "`quic.connect(address[, options])`", "name": "connect", "type": "method", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`address` {string|net.SocketAddress}", "name": "address", "type": "string|net.SocketAddress" }, { "textRaw": "`options` {quic.SessionOptions}", "name": "options", "type": "quic.SessionOptions", "optional": true } ], "return": { "textRaw": "Returns: {Promise} a promise for a {quic.QuicSession}", "name": "return", "type": "Promise", "desc": "a promise for a {quic.QuicSession}" } } ], "desc": "Initiate a new client-side session.
\nimport { connect } from 'node:quic';\nimport { Buffer } from 'node:buffer';\n\nconst enc = new TextEncoder();\nconst alpn = 'foo';\nconst client = await connect('123.123.123.123:8888', { alpn });\nawait client.createUnidirectionalStream({\n body: enc.encode('hello world'),\n});\nBy default, every call to connect(...) will create a new local\nQuicEndpoint instance bound to a new random local IP port. To\nspecify the exact local address to use, or to multiplex multiple\nQUIC sessions over a single local port, pass the endpoint option\nwith either a QuicEndpoint or EndpointOptions as the argument.
import { QuicEndpoint, connect } from 'node:quic';\n\nconst endpoint = new QuicEndpoint({\n address: '127.0.0.1:1234',\n});\n\nconst client = await connect('123.123.123.123:8888', { endpoint });\nConfigures the endpoint to listen as a server. When a new session is initiated by\na remote peer, the given onsession callback will be invoked with the created\nsession.
import { listen } from 'node:quic';\n\nconst endpoint = await listen((session) => {\n // ... handle the session\n});\n\n// Closing the endpoint allows any sessions open when close is called\n// to complete naturally while preventing new sessions from being\n// initiated. Once all existing sessions have finished, the endpoint\n// will be destroyed. The call returns a promise that is resolved once\n// the endpoint is destroyed.\nawait endpoint.close();\nBy default, every call to listen(...) will create a new local\nQuicEndpoint instance bound to a new random local IP port. To\nspecify the exact local address to use, or to multiplex multiple\nQUIC sessions over a single local port, pass the endpoint option\nwith either a QuicEndpoint or EndpointOptions as the argument.
At most, any single QuicEndpoint can only be configured to listen as\na server once.
An object containing commonly used constants for QUIC configuration.
", "properties": [ { "textRaw": "{Object}", "name": "cc", "type": "Object", "desc": "Congestion control algorithm identifiers, for use with the\nsessionOptions.cc option:
quic.constants.cc.RENO — Reno congestion control.quic.constants.cc.CUBIC — CUBIC congestion control.quic.constants.cc.BBR — BBR congestion control.The default TLS 1.3 cipher suite list used when sessionOptions.ciphers\nis not specified.
The default TLS 1.3 key-exchange group list used when\nsessionOptions.groups is not specified.
A QuicEndpoint encapsulates the local UDP-port binding for QUIC. It can be\nused as both a client and a server.
The local UDP socket address to which the endpoint is bound, if any.
\nIf the endpoint is not currently bound then the value will be undefined. Read only.
When endpoint.busy is set to true, the endpoint will temporarily reject\nnew sessions from being created. Read/write.
// Mark the endpoint busy. New sessions will be prevented.\nendpoint.busy = true;\n\n// Mark the endpoint free. New session will be allowed.\nendpoint.busy = false;\nThe busy property is useful when the endpoint is under heavy load and needs to\ntemporarily reject new sessions while it catches up.
A promise that is fulfilled when the endpoint is destroyed. This will be the same promise that is\nreturned by the endpoint.close() function. Read only.
True if endpoint.close() has been called and closing the endpoint has not yet completed.\nRead only.
True if endpoint.destroy() has been called. Read only.
True if the endpoint is actively listening for incoming connections. Read only.
" }, { "textRaw": "Type: {number}", "name": "maxConnectionsPerHost", "type": "number", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "The maximum number of concurrent connections allowed per remote IP address.\n0 means unlimited (default). Can be set at construction time via the\nmaxConnectionsPerHost option and changed dynamically at any time.\nThe valid range is 0 to 65535.
The maximum total number of concurrent connections across all remote\naddresses. 0 means unlimited (default). Can be set at construction time via\nthe maxConnectionsTotal option and changed dynamically at any time.\nThe valid range is 0 to 65535.
The statistics collected for an active endpoint. Read only.
" } ], "methods": [ { "textRaw": "`endpoint.close()`", "name": "close", "type": "method", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "signatures": [ { "params": [], "return": { "textRaw": "Returns: {Promise}", "name": "return", "type": "Promise" } } ], "desc": "Gracefully close the endpoint. The endpoint will close and destroy itself when\nall currently open sessions close. Once called, new sessions will be rejected.
\nReturns a promise that is fulfilled when the endpoint is destroyed.
" }, { "textRaw": "`endpoint.destroy([error])`", "name": "destroy", "type": "method", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`error` {any}", "name": "error", "type": "any", "optional": true } ] } ], "desc": "Forcefully closes the endpoint by forcing all open sessions to be immediately\nclosed.
" }, { "textRaw": "`endpoint.setSNIContexts(entries[, options])`", "name": "setSNIContexts", "type": "method", "meta": { "added": [ "v26.1.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`entries` {object} An object mapping host names to TLS identity options. Each entry must include `keys` and `certs`.", "name": "entries", "type": "object", "desc": "An object mapping host names to TLS identity options. Each entry must include `keys` and `certs`." }, { "textRaw": "`options` {object}", "name": "options", "type": "object", "options": [ { "textRaw": "`replace` {boolean} If `true`, replaces the entire SNI map. If `false` (the default), merges the entries into the existing map.", "name": "replace", "type": "boolean", "desc": "If `true`, replaces the entire SNI map. If `false` (the default), merges the entries into the existing map." } ], "optional": true } ] } ], "desc": "Replaces or updates the SNI TLS contexts for this endpoint. This allows\nchanging the TLS identity (key/certificate) used for specific host names\nwithout restarting the endpoint. Existing sessions are unaffected — only\nnew sessions will use the updated contexts.
\nendpoint.setSNIContexts({\n 'api.example.com': { keys: [newApiKey], certs: [newApiCert] },\n});\n\n// Replace the entire SNI map\nendpoint.setSNIContexts({\n 'api.example.com': { keys: [newApiKey], certs: [newApiCert] },\n}, { replace: true });\nCalls endpoint.close() and returns a promise that fulfills when the\nendpoint has closed.
A view of the collected statistics for an endpoint.
", "properties": [ { "textRaw": "Type: {bigint} A timestamp indicating the moment the endpoint was created. Read only.", "name": "createdAt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "A timestamp indicating the moment the endpoint was created. Read only." }, { "textRaw": "Type: {bigint} A timestamp indicating the moment the endpoint was destroyed. Read only.", "name": "destroyedAt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "A timestamp indicating the moment the endpoint was destroyed. Read only." }, { "textRaw": "Type: {bigint} The total number of bytes received by this endpoint. Read only.", "name": "bytesReceived", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of bytes received by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of bytes sent by this endpoint. Read only.", "name": "bytesSent", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of bytes sent by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of QUIC packets successfully received by this endpoint. Read only.", "name": "packetsReceived", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of QUIC packets successfully received by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of QUIC packets successfully sent by this endpoint. Read only.", "name": "packetsSent", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of QUIC packets successfully sent by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of peer-initiated sessions received by this endpoint. Read only.", "name": "serverSessions", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of peer-initiated sessions received by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of sessions initiated by this endpoint. Read only.", "name": "clientSessions", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of sessions initiated by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of times an initial packet was rejected due to the endpoint being marked busy. Read only.", "name": "serverBusyCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of times an initial packet was rejected due to the endpoint being marked busy. Read only." }, { "textRaw": "Type: {bigint} The total number of QUIC retry attempts on this endpoint. Read only.", "name": "retryCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of QUIC retry attempts on this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of sessions rejected due to QUIC version mismatch. Read only.", "name": "versionNegotiationCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of sessions rejected due to QUIC version mismatch. Read only." }, { "textRaw": "Type: {bigint} The total number of stateless resets handled by this endpoint. Read only.", "name": "statelessResetCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of stateless resets handled by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of sessions that were closed before handshake completed. Read only.", "name": "immediateCloseCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The total number of sessions that were closed before handshake completed. Read only." } ] }, { "textRaw": "Class: `QuicSession`", "name": "QuicSession", "type": "class", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "A QuicSession represents the local side of a QUIC connection.
Initiate a graceful close of the session. Existing streams will be allowed\nto complete but no new streams will be opened. Once all streams have closed,\nthe session will be destroyed. The returned promise will be fulfilled once\nthe session has been destroyed. If a non-zero code is specified, the\npromise will reject with an ERR_QUIC_TRANSPORT_ERROR or\nERR_QUIC_APPLICATION_ERROR depending on the type.
Immediately destroy the session. All streams will be destroyed and the\nsession will be closed. If error is provided and session.onerror is\nset, the onerror callback is invoked before destruction. The\nsession.closed promise will reject with the error. If options is\nprovided, the CONNECTION_CLOSE frame sent to the peer will include the\nspecified error code, type, and reason.
Open a new bidirectional stream. If the body option is not specified,\nthe outgoing stream will be half-closed. The priority and incremental\noptions are only used when the session supports priority (e.g. HTTP/3).\nThe headers, onheaders, ontrailers, oninfo, and onwanttrailers\noptions are only used when the session supports headers (e.g. HTTP/3).
Open a new unidirectional stream. If the body option is not specified,\nthe outgoing stream will be closed. The priority and incremental\noptions are only used when the session supports priority (e.g. HTTP/3).
Sends an unreliable datagram to the remote peer, returning a promise for\nthe datagram ID.
\nIf datagram is a string, it will be encoded using the specified encoding.
If datagram is an ArrayBufferView, the bytes are copied into an\ninternal buffer; the caller's source buffer is unchanged and may be reused\nor mutated immediately after the call returns. Callers that want to ensure\ntheir source cannot be mutated after the call (for example, when handing\nthe buffer off to another async consumer) can call\nArrayBuffer.prototype.transfer() themselves before passing the buffer.
If datagram is a Promise, it will be awaited before sending. If the\nsession closes while awaiting, 0n is returned silently (datagrams are\ninherently unreliable).
If the datagram payload is zero-length (empty string after encoding, detached\nbuffer, or zero-length view), 0n is returned and no datagram is sent.
For HTTP/3 sessions, the peer must advertise SETTINGS_H3_DATAGRAM=1\n(via application: { enableDatagrams: true }) for datagrams to be sent.\nIf the peer's setting is 0, sendDatagram() returns 0n (per RFC 9297\n§3, an endpoint MUST NOT send HTTP Datagrams unless the peer indicated\nsupport).
Datagrams cannot be fragmented — each must fit within a single QUIC packet.\nThe maximum datagram size is determined by the peer's\nmaxDatagramFrameSize transport parameter (which the peer advertises during\nthe handshake). If the peer sets this to 0, datagrams are not supported\nand 0n will be returned. If the datagram exceeds the peer's limit, it\nwill be silently dropped and 0n returned. The local\nmaxDatagramFrameSize transport parameter (default: 1200 bytes) controls\nwhat this endpoint advertises to the peer as its own maximum.
Initiate a key update for the session.
" }, { "textRaw": "`session[Symbol.asyncDispose]()`", "name": "[Symbol.asyncDispose]", "type": "method", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "Calls session.close() and returns a promise that fulfills when the\nsession has closed.
A promise that is fulfilled once the TLS handshake completes successfully.\nThe resolved value contains information about the established session\nincluding the negotiated protocol, cipher suite, certificate validation\nstatus, and 0-RTT early data status.
\nIf the handshake fails or the session is destroyed before the handshake\ncompletes, the promise will be rejected.
", "options": [ { "textRaw": "`local` {net.SocketAddress} The local socket address.", "name": "local", "type": "net.SocketAddress", "desc": "The local socket address." }, { "textRaw": "`remote` {net.SocketAddress} The remote socket address.", "name": "remote", "type": "net.SocketAddress", "desc": "The remote socket address." }, { "textRaw": "`servername` {string} The SNI server name negotiated during the handshake.", "name": "servername", "type": "string", "desc": "The SNI server name negotiated during the handshake." }, { "textRaw": "`protocol` {string} The ALPN protocol negotiated during the handshake.", "name": "protocol", "type": "string", "desc": "The ALPN protocol negotiated during the handshake." }, { "textRaw": "`cipher` {string} The name of the negotiated TLS cipher suite.", "name": "cipher", "type": "string", "desc": "The name of the negotiated TLS cipher suite." }, { "textRaw": "`cipherVersion` {string} The TLS protocol version of the cipher suite (e.g., `'TLSv1.3'`).", "name": "cipherVersion", "type": "string", "desc": "The TLS protocol version of the cipher suite (e.g., `'TLSv1.3'`)." }, { "textRaw": "`validationErrorReason` {string} If certificate validation failed, the reason string. Empty string if validation succeeded.", "name": "validationErrorReason", "type": "string", "desc": "If certificate validation failed, the reason string. Empty string if validation succeeded." }, { "textRaw": "`validationErrorCode` {number} If certificate validation failed, the error code. `0` if validation succeeded.", "name": "validationErrorCode", "type": "number", "desc": "If certificate validation failed, the error code. `0` if validation succeeded." }, { "textRaw": "`earlyDataAttempted` {boolean} Whether 0-RTT early data was attempted.", "name": "earlyDataAttempted", "type": "boolean", "desc": "Whether 0-RTT early data was attempted." }, { "textRaw": "`earlyDataAccepted` {boolean} Whether 0-RTT early data was accepted by the server.", "name": "earlyDataAccepted", "type": "boolean", "desc": "Whether 0-RTT early data was accepted by the server." } ], "shortDesc": "for an {Object}" }, { "textRaw": "Type: {Promise}", "name": "closed", "type": "Promise", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "A promise that is fulfilled once the session is destroyed.
" }, { "textRaw": "Type: {boolean}", "name": "closing", "type": "boolean", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "True if session.close() has been called and the session has not yet\nbeen destroyed. Read only.
True if session.destroy() has been called. Read only.
The endpoint that created this session. Returns null if the session\nhas been destroyed. Read only.
An optional callback invoked when the session is destroyed with an error.\nThis includes errors caused by user callbacks that throw or reject (see\nCallback error handling). The callback receives a single argument: the\nerror that triggered the destruction. If the onerror callback itself throws\nor returns a promise that rejects, the error is surfaced as an uncaught\nexception. Read/write.
Can also be set via the onerror option in quic.connect() or\nquic.listen().
The callback to invoke when a new stream is initiated by a remote peer. Read/write.
" }, { "textRaw": "Type: {quic.OnDatagramCallback}", "name": "ondatagram", "type": "quic.OnDatagramCallback", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The callback to invoke when a new datagram is received from a remote peer. Read/write.
" }, { "textRaw": "Type: {quic.OnDatagramStatusCallback}", "name": "ondatagramstatus", "type": "quic.OnDatagramStatusCallback", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The callback to invoke when the status of a datagram is updated. Read/write.
" }, { "textRaw": "Type: {Function|undefined}", "name": "onearlyrejected", "type": "Function|undefined", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "The callback to invoke when the server rejects 0-RTT early data. When\nthis fires, all streams that were opened during the 0-RTT phase have\nbeen destroyed. The application should re-open streams if needed.\nRead/write.
\nThis callback only fires on the client side when the server rejects\nthe client's 0-RTT attempt. The connection falls back to 1-RTT and\ncontinues normally.
" }, { "textRaw": "Type: {quic.OnPathValidationCallback}", "name": "onpathvalidation", "type": "quic.OnPathValidationCallback", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The callback to invoke when the path validation is updated. Read/write.
" }, { "textRaw": "Type: {quic.OnSessionTicketCallback}", "name": "onsessionticket", "type": "quic.OnSessionTicketCallback", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The callback to invoke when a new session ticket is received. Read/write.
" }, { "textRaw": "Type: {quic.OnVersionNegotiationCallback}", "name": "onversionnegotiation", "type": "quic.OnVersionNegotiationCallback", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The callback to invoke when a version negotiation is initiated. Read/write.
" }, { "textRaw": "Type: {quic.OnHandshakeCallback}", "name": "onhandshake", "type": "quic.OnHandshakeCallback", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The callback to invoke when the TLS handshake is completed. Read/write.
" }, { "textRaw": "Type: {quic.OnNewTokenCallback}", "name": "onnewtoken", "type": "quic.OnNewTokenCallback", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "The callback to invoke when a NEW_TOKEN token is received from the server.\nThe token can be passed as the token option on a future connection to\nthe same server to skip address validation. Read/write.
The callback to invoke when an ORIGIN frame (RFC 9412) is received from\nthe server, indicating which origins the server is authoritative for.\nRead/write.
" }, { "textRaw": "Type: {Function}", "name": "ongoaway", "type": "Function", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "The callback to invoke when the peer sends an HTTP/3 GOAWAY frame,\nindicating it is initiating a graceful shutdown. The callback receives\n(lastStreamId) where lastStreamId is a {bigint}:
lastStreamId is -1n, the peer sent a shutdown notice (intent\nto close) without specifying a stream boundary. All existing streams\nmay still be processed.lastStreamId is >= 0n, it is the highest stream ID the peer\nmay have processed. Streams with IDs above this value were NOT\nprocessed and can be safely retried on a new connection.After GOAWAY is received, session.createBidirectionalStream() will\nthrow ERR_INVALID_STATE. Existing streams continue until they\ncomplete or the session closes.
This callback is only relevant for HTTP/3 sessions. Read/write.
" }, { "textRaw": "Type: {quic.OnKeylogCallback}", "name": "onkeylog", "type": "quic.OnKeylogCallback", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "The callback to invoke when TLS key material is available. Requires\nsessionOptions.keylog to be true. Each invocation receives a single\nline of NSS Key Log Format text (including a trailing newline). This is\nuseful for decrypting packet captures with tools like Wireshark. Read/write.
Can also be set via the onkeylog option in quic.connect() or\nquic.listen().
The callback to invoke when qlog data is available. Requires\nsessionOptions.qlog to be true. The callback receives a string\nchunk of JSON-SEQ formatted qlog data and a boolean fin flag. When\nfin is true, the chunk is the final qlog output for this session and\nthe concatenated chunks form a complete qlog trace. Read/write.
Qlog data arrives during the connection lifecycle. The first chunk contains\nthe qlog header with format metadata. Subsequent chunks contain trace\nevents. The final chunk (with fin set to true) is emitted during\nsession destruction and completes the JSON-SEQ output.
Can also be set via the onqlog option in quic.connect() or\nquic.listen().
The local and remote socket addresses associated with the session. Read only.
", "options": [ { "textRaw": "`local` {net.SocketAddress}", "name": "local", "type": "net.SocketAddress" }, { "textRaw": "`remote` {net.SocketAddress}", "name": "remote", "type": "net.SocketAddress" } ] }, { "textRaw": "Type: {Object|undefined}", "name": "certificate", "type": "Object|undefined", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "The local certificate as an object with properties such as subject,\nissuer, valid_from, valid_to, fingerprint, etc. Returns undefined\nif the session is destroyed or no certificate is available.
The peer's certificate as an object with properties such as subject,\nissuer, valid_from, valid_to, fingerprint, etc. Returns undefined\nif the session is destroyed or the peer did not present a certificate.
The ephemeral key information for the session, with properties such as\ntype, name, and size. Only available on client sessions. Returns\nundefined for server sessions or if the session is destroyed.
The maximum datagram payload size in bytes that the peer will accept.\nThis is derived from the peer's maxDatagramFrameSize transport\nparameter minus the DATAGRAM frame overhead (type byte and variable-length\ninteger encoding). Returns 0 if the peer does not support datagrams or\nif the handshake has not yet completed. Datagrams larger than this value\nwill not be sent.
The maximum number of datagrams that can be queued for sending. Datagrams\nare queued when sendDatagram() is called and sent opportunistically\nalongside stream data by the packet serialization loop. When the queue\nis full, the sessionOptions.datagramDropPolicy determines whether\nthe oldest or newest datagram is dropped. Dropped datagrams are reported\nas lost via the ondatagramstatus callback.
This property can be changed dynamically to adjust queue capacity\nbased on application activity or memory pressure. The valid range\nis 0 to 65535.
Return the current statistics for the session. Read only.
" } ] }, { "textRaw": "Class: `QuicSession.Stats`", "name": "QuicSession.Stats", "type": "class", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "properties": [ { "textRaw": "Type: {bigint}", "name": "createdAt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "closingAt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "handshakeCompletedAt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "handshakeConfirmedAt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "bytesReceived", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "bytesSent", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "bidiInStreamCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "bidiOutStreamCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "uniInStreamCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "uniOutStreamCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "maxBytesInFlight", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "bytesInFlight", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "blockCount", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "cwnd", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "latestRtt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "minRtt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "rttVar", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "smoothedRtt", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "ssthresh", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "datagramsReceived", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "datagramsSent", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "datagramsAcknowledged", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } }, { "textRaw": "Type: {bigint}", "name": "datagramsLost", "type": "bigint", "meta": { "added": [ "v23.8.0" ], "changes": [] } } ] }, { "textRaw": "Class: `QuicError`", "name": "QuicError", "type": "class", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "desc": "A QuicError is an Error subclass that carries an explicit numeric\nQUIC error code. Use it to abort a QUIC stream or session with a\nspecific application-protocol-defined error code rather than letting\nthe implementation pick a generic fallback.
The class is exported from node:quic:
import { QuicError } from 'node:quic';\nconst { QuicError } = require('node:quic');\nWhen a QuicError is supplied to APIs that emit a wire frame\n(writer.fail(), stream.destroy()), the QUIC stack uses\nerror.errorCode as the wire code for the resulting frame.\nWhen any other value is supplied (for example a plain Error), the\nimplementation falls back to the negotiated application protocol's\n\"internal error\" code (H3_INTERNAL_ERROR (0x102) for HTTP/3, or\nthe QUIC transport-layer INTERNAL_ERROR (0x1) for raw QUIC).
The Node.js error code (error.code) defaults to\n'ERR_QUIC_STREAM_ABORTED'. Callers who need a more specific code\nstring can override it via options.code — the numeric QUIC code\nis unaffected.
The Node.js error code is fixed at 'ERR_QUIC_STREAM_ABORTED' so that\ncatch blocks can distinguish a QuicError from other Node.js errors\nwithout checking the prototype chain. The numeric QUIC code lives on\nthe separate error.errorCode property to avoid colliding with\nthe Node.js convention that error.code is a string.
import { QuicError } from 'node:quic';\n\nconst err = new QuicError('rejecting stream', { errorCode: 0x10cn });\nconsole.log(err.code); // 'ERR_QUIC_STREAM_ABORTED'\nconsole.log(err.errorCode); // 268n\nconsole.log(err.type); // 'application'\n\nconst custom = new QuicError('custom failure', {\n errorCode: 0x10cn,\n code: 'ERR_MY_QUIC_FAILURE',\n});\nconsole.log(custom.code); // 'ERR_MY_QUIC_FAILURE'\nThe numeric QUIC error code carried by this error.
" }, { "textRaw": "Type: {string}", "name": "type", "type": "string", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "Either 'application' or 'transport'. Indicates the namespace of\nerror.errorCode.
A promise that is fulfilled when the stream is fully closed. It resolves\nwhen the stream closes cleanly (including idle timeout). It rejects with\nan ERR_QUIC_APPLICATION_ERROR or ERR_QUIC_TRANSPORT_ERROR when the\nstream is closed due to a QUIC error (e.g., stream reset by the peer,\nCONNECTION_CLOSE with a non-zero error code).
True if stream.destroy() has been called.
True if any data on this stream was received as 0-RTT (early data)\nbefore the TLS handshake completed. Early data is less secure and\ncould potentially be replayed by an attacker. Applications should\ntreat early data with appropriate caution.
\nThis property is only meaningful on the server side. On the client\nside, it is always false.
The directionality of the stream, or null if the stream has been destroyed\nor is still pending. Read only.
The maximum number of bytes that the writer will buffer before\nwriteSync() returns false. When the buffered data exceeds this limit,\nthe caller should wait for drain before writing more.
The value can be changed dynamically at any time. This is particularly\nuseful for streams received via the onstream callback, where the\ndefault (65536) may need to be adjusted based on application needs.\nThe valid range is 0 to 4294967295.
The stream ID, or null if the stream has been destroyed or is still\npending. Read only.
An optional callback invoked when the stream is destroyed with an error.\nThis includes errors caused by user callbacks that throw or reject (see\nCallback error handling). The callback receives a single argument: the\nerror that triggered the destruction. If the onerror callback itself throws\nor returns a promise that rejects, the error is surfaced as an uncaught\nexception. Read/write.
The callback to invoke when the stream is blocked. Read/write.
" }, { "textRaw": "Type: {quic.OnStreamErrorCallback}", "name": "onreset", "type": "quic.OnStreamErrorCallback", "meta": { "added": [ "v23.8.0" ], "changes": [] }, "desc": "The callback to invoke when the peer aborts a direction of the stream by\nsending a RESET_STREAM frame (the peer abandons their writable side, so\nno further data will arrive on our readable side) or a STOP_SENDING\nframe (the peer asks us to stop writing on our writable side).
The callback receives a Node.js error whose errorCode (bigint)\nproperty carries the application error code from the wire frame.
The stream is not automatically destroyed when this callback fires —\nthe application chooses how to react. Common patterns are: ignore (and\ncontinue using the still-active direction on a bidirectional stream),\nabort the other direction with writer.fail(), or tear down the\nwhole stream with stream.destroy(). Read/write.
The buffered initial headers received on this stream, or undefined if the\napplication does not support headers or no headers have been received yet.\nFor server-side streams, this contains the request headers (e.g., :method,\n:path, :scheme). For client-side streams, this contains the response\nheaders (e.g., :status).
Header names are lowercase strings. Multi-value headers are represented as\narrays. The object has __proto__: null.
The callback to invoke when initial headers are received on the stream. The\ncallback receives (headers) where headers is an object (same format as\nstream.headers). For HTTP/3, this delivers request pseudo-headers on the\nserver side and response headers on the client side. Throws\nERR_INVALID_STATE if set on a session that does not support headers.\nRead/write.
The callback to invoke when trailing headers are received from the peer.\nThe callback receives (trailers) where trailers is an object in the\nsame format as stream.headers. Throws ERR_INVALID_STATE if set on a\nsession that does not support headers. Read/write.
The callback to invoke when informational (1xx) headers are received from\nthe server. The callback receives (headers) where headers is an object\nin the same format as stream.headers. Informational headers are sent\nbefore the final response (e.g., 103 Early Hints). Throws\nERR_INVALID_STATE if set on a session that does not support headers.\nRead/write.
The callback to invoke when the application is ready for trailing headers\nto be sent. This is called synchronously — the user must call\nstream.sendTrailers() within this callback. Throws\nERR_INVALID_STATE if set on a session that does not support headers.\nRead/write.
Set trailing headers to be sent automatically when the application requests\nthem. This is an alternative to the stream.onwanttrailers callback\nfor cases where the trailers are known before the body completes. Throws\nERR_INVALID_STATE if set on a session that does not support headers.\nRead/write.
The current priority of the stream. Returns null if the session does not\nsupport priority (e.g. non-HTTP/3) or if the stream has been destroyed.\nRead only. Use stream.setPriority() to change the priority.
On client-side HTTP/3 sessions, the value reflects what was set via\nstream.setPriority(). On server-side HTTP/3 sessions, the value\nreflects the peer's requested priority (e.g., from PRIORITY_UPDATE frames).
Returns a Writer object for pushing data to the stream incrementally.\nThe Writer implements the stream/iter Writer interface with the\ntry-sync-fallback-to-async pattern.
\nOnly available when no body source was provided at creation time or via\nstream.setBody(). Non-writable streams return an already-closed\nWriter. Throws ERR_INVALID_STATE if the outbound is already configured.
The Writer has the following methods:
\nwriteSync(chunk) — Synchronous write. Returns true if accepted,\nfalse if flow-controlled. Data is NOT accepted on false.write(chunk[, options]) — Async write with drain wait. options.signal\nis checked at entry but not observed during the write.writevSync(chunks) — Synchronous vectored write. All-or-nothing.writev(chunks[, options]) — Async vectored write.endSync() — Synchronous close. Returns total bytes or -1.end([options]) — Async close.fail(reason) — Errors the stream (sends RESET_STREAM to peer).\nWhen reason is a QuicError, its error.errorCode is used\nas the wire code on the resulting RESET_STREAM frame; otherwise\nthe wire code falls back to the negotiated application protocol's\n\"internal error\" code (H3_INTERNAL_ERROR (0x102) for HTTP/3, or\nthe QUIC transport-layer INTERNAL_ERROR (0x1) for raw QUIC).\nSee stream.destroy() for a full-stream abort that also resets\nthe readable side via STOP_SENDING.desiredSize — Available capacity in bytes, or null if closed/errored.The bytes from each writeSync() / writevSync() / write() / writev()\ninput chunk are copied into an internal buffer, so the caller's source\nbuffer is unchanged and may be reused or mutated immediately after the\ncall returns. Callers that want to ensure a source buffer cannot be\nmutated after handing it off can call ArrayBuffer.prototype.transfer()\nthemselves before passing the buffer.
The session that created this stream, or null if the stream has been\ndestroyed. Read only.
The current statistics for the stream. Read only.
" } ], "methods": [ { "textRaw": "`stream.destroy([error[, options]])`", "name": "destroy", "type": "method", "meta": { "added": [ "v23.8.0" ], "changes": [ { "version": "REPLACEME", "pr-url": "https://github.com/nodejs/node/pull/62876", "description": "Added the `options` parameter accepting `code` and `reason`." } ] }, "signatures": [ { "params": [ { "textRaw": "`error` {any}", "name": "error", "type": "any", "optional": true }, { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`code` {bigint|number} The application error code to include in the `RESET_STREAM` and `STOP_SENDING` frames sent to the peer. Numbers are coerced to `BigInt`. When omitted, the wire code is derived from `error` (see below).", "name": "code", "type": "bigint|number", "desc": "The application error code to include in the `RESET_STREAM` and `STOP_SENDING` frames sent to the peer. Numbers are coerced to `BigInt`. When omitted, the wire code is derived from `error` (see below)." }, { "textRaw": "`reason` {string} An optional human-readable reason string. Accepted for symmetry with `session.close()` and `session.destroy()`, but **not transmitted on the wire** — neither `RESET_STREAM` nor `STOP_SENDING` carry a reason field. Provided for application logging and for use by the `stream.onerror` callback.", "name": "reason", "type": "string", "desc": "An optional human-readable reason string. Accepted for symmetry with `session.close()` and `session.destroy()`, but **not transmitted on the wire** — neither `RESET_STREAM` nor `STOP_SENDING` carry a reason field. Provided for application logging and for use by the `stream.onerror` callback." } ], "optional": true } ] } ], "desc": "Immediately and abruptly destroys the stream. If error is provided and\nstream.onerror is set, the onerror callback is invoked before\ndestruction. The stream.closed promise rejects with the error.
When the stream is destroyed with an error (or with an explicit\noptions.code), the QUIC stack signals the abort to the peer:
RESET_STREAM frame is sent.STOP_SENDING frame is sent.Both frames carry the same wire code, resolved with the following\nprecedence:
\noptions.code, when explicitly provided.error.errorCode, when error is a QuicError.H3_INTERNAL_ERROR (0x102) for HTTP/3, or the QUIC transport-layer\nINTERNAL_ERROR (0x1) for raw QUIC).A clean destroy — no error and no options.code — does not emit\nRESET_STREAM or STOP_SENDING; the stream's existing close machinery\nhandles teardown.
See Aborting a stream for an overview of the available stream-abort\nAPIs.
" }, { "textRaw": "`stream.sendHeaders(headers[, options])`", "name": "sendHeaders", "type": "method", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`headers` {Object} Header object with string keys and string or string-array values. Pseudo-headers (`:method`, `:path`, etc.) must appear before regular headers.", "name": "headers", "type": "Object", "desc": "Header object with string keys and string or string-array values. Pseudo-headers (`:method`, `:path`, etc.) must appear before regular headers." }, { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`terminal` {boolean} If `true`, the stream is closed for sending after the headers (no body will follow). **Default:** `false`.", "name": "terminal", "type": "boolean", "default": "`false`", "desc": "If `true`, the stream is closed for sending after the headers (no body will follow)." } ], "optional": true } ], "return": { "textRaw": "Returns: {boolean}", "name": "return", "type": "boolean" } } ], "desc": "Sends initial or response headers on the stream. For client-side streams,\nthis sends request headers. For server-side streams, this sends response\nheaders. Throws ERR_INVALID_STATE if the session does not support headers.
Sends informational (1xx) response headers. Server only. Throws\nERR_INVALID_STATE if the session does not support headers.
Sends trailing headers on the stream. Must be called synchronously during\nthe stream.onwanttrailers callback, or set ahead of time via\nstream.pendingTrailers. Throws ERR_INVALID_STATE if the session\ndoes not support headers.
Sets the priority of the stream. Throws ERR_INVALID_STATE if the session\ndoes not support priority (e.g. non-HTTP/3). Has no effect if the stream\nhas been destroyed.
The stream implements Symbol.asyncIterator, making it directly usable\nin for await...of loops. Each iteration yields a batch of Uint8Array\nchunks.
Only one async iterator can be obtained per stream. A second call throws\nERR_INVALID_STATE. Non-readable streams (outbound-only unidirectional\nor closed) return an immediately-finished iterator.
for await (const chunks of stream) {\n for (const chunk of chunks) {\n // Process each Uint8Array chunk\n }\n}\nCompatible with stream/iter utilities:
\nimport Stream from 'node:stream/iter';\nconst body = await Stream.bytes(stream);\nconst text = await Stream.text(stream);\nawait Stream.pipeTo(stream, someWriter);\nSets the outbound body source for the stream. Can only be called once.\nMutually exclusive with stream.writer.
The following body source types are supported:
\nnull — The writable side is closed immediately (FIN sent with no data).string — UTF-8 encoded and sent as a single chunk.ArrayBuffer, SharedArrayBuffer, ArrayBufferView — Sent as a single\nchunk. The bytes are copied into an internal buffer, so the caller's\nsource buffer is unchanged and may be reused or mutated immediately\nafter the call returns. Callers wanting to ensure their source cannot\nbe mutated after handing it off can call\nArrayBuffer.prototype.transfer() themselves before passing the buffer.Blob — Sent from the Blob's underlying data queue.<FileHandle> — The file contents are read asynchronously via an\nfd-backed data source. The FileHandle must be opened for reading\n(e.g. via fs.promises.open(path, 'r')). Once passed as a body, the\nFileHandle is locked and cannot be used as a body for another stream.\nThe FileHandle is automatically closed when the stream finishes.AsyncIterable, Iterable — Each yielded chunk (string or\nUint8Array) is written incrementally in streaming mode.Promise — Awaited; the resolved value is used as the body (subject\nto the same type rules).Throws ERR_INVALID_STATE if the outbound is already configured or if\nthe writer has been accessed.
A QuicStream can be aborted in three ways, each producing different\nwire-frame side effects:
\nwriter.fail(reason) — Aborts only the writable side. Sends\nRESET_STREAM to the peer. The readable side is unaffected; any data\nalready buffered for read remains available.stream.destroy() with an error argument — Tears the stream\ndown completely. Sends RESET_STREAM on any still-open writable side\nand STOP_SENDING on any still-open readable side. The wire code\nis derived from error (see stream.destroy() for the precedence\nrules).stream.destroy() with an explicit options.code — Same as the\nprevious form but with a caller-supplied wire code, which takes\nprecedence over any code carried by error.When error is a QuicError, its error.errorCode is used as\nthe wire code for both writer.fail() and stream.destroy(). Otherwise\nthe implementation falls back to the negotiated application protocol's\n\"internal error\" code (see QuicError).