constructor

quic.QuicEndpoint.constructor

Not implemented in Bun

constructor QuicEndpoint(
options?: EndpointOptions

Referenced types

interface EndpointOptions

The endpoint configuration options passed when constructing a new QuicEndpoint instance.

  • address?: string | SocketAddress

    If not specified the endpoint will bind to IPv4 localhost on a random port.

  • addressLRUSize?: number | bigint

    The endpoint maintains an internal cache of validated socket addresses as a performance optimization. This option sets the maximum number of addresses that are cached. This is an advanced option that users typically won't have need to specify.

  • blockList?: BlockList

    An optional net.BlockList instance for filtering incoming packets by source address. When configured, every received UDP packet is checked against the block list before any QUIC processing occurs, minimizing resource expenditure on blocked sources. The block list is evaluated live — rules added to the BlockList object after the endpoint is created take effect immediately.

    See endpointOptions.blockListPolicy for how matches are interpreted.

  • blockListPolicy?: 'deny' | 'allow'

    Controls how the endpointOptions.blockList is interpreted:

    • 'deny' — Packets from addresses matching the block list are dropped. All other addresses are accepted. This is the typical blocklist mode.
    • 'allow' — Only packets from addresses matching the block list are accepted. All other addresses are dropped. This is an allowlist mode for restricting access to known clients.

    If no block list is configured, this option has no effect.

  • disableStatelessReset?: boolean

    When true, the endpoint will not send stateless reset packets in response to packets from unknown connections. Stateless resets allow a peer to detect that a connection has been lost even when the server has no state for it. Disabling them may be useful in testing or when stateless resets are handled at a different layer.

  • idleTimeout?: number

    The number of seconds an endpoint will remain alive after all sessions have closed and it is no longer listening. A value of 0 (default) means the endpoint is only destroyed when explicitly closed via endpoint.close() or endpoint.destroy(). A positive value starts an idle timer when the endpoint becomes idle; if no new sessions are created before the timer fires, the endpoint is automatically destroyed. This is useful for connection pooling where endpoints should linger briefly for reuse by future connect() calls.

  • immediateCloseBurst?: number

    The maximum burst of immediate connection close packets allowed before rate limiting takes effect.

  • immediateCloseRate?: number

    The maximum number of immediate connection close packets the endpoint will send per second.

  • ipv6Only?: boolean

    When true, indicates that the endpoint should bind only to IPv6 addresses.

  • maxConnectionsPerHost?: number

    Specifies the maximum number of concurrent sessions allowed per remote IP address (ignoring port). When the limit is reached, new connections from the same IP are refused with CONNECTION_REFUSED. A value of 0 disables the limit. The maximum value is 65535.

    This limit can also be changed dynamically after construction via endpoint.maxConnectionsPerHost.

  • maxConnectionsTotal?: number

    Specifies the maximum total number of concurrent sessions across all remote addresses. When the limit is reached, new connections are refused with CONNECTION_REFUSED. A value of 0 disables the limit. The maximum value is 65535.

    This limit can also be changed dynamically after construction via endpoint.maxConnectionsTotal.

  • resetTokenSecret?: ArrayBufferView<ArrayBufferLike>

    Specifies the 16-byte secret used to generate QUIC retry tokens.

  • retryBurst?: number

    The maximum burst of retry packets allowed before rate limiting takes effect.

  • retryRate?: number

    The maximum number of QUIC retry packets the endpoint will send per second. This is a global rate limit (not per-host) that caps the total server-wide retry response rate, preventing spoofed-source floods from consuming unbounded resources.

  • retryTokenExpiration?: number | bigint

    Specifies the length of time a QUIC retry token is considered valid.

  • sessionCreationBurst?: number

    The maximum burst of new session creations allowed from a single remote address before rate limiting takes effect.

  • sessionCreationRate?: number

    The maximum number of new sessions that a single remote address can create per second. This is a per-host rate limit tracked in the address validation LRU cache. It prevents a validated remote address from churning through sessions (rapidly opening and abandoning connections) faster than the server can handle. For benchmarking where traffic comes from a single source, set this to a high value.

  • statelessResetBurst?: number

    The maximum burst of stateless reset packets allowed before rate limiting takes effect.

  • statelessResetRate?: number

    The maximum number of stateless reset packets the endpoint will send per second.

  • tokenExpiration?: number | bigint

    Specifies the length of time a QUIC token is considered valid.

  • tokenSecret?: ArrayBufferView<ArrayBufferLike>

    Specifies the 16-byte secret used to generate QUIC tokens.

  • udpTTL?: number
  • validateAddress?: boolean

    When true, requires that the endpoint validate peer addresses using retry packets while establishing a new connection.

  • versionNegotiationBurst?: number

    The maximum number of immediate connection close packets the endpoint will send per second.

  • versionNegotiationRate?: number

    The maximum number of version negotiation packets the endpoint will send per second.

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 immediate connection close packets sent by this endpoint. Read only.

    • readonly immediateCloseRateLimited: bigint

      The total number of immediate connection close packets dropped by the global rate limiter. Read only.

    • readonly packetsBlocked: bigint

      The total number of incoming packets dropped by the block list filter. 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 retry packets sent by this endpoint. Read only.

    • readonly retryRateLimited: bigint

      The total number of retry packets dropped by the global rate limiter. Read only. A non-zero value indicates the endpoint is under retry flood pressure.

    • 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 sessionCreationRateLimited: bigint

      The total number of session creation attempts dropped by the per-host rate limiter. Read only. A non-zero value indicates one or more remote addresses are creating sessions faster than the configured rate allows.

    • readonly statelessResetCount: bigint

      The total number of stateless reset packets sent by this endpoint. Read only.

    • readonly statelessResetRateLimited: bigint

      The total number of stateless reset packets dropped by the global rate limiter. Read only.

    • readonly versionNegotiationCount: bigint

      The total number of version negotiation packets sent by this endpoint. Read only.

    • readonly versionNegotiationRateLimited: bigint

      The total number of version negotiation packets dropped by the global rate limiter. Read only.