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
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[]required

The destination; every one of its bytes is written, so it is fully overwritten.

fromu8[]required

The source; bytes it does not have (an index before 0 or past its end) are copied as zero.

ati32required

The offset in from of the first byte to copy.

lengthi32required

How 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.