function

quic.connect

function connect(
address: string | SocketAddress,
options?: SessionOptions
): Promise<QuicSession>;

Initiate a new client-side session.

import { connect } from 'node:quic';
import { Buffer } from 'node:buffer';

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

By default, every call to connect(...) 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.

import { QuicEndpoint, connect } from 'node:quic';

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

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

Referenced types

  • readonly address: string

    Either 'ipv4' or 'ipv6'.

  • readonly family: IPVersion

    Either 'ipv4' or 'ipv6'.

  • readonly flowlabel: number
  • readonly port: number
  • static parse(
    input: string
    ): undefined | SocketAddress;
    @param input

    An input string containing an IP address and optional port, e.g. 123.1.2.3:1234 or [1::1]:1234.

    @returns

    Returns a SocketAddress if parsing was successful. Otherwise returns undefined.

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.

  • application?: ApplicationOptions

    HTTP/3 application-specific options. These only apply when the negotiated ALPN selects the HTTP/3 application ('h3').

  • 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.

  • datagramDropPolicy?: 'drop-oldest' | 'drop-newest'

    Controls which datagram to drop when the pending datagram queue (sized by session.maxPendingDatagrams) is full. Must be one of 'drop-oldest' (discard the oldest queued datagram to make room) or 'drop-newest' (reject the incoming datagram). Dropped datagrams are reported as lost via the ondatagramstatus callback.

    This option is immutable after session creation.

  • drainingPeriodMultiplier?: number

    A multiplier applied to the Probe Timeout (PTO) to compute the draining period duration after receiving a CONNECTION_CLOSE frame from the peer. RFC 9000 Section 10.2 requires the draining period to persist for at least three times the current PTO. The valid range is 3 to 255. Values below 3 are clamped to 3.

  • enableEarlyData?: boolean

    When true, enables TLS 0-RTT early data for this session. Early data allows the client to send application data before the TLS handshake completes, reducing latency on reconnection when a valid session ticket is available. Set to false to disable early data support.

  • endpoint?: QuicEndpoint | EndpointOptions

    An endpoint to use.

  • groups?: string

    The list of supported TLS 1.3 cipher groups.

  • handshakeTimeout?: number | bigint

    Specifies the keep-alive timeout in milliseconds. When set to a non-zero value, PING frames will be sent automatically to keep the connection alive before the idle timeout fires. The value should be less than the effective idle timeout (maxIdleTimeout transport parameter) to be useful.

  • keylog?: boolean

    When true, enables TLS key logging for the session. Key material is delivered to the session.onkeylog callback in NSS Key Log Format. Each callback invocation receives a single line of key material. The output can be used with tools such as Wireshark to decrypt captured QUIC traffic.

  • 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.

  • maxDatagramSendAttempts?: number

    The maximum number of SendPendingData cycles a datagram can survive without being sent before it is abandoned. When a datagram cannot be sent due to congestion control or packet size constraints, it remains in the queue and the attempt counter increments. Once the limit is reached, the datagram is dropped and reported as 'abandoned' via the ondatagramstatus callback. Valid range: 1 to 255.

  • 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.

  • onearlyrejected?: (this: QuicSession) => void
  • onerror?: (this: QuicSession, error: any) => void
  • ongoaway?: (this: QuicSession, lastStreamId: bigint) => void
  • onheaders?: (this: QuicStream, headers: Dict<string | string[]>) => void
  • oninfo?: (this: QuicStream, headers: Dict<string | string[]>) => void
  • ontrailers?: (this: QuicStream, trailers: Dict<string | string[]>) => void
  • onwanttrailers?: (this: QuicStream) => void
  • preferredAddressPolicy?: 'ignore' | 'default' | 'use'

    When the remote peer advertises a preferred address, this option specifies whether to use it or ignore it.

  • qlog?: boolean

    When true, enables qlog diagnostic output for the session. Qlog data is delivered to the session.onqlog callback as chunks of JSON-SEQ formatted text. The output can be analyzed with qlog visualization tools such as qvis.

  • rejectUnauthorized?: boolean

    If true, the peer certificate is verified against the list of supplied CAs. An error is emitted if verification fails; the error can be inspected via the validationErrorReason and validationErrorCode fields in the handshake callback. If false, peer certificate verification errors are ignored.

  • reuseEndpoint?: boolean

    When true (the default), connect() will attempt to reuse an existing endpoint rather than creating a new one for each session. This provides connection pooling behavior — multiple sessions can share a single UDP socket. The reuse logic will not return an endpoint that is listening on the 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 is useful when endpoint isolation is required (e.g., testing stateless reset behavior where source port identity matters).

  • 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 and must contain at least one entry. The special key '*' specifies the optional default/fallback identity used when no other host name matches. If no wildcard entry is provided, connections with unrecognized server names will be rejected with a TLS unrecognized_name alert. Each entry may contain:

  • tlsTrace?: boolean

    True to enable TLS tracing output.

  • token?: ArrayBufferView<ArrayBufferLike>

    An opaque address validation token previously received from the server via the session.onnewtoken callback. Providing a valid token on reconnection allows the client to skip the server's address validation, reducing handshake latency.

  • 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 QuicSession