nish/net/quic-listener

What a QUIC version 1 server answers to a datagram no connection owns: Version Negotiation for a version it does not speak (RFC 9000 §6, §17.2.1), a Retry that asks a client to prove its address before any connection state exists (§8.1.2, §17.2.5), and a stateless reset for a packet sent to a connection the server no longer has (§10.3). Sans-IO, like the rest of nish/net, and stateless in the sense the RFC means: nothing it answers depends on any connection.

import {
  QUIC_LISTENER_ANSWER_SIZE,
  QUIC_LISTENER_ENTROPY_SIZE,
  QUIC_LISTENER_FLIGHT_MAX,
  QUIC_LISTENER_FLIGHT_QUANTUM,
  QUIC_LISTENER_MAX_TOKEN_LIFETIME,
  QUIC_LISTENER_MIN_RESET,
  QUIC_LISTENER_RESET_BURST,
  QUIC_LISTENER_RESET_INTERVAL,
  QUIC_LISTEN_ACCEPT,
  QUIC_LISTEN_DROP,
  QUIC_LISTEN_INVALID_TOKEN,
  QUIC_LISTEN_RETRY,
  QUIC_LISTEN_STATELESS_RESET,
  QUIC_LISTEN_VERSION_NEGOTIATION,
  QuicFlight,
  QuicListener,
  QuicListenerAnswer,
  quicListenerFlightTime,
  quicListenerPaceTime,
  quicListenerReceiveSegments,
  quicListenerTakeFlight,
  quicListenerTakePaced,
} from "nish/net/quic-listener";
import { QuicListener, QuicListenerAnswer, QUIC_LISTEN_ACCEPT, QUIC_LISTENER_ANSWER_SIZE } from "nish/net/quic-listener";
import { QuicConnection } from "nish/net/quic";

const listener = new QuicListener(config, entropy);      // entropy: QUIC_LISTENER_ENTROPY_SIZE random bytes
const answer = new QuicListenerAnswer(QUIC_LISTENER_ANSWER_SIZE);  // once, beside the listener
// For a datagram buf[at .. at + len) whose first packet no connection owns:
if (listener.handleWindow(buf, at, len, fromAddress, now, answer) === QUIC_LISTEN_ACCEPT) {
  const conn = new QuicConnection(config, connectionEntropy);
  if (answer.retried) { conn.acceptRetry(answer.originalDcid, answer.retryScid); }
  conn.receiveWindow(buf, at, len, now);
} else if (toI32(answer.reply.length) > 0) {
  … send answer.reply back to fromAddress …
}

Nothing is kept per datagram (H3-3 in docs/security/http3.md). handleWindow reads the datagram where it lies, its header parsed in place, and writes every answer into the caller's QuicListenerAnswer, whose arrays were given their room once; every MAC, key and seal is computed in scratch the listener made at start-up. handle is the same over a whole array, into an answer of its own each time, for a caller that keeps them.

Routing is the caller's

The listener sees only datagrams the caller could not hand to a live connection, and it must see only those: a stateless reset carries the token for the packet's connection ID, and handing the listener a packet for a connection that is still alive would give that token, which ends the connection, to whoever sent it (RFC 9000 §21.11).

Retry tokens

Retry tokens (§8.1.4). They are this server's own format: a marker byte, the time the token was issued, and the client's original Destination Connection ID, then 16 bytes of HMAC-SHA256 under the configuration's retryTokenKey over all of that, the Retry's Source Connection ID (which the client's next Initial must be sent to) and the client's address as the caller gives it, port included. So a token is good only from the address it was sent to, only for the connection it was issued for, and only for retryTokenLifetime milliseconds.

A token that carries the marker and fails any of that is an invalid Retry token, which closes the attempt with INVALID_TOKEN (§8.1.2); a token without the marker, which some other server issued, is treated as no token at all (§8.1.3).

Stateless resets

Stateless resets (§10.3). They end in the token quicStatelessResetToken derives (computed in place, by quicConnResetTokenInto) from the configuration's static key and the packet's connection ID, so a server that restarted with the same key can end the connections it lost. RFC 9000 §10.3 and §10.3.3 bound them, and each bound is held here.

A reset is sent only for a short header, and is always shorter than the datagram that caused it, so two endpoints resetting each other shrink to nothing; one byte shorter for a datagram of 43 bytes or fewer, and never under 21 bytes, so a datagram of 21 or fewer gets none. That also bounds amplification at less than one to one. They are rate limited: QUIC_LISTENER_RESET_BURST at once, then one per QUIC_LISTENER_RESET_INTERVAL milliseconds. Each reset's other bytes are unpredictable, from the listener's own generator.

Pacing

Pacing (RFC 9002 §7.7). It is the carrier's send loop, so it is here beside the rest of what the carrier calls: quicListenerTakePaced takes a connection's next datagram only when its pacer has the credit for it, and quicListenerPaceTime says when it will. The pacer earns 5/4 of the congestion window per smoothed RTT and lets a burst of at most the initial window go at once, so a flight leaves spread over the round trip instead of in one burst that overruns a queue on the path.

let out: u8[] | null = quicListenerTakePaced(conn, now);
while (out !== null) { … send it with conn.datagramEcn … ; out = quicListenerTakePaced(conn, now); }
… and wake at the earlier of conn.deadline() and quicListenerPaceTime(conn, now)

A carrier that sends whole flights with quicListenerTakeFlight, below, wakes at quicListenerFlightTime instead, as Http3Server does: a flight waits for more credit than one datagram, so the pace time can come first.

GSO and GRO

GSO and GRO (nish:net's UDP_SEGMENT and UDP_GRO). A carrier that sends with segmentation offload takes a whole flight at once: quicListenerTakeFlight writes as many datagrams as the pacer has credit for back to back into one buffer, every one the connection's datagramSize() but the last, which is what one udpSendTo with that segment size cuts back into datagrams; each is written in place, so a flight allocates nothing.

The flight is paced as a whole: it is as long as the pacer's credit, and charged to it datagram by datagram, so a burst is never more than the initial window however the carrier sends it. It starts only on a millisecond's earning, up to four datagrams, so a fast connection's pacer, which earns by the microsecond, does not let it out a datagram per send; quicListenerFlightTime says when. On the receiving side, quicListenerReceiveSegments hands a connection the datagrams of one GRO receive, segment by segment, in place.

ECN

ECN (RFC 9000 §13.4). A carrier whose platform sends the ECN bits it is given sets the connection's ecnMarking and sends each datagram with the codepoint the connection marked it with: conn.datagramEcn after a takeDatagramInto or quicListenerTakePaced, flight.ecn for a flight. One send carries one codepoint, so a flight ends before a datagram the connection would mark otherwise. The listener's own answers go unmarked. On the receiving side, a carrier whose platform reports the bits a datagram arrived with (udpRecvFrom's meta[1]) sets conn.arrivalEcn to them before handing the datagram over, quicListenerReceiveSegments included: one receive is one codepoint for all its segments. The connection then counts them per packet number space and its ACKs carry the counts as an ACK_ECN (§13.4.1).

const flight = new QuicFlight();
const n: i32 = quicListenerTakeFlight(conn, now, buf, 0, toI32(buf.length), flight);
if (n > 0) { udpSendTo(fd, buf, 0, n, peer, flight.count > 1 ? flight.segment : 0, flight.ecn); }
Sans-IO and deterministic

The caller gives the time, the client's address and, once, QUIC_LISTENER_ENTROPY_SIZE random bytes: every unpredictable byte the listener sends (a Retry's connection ID and unused bits, Version Negotiation's unused bits, a reset's padding and length) is HMAC-SHA256 under that seed of a counter. So a recorded exchange replays byte for byte.

Secrets

The seed lives in the listener and the static keys in the QuicServerConfig, for the server's lifetime, as plain bytes, since a Secret may not be a field (NL2430). release() wipes the listener's own, and Http3Server.stop the configuration's with them; QUIC-5 in docs/security/quic.md records what is left.

Written from RFC 9000, in this module's own structure; nothing here is ported from another implementation. Private names carry the quicListener prefix (docs/wp26-stdlib.md §3e).

Functions

quicListenerFlightTime

When quicListenerTakeFlight next lets conn start a flight, in the caller's milliseconds: now when it may already.

const quicListenerFlightTime: (
  conn: QuicConnection,
  now: i64,
) => i64
connQuicConnectionrequired

The connection to ask about.

nowi64required

The caller's time in milliseconds.

returnsi64

A time in milliseconds, now or later. It says nothing of whether a datagram is due.

quicListenerPaceTime

When quicListenerTakePaced next lets conn send a full datagram, in the caller's milliseconds: now when it may already.

const quicListenerPaceTime: (
  conn: QuicConnection,
  now: i64,
) => i64
connQuicConnectionrequired

The connection to ask about.

nowi64required

The caller's time in milliseconds.

returnsi64

A time in milliseconds, now or later. It says nothing of whether a datagram is due.

quicListenerReceiveSegments

Hands conn the datagrams of one receive, buf[off .. off + len), at now: one datagram when segment is 0, else a GRO receive cut every segment bytes (the last may be shorter). Each is read in place, with the ECN bits the caller set in conn.arrivalEcn. Answers how many it handed over.

const quicListenerReceiveSegments: (
  conn: QuicConnection,
  buf: u8[],
  off: i32,
  len: i32,
  segment: i32,
  now: i64,
) => i32
connQuicConnectionrequired

The connection the datagrams belong to.

bufu8[]required

The receive buffer; read, not kept.

offi32required

The index in buf of the first byte received.

leni32required

The bytes received.

segmenti32required

The GRO segment size in bytes, or 0 (or less) for a single datagram.

nowi64required

The caller's time in milliseconds.

returnsi32

How many datagrams were handed over: always 1 when segment is 0 or less, whatever len; otherwise one per segment bytes of len, rounded up, which is 0 when len is 0 or less.

quicListenerTakeFlight

Writes the next flight conn sends at now into buf[at .. at + cap), datagram after datagram, for one GSO send, and answers its length in bytes (0 for none); flight says how many datagrams it holds and the segment size.

A flight starts only once the pacer has the credit quicListenerFlightTime waits for, a millisecond's earning of one to four datagrams; then each datagram goes only when the pacer has credit for a full one (RFC 9002 §7.7) and is charged at its real size, as quicListenerTakePaced does, so the flight is the pacer's whole credit and no more. Every datagram after the first is held to the first's size, the segment, and the flight stops at the first datagram shorter than the segment or than the connection's datagramSize(), which can only be the last of a segmented send, at QUIC_LISTENER_FLIGHT_MAX datagrams, when cap has no room for another, and before a datagram whose ECN codepoint would not be the first's. A path MTU probe (see QuicConnection.pathMtu) goes only when cap has room for it, so a carrier gives QUIC_CONN_DATAGRAM_MAX bytes or more to let the connection discover a larger path.

const quicListenerTakeFlight: (
  conn: QuicConnection,
  now: i64,
  buf: u8[],
  at: i32,
  cap: i32,
  flight: QuicFlight,
) => i32
connQuicConnectionrequired

The connection to send for.

nowi64required

The caller's time in milliseconds.

bufu8[]required

Where the flight is written.

ati32required

The index in buf of the flight's first byte.

capi32required

The bytes of buf from at the flight may use; under QUIC_CONN_DATAGRAM_SIZE sends nothing.

flightQuicFlightrequired

Overwritten with the flight's datagram count, segment size and ECN codepoint; all 0 when nothing was written.

returnsi32

The flight's length in bytes, or 0 when the pacer holds it back or nothing is due.

quicListenerTakePaced

The next datagram conn sends at now, as takeDatagram answers it, but only when the connection's pacer has the credit for a full datagram (RFC 9002 §7.7); null when it has not, or when nothing is due. The datagram is charged to the pacer at its real size.

const quicListenerTakePaced: (
  conn: QuicConnection,
  now: i64,
) => u8[] | null
connQuicConnectionrequired

The connection to send for.

nowi64required

The caller's time in milliseconds.

returnsu8[] | null

A new datagram to send, the caller's; or null when the pacer holds it back or nothing is due.

Classes

QuicFlight

What quicListenerTakeFlight wrote: how many datagrams, and the segment size to send them with.

class QuicFlight
Member
new QuicFlight()
count: i32 The datagrams in the flight.
ecn: i32 The ECN codepoint every datagram of the flight was marked with: the one to send with.
segment: i32 Every datagram's size but the last's, which may be shorter: the UDP_SEGMENT to send with.

QuicListener

The server's answers to datagrams no connection owns, under one QuicServerConfig. Make one when the server starts, with the same configuration its connections use, and hand it every such datagram with the address it came from and the time.

A configuration whose statelessResetKey or retryTokenKey is not QUIC_CONN_STATIC_KEY_SIZE bytes, or whose retryTokenLifetime is outside 1 to QUIC_LISTENER_MAX_TOKEN_LIFETIME, or entropy of another length, make a listener that drops everything.

Everything an answer is computed in is made here, once: the header a datagram is parsed into, the HMAC and HKDF scratch, the Initial secrets and key slots of the INVALID_TOKEN close, and the generator's block. So handleWindow reads the datagram where it lies and keeps nothing.

class QuicListener
Member
new QuicListener(config: QuicServerConfig, entropy: u8[]) A listener under config; entropy's QUIC_LISTENER_ENTROPY_SIZE bytes are copied, then wiped in the caller's array.
initialClient: u8[] The Initial secrets of an INVALID_TOKEN close, and its keys, both directions.
initialServer: u8[] The server's Initial secret of an INVALID_TOKEN close; initialClient is the client's.
kdf: HkdfScratch Every HMAC and HKDF the listener computes runs here; its sha256 makes tokens, resets and the generator's blocks.
pool: u8[] Unpredictable bytes not yet used, from poolHead, and the counter the next block is made from.
poolHead: i32 Where the unused bytes of pool start: QUIC_LISTENER_POOL when it is spent.
readSlot: QuicKeysSlot The INVALID_TOKEN close's keys for reading the client's Initial.
resetsLimited: i32 Stateless resets the rate limit held back, which a log or test reads to see the limit working.
resetsSent: i32 Stateless resets sent, and ones the rate limit held back.
seed: u8[] The 32 bytes of entropy every unpredictable byte is made from; release wipes it.
spare: QuicListenerAnswer What handle answers into before it copies the answer out.
tag: u8[] A full HMAC-SHA256 tag, wiped once its 16 bytes are used.
writeSlot: QuicKeysSlot The INVALID_TOKEN close's keys for sealing the server's Initial.
handle(datagram: u8[], address: u8[], now: i64): QuicListenerAnswer handleWindow over the whole of datagram, into an answer of its own, made with exactly the room its reply takes: for a caller that keeps each answer, at the cost of one QuicListenerAnswer a datagram. A carrier makes one answer and calls handleWindow.
handleWindow(datagram: u8[], at: i32, len: i32, address: u8[], now: i64, answer: QuicListenerAnswer): i32 Decides what to answer a datagram whose first packet no connection owns, datagram[at .. at + len), read where it lies, from address (the client's address as the caller's socket reports it, port included) at now (the caller's monotonic time in milliseconds), into answer, whose arrays are refilled in their own room. Answers answer.kind. See the module header for the rules; nothing a peer sends makes it panic, and nothing it does keeps arena memory. A window outside datagram is the caller's mistake, and panics.
release(): void Ends the listener: wipes the seed and the generator's unused bytes, the tag and the HMAC and HKDF scratch, the INVALID_TOKEN close's Initial secrets and key slots, and handle's spare answer, which holds the last one; handle and handleWindow then drop every datagram they are handed. The other methods still run, under the zeroed seed, and are the caller's not to call. What handle returned is the caller's to wipe. The configuration's keys are not the listener's to wipe: Http3Server.stop wipes them with the rest of the server.

QuicListenerAnswer

What QuicListener.handleWindow decided about one datagram: kind is a QUIC_LISTEN_*, and reply the datagram to send back, empty when there is none. For QUIC_LISTEN_ACCEPT after a Retry, retried is set and originalDcid and retryScid are what QuicConnection.acceptRetry takes.

Make one once, with QUIC_LISTENER_ANSWER_SIZE as its room, and hand it to every handleWindow: the constructor gives reply that room and each ID 20 bytes, and each answer refills them in it, its length the answer's, so answering allocates nothing (H3-3). A smaller room still works, and grows the first time an answer needs more; handle makes each answer with exactly the room its reply takes.

class QuicListenerAnswer
Member
new QuicListenerAnswer(room: i32) An empty answer with room for a reply of room bytes.
kind: i32 What to do with the datagram: a QUIC_LISTEN_*, QUIC_LISTEN_DROP after wipe.
originalDcid: u8[] After a Retry, the DCID of the client's first Initial, which QuicConnection.acceptRetry checks.
reply: u8[] The datagram to send back to the peer's address; empty when the answer sends nothing.
retried: boolean Whether an accepted Initial carried a valid Retry token, so originalDcid and retryScid are set.
retryScid: u8[] After a Retry, the SCID the Retry chose, which QuicConnection.acceptRetry checks.
wipe(): void Zeroes the last answer: reply across its whole room and each ID across its 20 bytes, so a Retry's token, a stateless reset's token and the IDs leave no copy beyond the arrays' lengths either. Each is left that long and all zero, kind a drop. An answer whose reply grew past its room keeps what lies beyond the longest length it is wiped at; one made with QUIC_LISTENER_ANSWER_SIZE never grows. The caller's to call once it has sent the answer QuicListener.handle gave, and before it drops it.

Limits

QUIC_​CONN_​DATAGRAM_​SIZE

QUIC_LISTENER_ANSWER_SIZE: i32

The largest answer the listener sends, and so the room QuicListenerAnswer makes for reply: a stateless reset is at most a full datagram (RFC 9000 §10.3); a Version Negotiation packet, which echoes two IDs of up to 255 bytes, a Retry and the INVALID_TOKEN close are all shorter.

64

QUIC_LISTENER_FLIGHT_MAX: i32

The most datagrams one GSO send carries: Linux's UDP_MAX_SEGMENTS.

4,800

QUIC_LISTENER_FLIGHT_QUANTUM: i32

The most credit a paced flight waits for before it starts: four datagrams.

60,000

QUIC_LISTENER_MAX_TOKEN_LIFETIME: i64

The longest a Retry token may be accepted for, in milliseconds: a client returns one within a round trip.

21

QUIC_LISTENER_MIN_RESET: i32

The smallest stateless reset (RFC 9000 §10.3): a first byte, at least 38 unpredictable bits after the fixed ones, and the 16-byte token.

16

QUIC_LISTENER_RESET_BURST: i32

The most stateless resets the listener sends at once, before the rate limit applies.

Constants

32

QUIC_LISTENER_ENTROPY_SIZE: i32

How many random bytes the constructor takes: the seed of every unpredictable byte the listener sends.

100

QUIC_LISTENER_RESET_INTERVAL: i64

After the burst, one stateless reset per this many milliseconds.

1

QUIC_LISTEN_ACCEPT: i32

Make a connection and hand it the datagram; after a Retry, acceptRetry it first.

0

QUIC_LISTEN_DROP: i32

Nothing to send and no connection to make: the datagram is dropped.

4

QUIC_LISTEN_INVALID_TOKEN: i32

Send reply, an Initial carrying CONNECTION_CLOSE with INVALID_TOKEN (§8.1.2).

3

QUIC_LISTEN_RETRY: i32

Send reply, a Retry packet with an address-validation token (§17.2.5).

5

QUIC_LISTEN_STATELESS_RESET: i32

Send reply, a stateless reset (§10.3).

2

QUIC_LISTEN_VERSION_NEGOTIATION: i32

Send reply, a Version Negotiation packet (RFC 9000 §17.2.1).