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 …
}
quicListenerFlightTime
When quicListenerTakeFlight next lets conn start a flight, in the caller's milliseconds: now when it may already.
quicListenerPaceTime
When quicListenerTakePaced next lets conn send a full datagram, in the caller's milliseconds: now when it may already.
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).
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.
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.
QuicFlight
What quicListenerTakeFlight wrote: how many datagrams, and the segment size to send them with.
QuicListener
The server's answers to datagrams no connection owns, under one QuicServerConfig.
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.
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
connQuicConnectionrequiredThe connection to ask about.
nowi64requiredThe caller's time in milliseconds.
returnsi64A 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
connQuicConnectionrequiredThe connection to ask about.
nowi64requiredThe caller's time in milliseconds.
returnsi64A 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
connQuicConnectionrequiredThe connection the datagrams belong to.
bufu8[]requiredThe receive buffer; read, not kept.
offi32requiredThe index in buf of the first byte received.
leni32requiredThe bytes received.
segmenti32requiredThe GRO segment size in bytes, or 0 (or less) for a single datagram.
nowi64requiredThe 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
connQuicConnectionrequiredThe connection to send for.
nowi64requiredThe caller's time in milliseconds.
bufu8[]requiredWhere the flight is written.
ati32requiredThe index in buf of the flight's first byte.
capi32requiredThe bytes of buf from at the flight may use; under QUIC_CONN_DATAGRAM_SIZE sends nothing.
flightQuicFlightrequiredOverwritten with the flight's datagram count, segment size and ECN codepoint; all 0 when nothing was written.
returnsi32The 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
connQuicConnectionrequiredThe connection to send for.
nowi64requiredThe caller's time in milliseconds.
returnsu8[] | nullA 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).

