function

quic.listen

function listen(

Configures the endpoint to listen as a server. When a new session is initiated by a remote peer, the given onsession callback will be invoked with the created session.

import { listen } from 'node:quic';

const endpoint = await listen((session) => {
  // ... handle the session
});

// Closing the endpoint allows any sessions open when close is called
// to complete naturally while preventing new sessions from being
// initiated. Once all existing sessions have finished, the endpoint
// will be destroyed. The call returns a promise that is resolved once
// the endpoint is destroyed.
await endpoint.close();

By default, every call to listen(...) will create a new local QuicEndpoint instance bound to a new random local IP port. To specify the exact local address to use, or to multiplex multiple QUIC sessions over a single local port, pass the endpoint option with either a QuicEndpoint or EndpointOptions as the argument.

At most, any single QuicEndpoint can only be configured to listen as a server once.

Referenced types

type OnSessionCallback = (this: QuicEndpoint, session: QuicSession) => void

interface SessionOptions

alpn?: string | readonly string[]
The ALPN (Application-Layer Protocol Negotiation) identifier(s).
For client sessions, this is a single string specifying the protocol the client wants to use (e.g. 'h3').
For server sessions, this is an array of protocol names in preference order that the server supports (e.g. ['h3', 'h3-29']). During the TLS handshake, the server selects the first protocol from its list that the client also supports.
The negotiated ALPN determines which Application implementation is used for the session. 'h3' and 'h3-*' variants select the HTTP/3 application; all other values select the default application.
ca?: ArrayBuffer | ArrayBufferView<ArrayBufferLike> | readonly unknown[]
The CA certificates to use for client sessions. For server sessions, CA certificates are specified per-identity in the sessionOptions.sni map.
cc?: 'reno' | 'cubic' | 'bbr'
Specifies the congestion control algorithm that will be used. Must be set to one of either 'reno', 'cubic', or 'bbr'.
This is an advanced option that users typically won't have need to specify.
certs?: ArrayBuffer | ArrayBufferView<ArrayBufferLike> | readonly unknown[]
The TLS certificates to use for client sessions. For server sessions, certificates are specified per-identity in the sessionOptions.sni map.
ciphers?: string
The list of supported TLS 1.3 cipher algorithms.
crl?: ArrayBuffer | ArrayBufferView<ArrayBufferLike> | readonly unknown[]
The CRL to use for client sessions. For server sessions, CRLs are specified per-identity in the sessionOptions.sni map.
endpoint?: QuicEndpoint | EndpointOptions
An endpoint to use.
groups?: string
The list of support TLS 1.3 cipher groups.
handshakeTimeout?: number | bigint
Specifies the maximum number of milliseconds a TLS handshake is permitted to take to complete before timing out.
keylog?: boolean
True to enable TLS keylogging output.
keys?: KeyObject | readonly KeyObject[]
The TLS crypto keys to use for client sessions. For server sessions, keys are specified per-identity in the sessionOptions.sni map.
maxPayloadSize?: number | bigint
Specifies the maximum UDP packet payload size.
maxStreamWindow?: number | bigint
Specifies the maximum stream flow-control window size.
maxWindow?: number | bigint
Specifies the maximum session flow-control window size.
minVersion?: number
The minimum QUIC version number to allow. This is an advanced option that users typically won't have need to specify.
preferredAddressPolicy?: 'ignore' | 'default' | 'use'
When the remote peer advertises a preferred address, this option specifies whether to use it or ignore it.
qlog?: boolean
True if qlog output should be enabled.
servername?: string
The peer server name to target (SNI). Defaults to 'localhost'.
sessionTicket?: ArrayBufferView<ArrayBufferLike>
A session ticket to use for 0RTT session resumption.
sni?: Record<string, SNIEntry>
An object mapping host names to TLS identity options for Server Name Indication (SNI) support. This is required for server sessions. The special key '*' specifies the default/fallback identity used when no other host name matches. Each entry may contain:
const endpoint = await listen(callback, { sni: { '*': { keys: [defaultKey], certs: [defaultCert] }, 'api.example.com': { keys: [apiKey], certs: [apiCert] }, 'www.example.com': { keys: [wwwKey], certs: [wwwCert], ca: [customCA] }, }, });
Shared TLS options (such as ciphers, groups, keylog, and verifyClient) are specified at the top level of the session options and apply to all identities. Each SNI entry overrides only the per-identity certificate fields.
The SNI map can be replaced at runtime using endpoint.setSNIContexts(), which atomically swaps the map for new sessions while existing sessions continue to use their original identity.
tlsTrace?: boolean
True to enable TLS tracing output.
transportParams?: TransportParams
The QUIC transport parameters to use for the session.
unacknowledgedPacketThreshold?: number | bigint
Specifies the maximum number of unacknowledged packets a session should allow.
verifyClient?: boolean
True to require verification of TLS client certificate.
verifyPrivateKey?: boolean
True to require private key verification for client sessions. For server sessions, this option is specified per-identity in the sessionOptions.sni map.
version?: number
The QUIC version number to use. This is an advanced option that users typically won't have need to specify.

namespace QuicEndpoint

class Stats
A view of the collected statistics for an endpoint.
- readonly bytesReceived: bigint
  The total number of bytes received by this endpoint. Read only.
- readonly bytesSent: bigint
  The total number of bytes sent by this endpoint. Read only.
- readonly clientSessions: bigint
  The total number of sessions initiated by this endpoint. Read only.
- readonly createdAt: bigint
  A timestamp indicating the moment the endpoint was created. Read only.
- readonly destroyedAt: bigint
  A timestamp indicating the moment the endpoint was destroyed. Read only.
- readonly immediateCloseCount: bigint
  The total number of sessions that were closed before handshake completed. Read only.
- readonly packetsReceived: bigint
  The total number of QUIC packets successfully received by this endpoint. Read only.
- readonly packetsSent: bigint
  The total number of QUIC packets successfully sent by this endpoint. Read only.
- readonly retryCount: bigint
  The total number of QUIC retry attempts on this endpoint. Read only.
- readonly serverBusyCount: bigint
  The total number of times an initial packet was rejected due to the endpoint being marked busy. Read only.
- readonly serverSessions: bigint
  The total number of peer-initiated sessions received by this endpoint. Read only.
- readonly statelessResetCount: bigint
  The total number of stateless resets handled by this endpoint. Read only.
- readonly versionNegotiationCount: bigint
  The total number sessions rejected due to QUIC version mismatch. Read only.

quic.listen

Referenced types

interface SessionOptions

namespace QuicEndpoint

class Stats