Fconnect
Bun

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.

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