nish/net/quic-conn-cid
A QUIC connection's connection-ID table (RFC 9000 §5.1): the IDs this endpoint issued, which a datagram is routed by, and the ones the peer issued, which this endpoint sends to.
import {
QuicCidEntry,
QuicCidTable,
quicCidCopy,
} from "nish/net/quic-conn-cid";
import { QuicCidTable } from "nish/net/quic-conn-cid";
const ids = new QuicCidTable(4, 4) // the limit advertised; local slots
ids.addLocal(serverScid, []) // sequence 0, sent in the SCID, so no token
ids.addLocal(nextCid, resetToken) // sequence 1, for a NEW_CONNECTION_ID frame
ids.addPeer(0, 0, clientScid, []) // the client's first SCID, sequence 0
const dcid: u8[] = ids.currentPeer() // the ID this side sends to
const error: i64 = ids.retireLocal(sequence, packet, dcidAt, dcidLength)
// error is QUIC_ERROR_NO_ERROR, or QUIC_ERROR_PROTOCOL_VIOLATION to close with
quicCidCopy
Copies length bytes of from at at into the start of to, and zeroes the rest of to.
QuicCidEntry
One slot of the table: a connection ID and what came with it.
QuicCidTable
Both sides of one connection's IDs.
Local IDs
They are the ones this side handed out: sequence 0 is the Source
Connection ID of its first packet, and each later one goes out in a
NEW_CONNECTION_ID frame (nextUnannounced answers the next one still to). The peer
retires one with RETIRE_CONNECTION_ID: a sequence number never issued, or
the one the retiring packet was itself sent to, is a PROTOCOL_VIOLATION
(§19.16).
Peer IDs
They come from the peer's first packet and its NEW_CONNECTION_ID frames (§19.15). A sequence number seen before must carry the same ID and token, or it is a PROTOCOL_VIOLATION; an ID already given another sequence number is one too. More active IDs than the limit this side advertised is a CONNECTION_ID_LIMIT_ERROR (§5.1.1). Retire Prior To retires every older ID at once: each is queued for this side to send RETIRE_CONNECTION_ID for, and the ID this side sends to moves to the oldest still active. Queued retirements past twice the limit are a CONNECTION_ID_LIMIT_ERROR too (§5.1.2), which bounds what a peer can make this side owe it.
Fixed slots
The table is sized when it is made — limit slots for the
peer's IDs, each with room for a 20-byte ID and its token, localCapacity
for this side's, and a ring of twice the limit for owed retirements — and
every ID is copied into a slot, so nothing a peer sends allocates: a frame
reads straight from the packet through addPeerAt, ownsLocalAt and
retireLocal, and reset empties the table for a connection slot reused
for another peer. Connection IDs are compared in constant time.
Written from RFC 9000 §5.1, §19.15 and §19.16, not ported from another
implementation. Private names carry the quicCid prefix
(docs/wp26-stdlib.md §3e).
Functions
quicCidCopy
Copies length bytes of from at at into the start of to, and zeroes the rest of to.
const quicCidCopy: (
to: u8[],
from: u8[],
at: i32,
length: i32,
) => void
tou8[]requiredThe destination; every one of its bytes is written, so it is fully overwritten.
fromu8[]requiredThe source; bytes it does not have (an index before 0 or past its end) are copied as zero.
ati32requiredThe offset in from of the first byte to copy.
lengthi32requiredHow many bytes to copy; past to.length the extra bytes are dropped.
Classes
QuicCidEntry
One slot of the table: a connection ID and what came with it. cid has
room for the longest ID, and its first length bytes are this one; used
says whether the slot holds an ID at all.
class QuicCidEntry
| Member | |
|---|---|
new QuicCidEntry() |
Makes an unused slot, with room for the longest connection ID and its reset token. |
announced: boolean |
For a local ID: whether a NEW_CONNECTION_ID frame announced it yet. Sequence 0 needs none. |
length: i32 |
How many bytes of cid the ID takes, 0 to 20. |
resetToken: u8[] |
The stateless reset token issued with it (RFC 9000 §10.3); hasToken is false for a peer's sequence 0. |
sequence: i64 |
The ID's sequence number, as issued in NEW_CONNECTION_ID; 0 for the ID of the handshake. |
QuicCidTable
Both sides of one connection's IDs. limit is the
active_connection_id_limit this side advertised, which bounds the peer's.
class QuicCidTable
| Member | |
|---|---|
new QuicCidTable(limit: i64, localCapacity: i32) |
A table for an advertised limit (2 to 8 in practice) with localCapacity slots for this side's IDs. |
local: QuicCidEntry[] |
The slots for the IDs this side issued, so a caller can walk them, used or not. |
nextLocal: i64 |
The next local sequence number to issue. |
peer: QuicCidEntry[] |
The slots for the IDs the peer issued, used or not, as limit bounds them; a caller walks them to see each ID and its reset token. |
retireCount: i32 |
How many RETIRE_CONNECTION_ID frames this side still owes the peer, at most twice limit. |
activeLocal(): i32 |
How many local IDs are active: a retired one leaves its slot. |
activePeer(): i32 |
How many peer IDs are active: retired ones leave their slots. |
addLocal(cid: u8[], resetToken: u8[]): i64 |
Issues cid, up to its first 20 bytes, as the next local ID, with its 16-byte reset token (or none, empty, for sequence 0), and answers its sequence number; -1 when every local slot is taken. |
addPeer(sequence: i64, retirePriorTo: i64, cid: u8[], resetToken: u8[]): i64 |
addPeerAt of whole arrays: resetToken empty for none. |
addPeerAt(sequence: i64, retirePriorTo: i64, cid: u8[], cidAt: i32, cidLength: i32, token: u8[], tokenAt: i32, hasToken: boolean): i64 |
Takes a peer ID, cid[cidAt .. cidAt + cidLength), with the 16-byte token at token[tokenAt] when hasToken (its first packet's SCID is sequence 0, with none; a NEW_CONNECTION_ID frame's has one). Answers QUIC_ERROR_NO_ERROR, QUIC_ERROR_PROTOCOL_VIOLATION for a sequence number reused with another ID or token or an ID reused under another sequence number, or QUIC_ERROR_CONNECTION_ID_LIMIT when the active IDs or the queued retirements would pass what §5.1 allows, in which case the table is left as it was. The tokens are compared in constant time, since a token is what a stateless reset is checked against. |
currentPeer(): u8[] |
A copy of the peer ID this side sends to, or empty before the peer gave any. |
currentPeerEntry(): QuicCidEntry | null |
The peer ID this side sends to: its slot, or null before the peer gave any. |
nextUnannounced(): QuicCidEntry | null |
The first local ID still to be announced in a NEW_CONNECTION_ID frame, oldest first, or null. |
ownsLocal(dcid: u8[]): boolean |
Whether dcid is an active local ID: whether a packet sent to it is this connection's. |
ownsLocalAt(buf: u8[], at: i32, length: i32): boolean |
Whether buf[at .. at + length) is an active local ID. Each active slot of that length is compared in constant time, and the loop does not stop at a match; unused slots and slots of another length are skipped. |
prune(): void |
Makes the oldest active peer ID the current one, or none when no peer ID is active. |
queueRetire(sequence: i64): void |
Queues a RETIRE_CONNECTION_ID for peer sequence sequence, unless it is queued already or the ring is full. |
reset(): void |
Empties the table, for a connection slot reused for another peer; the slots and their bytes are kept, zeroed. |
retireLocal(sequence: i64, buf: u8[], at: i32, length: i32): i64 |
The peer retires local ID sequence (RETIRE_CONNECTION_ID), in a packet sent to buf[at .. at + length). Answers QUIC_ERROR_NO_ERROR, or QUIC_ERROR_PROTOCOL_VIOLATION for a sequence number never issued or the ID the packet itself was sent to (§19.16). Retiring one twice is fine. A retired ID leaves its slot, so a peer that retires one ID after another cannot grow the table. |
takeRetire(): i64 |
The oldest queued retirement, or -1 when none is queued. Taking it removes it. |

