events

js/net/quic/events.ts

Classes

class QuicConnectionEvent extends Event {

Event carrying a new QuicConnection, dispatched on a QuicEndpoint.

Fired as the 'connection' event when a server endpoint accepts an incoming connection, giving event-driven code an alternative to awaiting endpoint.accept().

endpoint.addEventListener('connection', (event) => {
  const conn = (event as QuicConnectionEvent).connection;
  console.log('accepted from', conn.remoteAddress.ip);
});

Readonly Properties

readonly connection: QuicConnection

The connection this event announces.

Constructors

constructor(type: string, init: { connection: QuicConnection; })

Wrap one QuicConnection in an endpoint connection event.

class QuicDatagramEvent extends Event {

Event carrying one received unreliable QUIC DATAGRAM payload.

Dispatched as 'datagram' on the connection for each received RFC 9221 DATAGRAM frame. Delivery is unreliable and unordered; earlyData marks payloads that arrived in 0-RTT packet space. The same payloads are also available through connection.datagrams as a ReadableStream.

connection.addEventListener('datagram', (event) => {
  handle((event as QuicDatagramEvent).data);
});

Readonly Properties

readonly data: Uint8Array

Datagram payload copied from ngtcp2 receive memory.

readonly earlyData: boolean

True when the datagram arrived in 0-RTT packet space.

Constructors

constructor(type: string, init: { data: Uint8Array; earlyData?: boolean; })

Create an event carrying one received QUIC DATAGRAM payload.

class QuicDatagramStatusEvent extends Event {

Event reporting the delivery outcome of a locally sent QUIC DATAGRAM.

Dispatched as 'datagramack', 'datagramlost', or 'datagramabandoned' on the connection (also reflected in status), keyed by the id returned from sendDatagram(). Because DATAGRAMs are unreliable, lost and abandoned are normal outcomes, not errors.

connection.addEventListener('datagramlost', (event) => {
  console.log('datagram lost', (event as QuicDatagramStatusEvent).id);
});

Readonly Properties

readonly id: number

Application-assigned datagram identifier passed to ngtcp2.

readonly status: QuicDatagramStatus

Delivery status reported by ngtcp2 recovery.

Constructors

constructor(type: string, init: { id: number; status: QuicDatagramStatus; })

Create an event carrying one QUIC DATAGRAM delivery status update.

class QuicEarlyDataEvent extends Event {

Event reporting whether attempted 0-RTT early data was accepted or rejected.

Dispatched as 'earlydata' on a client connection that attempted 0-RTT. When rejected is true the early data must be replayed after the handshake; reason gives a stable, application-readable cause (for example an expired or incompatible session).

connection.addEventListener('earlydata', (event) => {
  const e = event as QuicEarlyDataEvent;
  if (e.rejected) replayRequest(e.reason);
});

Readonly Properties

readonly accepted: boolean

True when the attempted 0-RTT state is usable for early writes.

readonly rejected: boolean

True when early data was attempted but cannot be used.

readonly reason: string

Stable application-readable reason for the early-data decision.

Constructors

constructor(type: string, init: { accepted: boolean; rejected: boolean; reason: string; })

Create an event carrying one 0-RTT early-data decision.

class QuicErrorEvent extends Event {

Event carrying a connection-level error, dispatched as 'error'.

Fired on the connection (and re-surfaced on the owning endpoint) when a connection fails — a handshake error, transport error, or unexpected native failure. The connection is closing or closed by the time it fires.

connection.addEventListener('error', (event) => {
  console.error('quic connection failed', (event as QuicErrorEvent).error);
});

Readonly Properties

readonly error: Error

The error that caused the connection to fail.

Constructors

constructor(type: string, init: { error: Error; })

Wrap one Error in a connection error event.

class QuicNewTokenEvent extends Event {

Event carrying a server-issued NEW_TOKEN address-validation token.

Dispatched as 'newtoken' on a client connection when the server sends a NEW_TOKEN frame. Persisting the token (for example via a session store) lets a later connection to the same address skip the Retry round trip.

connection.addEventListener('newtoken', (event) => {
  const e = event as QuicNewTokenEvent;
  saveToken(e.address, e.token);
});

Readonly Properties

readonly token: Uint8Array

Address-validation token received from a QUIC NEW_TOKEN frame.

readonly address: QuicAddress

Peer address for which the token is valid.

Constructors

constructor(type: string, init: { token: Uint8Array; address: QuicAddress; })

Create an event carrying a QUIC NEW_TOKEN address-validation token.

class QuicPathValidationEvent extends Event {

Event reporting the result of a QUIC path validation.

Dispatched as 'pathvalidation' on the connection when ngtcp2 finishes probing a network path — during connection migration or when adopting a server preferred address. result is 'success', 'failure', or 'aborted'; path is the path that was validated (or failed) and previousPath the one it may fall back to.

connection.addEventListener('pathvalidation', (event) => {
  const e = event as QuicPathValidationEvent;
  if (e.result === 'success') console.log('migrated to', e.path?.localAddress.ip);
});

Readonly Properties

readonly result: QuicPathValidationResult

Path-validation result reported by ngtcp2.

readonly path: QuicPath | null

Newly validated path, or the failed path when validation failed.

readonly previousPath: QuicPath | null

Fallback or previous path reported by ngtcp2, when available.

readonly preferredAddress: boolean

True when validation was for a server preferred address.

readonly newToken: boolean

True when validation requested NEW_TOKEN generation for the new path.

Constructors

constructor(type: string, init: { result: QuicPathValidationResult; path: QuicPath | null; previousPath?: QuicPath | null; preferredAddress?: boolean; newToken?: boolean; })

Create an event carrying path-validation result and path details.

class QuicStopSendingEvent extends Event {

Event fired when the peer asks us to stop sending on a stream (STOP_SENDING).

Dispatched as 'stopsending' on the stream: the peer no longer wants data on our sending side. errorCode is the peer's application code; the usual response is to reset the stream.

stream.addEventListener('stopsending', (event) => {
  stream.reset((event as QuicStopSendingEvent).errorCode);
});

Readonly Properties

readonly errorCode: number

Peer application error code carried by STOP_SENDING.

readonly error: Error

Error object suitable for compatibility with existing error handlers.

Constructors

constructor(type: string, init: { errorCode: number; error?: Error; })

Create an event carrying one peer STOP_SENDING application code.

class QuicStreamBlockedEvent extends Event {

Event fired when a stream cannot send because QUIC flow control blocked it.

Dispatched as 'blocked' on the connection when the peer's stream- or connection-level flow-control window is exhausted; the stream resumes automatically once the peer extends credit.

connection.addEventListener('blocked', (event) => {
  console.warn('stream flow-control blocked', (event as QuicStreamBlockedEvent).streamId);
});

Readonly Properties

readonly stream: QuicStream

Stream that was blocked by QUIC flow control.

readonly connection: QuicConnection

Owning QUIC connection.

readonly streamId: number

Numeric QUIC stream identifier.

Constructors

constructor(type: string, init: { stream: QuicStream; connection: QuicConnection; streamId?: number; })

Create an event carrying one flow-control blocked stream notification.

class QuicStreamEvent extends Event {

Event carrying a new QuicStream, dispatched on a QuicConnection.

Fired as the 'stream' event when the peer opens a stream, giving event-driven code an alternative to awaiting connection.acceptStream().

connection.addEventListener('stream', (event) => {
  const stream = (event as QuicStreamEvent).stream;
  pump(stream.readable);
});

Readonly Properties

readonly stream: QuicStream

The stream this event announces.

Constructors

constructor(type: string, init: { stream: QuicStream; })

Wrap one QuicStream in a connection stream event.

class QuicStreamResetEvent extends Event {

Event fired when the peer aborts a stream's sending side with RESET_STREAM.

Dispatched as 'reset' on the stream; the readable side ends and no further data will arrive. errorCode is the peer's application error code.

stream.addEventListener('reset', (event) => {
  console.error('peer reset stream', (event as QuicStreamResetEvent).errorCode);
});

Readonly Properties

readonly errorCode: number

Peer application error code carried by RESET_STREAM.

readonly error: Error

Error object suitable for compatibility with existing error handlers.

Constructors

constructor(type: string, init: { errorCode: number; error?: Error; })

Create an event carrying one RESET_STREAM application code.

class QuicVersionNegotiationError extends Error {

Error thrown when QUIC Version Negotiation finds no mutually supported version.

A server offered a set of versions in a Version Negotiation packet, but none of them intersects the client's enabled versions, so the handshake cannot proceed. Both version lists are exposed as raw wire numbers for diagnostics.

try {
  await endpoint.connect({ address, versions: ['v2'] });
} catch (err) {
  if (err instanceof QuicVersionNegotiationError) {
    console.error('no common version', err.requestedVersions, err.supportedVersions);
  }
}

Readonly Properties

readonly requestedVersions: readonly number[]

Wire version numbers the client offered.

readonly supportedVersions: readonly number[]

Wire version numbers the server advertised as supported.

Constructors

constructor(requestedVersions: readonly number[], supportedVersions: readonly number[])

Build the error from the offered and advertised version lists.