@amritk/nish-x86_64-linux 0.16.0 → 0.18.0

package/std/net/quic-conn-ack.ts

@@ -0,0 +1,206 @@
+/**
+ * `nish/net/quic-conn-ack` — the packet numbers one QUIC packet number space
+ * has received, kept as ranges, which is what duplicate detection reads
+ * (RFC 9000 §12.3) and what an ACK frame is written from (§13.2, §19.3).
+ *
+ *     import { QuicAckRanges } from "nish/net/quic-conn-ack";
+ *
+ *     const received = new QuicAckRanges();
+ *     if (!received.record(packetNumber, ackEliciting)) { … a duplicate: drop it … }
+ *     if (received.ackPending) { received.pushAck(payload, 0); }
+ *
+ * **Bounded.** At most `QUIC_ACK_MAX_RANGES` ranges are kept, highest first.
+ * A new range past that drops the lowest, and everything at or below what it
+ * covered becomes the `floor`: a packet number there is answered as already
+ * seen, because this side can no longer tell, and RFC 9000 §12.3 says a
+ * receiver must discard a packet it cannot be sure it has not processed. So a
+ * peer that sends packet numbers full of holes costs a fixed amount of memory
+ * and loses only very late packets.
+ *
+ * **When to acknowledge** is the connection's choice; this module records
+ * whether something ack-eliciting arrived since the last ACK it wrote
+ * (`ackPending`). ACK frames carry an ACK Delay the caller supplies, and no
+ * ECN counts.
+ *
+ * Written from RFC 9000 §12.3, §13.2 and §19.3, not ported from another
+ * implementation. Private names carry the `quicAck` prefix
+ * (`docs/wp26-stdlib.md` §3e).
+ */
+import { QUIC_MAX_VARINT } from "nish/net/quic-packet"
+import { quicPushAck, quicPutAck } from "nish/net/quic-frame"
+
+/** The most disjoint ranges a `QuicAckRanges` keeps, and so the most an ACK frame it writes lists. */
+export const QUIC_ACK_MAX_RANGES: i32 = 32
+
+/**
+ * The packet numbers received in one space. `ranges` holds `count` pairs
+ * `[smallest, largest]`, highest first and never touching; `largest` is the
+ * largest packet number received, or -1 before the first.
+ */
+export class QuicAckRanges {
+  /** The largest packet number received, or -1. */
+  largest: i64 = -1
+  /** Every packet number at or below this is answered as already received; -1 until a range is dropped. */
+  floor: i64 = -1
+  ranges: i64[]
+  count: i32 = 0
+  /** Whether an ack-eliciting packet arrived since the last `pushAck`. */
+  ackPending: boolean = false
+
+  constructor() {
+    this.ranges = new Array<i64>(QUIC_ACK_MAX_RANGES * 2)
+  }
+
+  /** The smallest packet number of range `k`, which the caller keeps below `count`. */
+  low(k: i32): i64 {
+    const at: i32 = k * 2
+    if (at < 0 || at >= toI32(this.ranges.length)) {
+      return -1
+    }
+    return this.ranges[at]
+  }
+
+  /** The largest packet number of range `k`. */
+  high(k: i32): i64 {
+    const at: i32 = k * 2 + 1
+    if (at < 0 || at >= toI32(this.ranges.length)) {
+      return -1
+    }
+    return this.ranges[at]
+  }
+
+  /** Sets range `k` to `[low, high]`. */
+  set(k: i32, low: i64, high: i64): void {
+    const at: i32 = k * 2
+    const next: i32 = at + 1
+    if (at < 0 || at >= toI32(this.ranges.length) || next < 0 || next >= toI32(this.ranges.length)) {
+      return
+    }
+    this.ranges[at] = low
+    this.ranges[next] = high
+  }
+
+  /** Whether `pn` was received, or is at or below the floor and so cannot be told apart from one that was. */
+  contains(pn: i64): boolean {
+    if (pn <= this.floor) {
+      return true
+    }
+    for (let k: i32 = 0; k < this.count; k += 1) {
+      if (pn > this.high(k)) {
+        return false
+      }
+      if (pn >= this.low(k)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  /**
+   * Records `pn` as received, `ackEliciting` saying whether its frames ask for
+   * an acknowledgement. Answers `false`, changing nothing, for a packet number
+   * already received (or at or below the floor), or one that is not a packet
+   * number at all.
+   */
+  record(pn: i64, ackEliciting: boolean): boolean {
+    if (pn < 0 || pn > QUIC_MAX_VARINT || this.contains(pn)) {
+      return false
+    }
+    if (pn > this.largest) {
+      this.largest = pn
+    }
+    if (ackEliciting) {
+      this.ackPending = true
+    }
+    // Find the first range whose largest is below `pn`: `pn` goes above it.
+    let k: i32 = 0
+    while (k < this.count && this.low(k) > pn) {
+      k += 1
+    }
+    const joinsAbove: boolean = k > 0 && this.low(k - 1) === pn + 1
+    const joinsBelow: boolean = k < this.count && this.high(k) === pn - 1
+    if (joinsAbove && joinsBelow) {
+      // `pn` closes the hole between two ranges: merge them into the upper one.
+      this.set(k - 1, this.low(k), this.high(k - 1))
+      this.remove(k)
+      return true
+    }
+    if (joinsAbove) {
+      this.set(k - 1, pn, this.high(k - 1))
+      return true
+    }
+    if (joinsBelow) {
+      this.set(k, this.low(k), pn)
+      return true
+    }
+    this.insert(k, pn)
+    return true
+  }
+
+  /** Removes range `k`, moving the lower ones up. */
+  remove(k: i32): void {
+    for (let j: i32 = k; j + 1 < this.count; j += 1) {
+      this.set(j, this.low(j + 1), this.high(j + 1))
+    }
+    this.count = this.count - 1
+  }
+
+  /**
+   * Inserts the one-number range `[pn, pn]` at position `k`. When every slot
+   * is taken the lowest range is dropped first and the floor raised over it;
+   * if `pn` itself would be that lowest range, it is the one dropped.
+   */
+  insert(k: i32, pn: i64): void {
+    if (this.count === QUIC_ACK_MAX_RANGES) {
+      if (k === this.count) {
+        this.floor = pn
+        return
+      }
+      this.floor = this.high(this.count - 1)
+      this.count = this.count - 1
+    }
+    for (let j: i32 = this.count; j > k; j -= 1) {
+      this.set(j, this.low(j - 1), this.high(j - 1))
+    }
+    this.set(k, pn, pn)
+    this.count = this.count + 1
+  }
+
+  /**
+   * Appends an ACK frame for every range kept, with `ackDelay` (already
+   * scaled by this endpoint's ACK delay exponent), and clears `ackPending`.
+   * Answers `false`, appending nothing, when nothing has been received.
+   */
+  pushAck(out: u8[], ackDelay: i64): boolean {
+    if (this.count === 0 || !quicPushAck(out, this.ranges, this.count, ackDelay)) {
+      return false
+    }
+    this.ackPending = false
+    return true
+  }
+
+  /**
+   * Writes the ACK frame `pushAck` appends into `buf` at `at`, before `end`,
+   * and clears `ackPending`. Answers the offset past it, or -1, writing
+   * nothing and leaving `ackPending` as it was, when nothing has been
+   * received or the frame does not fit.
+   */
+  putAck(buf: u8[], at: i32, end: i32, ackDelay: i64): i32 {
+    if (this.count === 0) {
+      return -1
+    }
+    const next: i32 = quicPutAck(buf, at, end, this.ranges, this.count, ackDelay)
+    if (next >= 0) {
+      this.ackPending = false
+    }
+    return next
+  }
+
+  /** Forgets every packet number, for a connection slot reused for another peer. */
+  clear(): void {
+    this.largest = -1
+    this.floor = -1
+    this.count = 0
+    this.ackPending = false
+  }
+}

package/std/net/quic-conn-cid.ts

@@ -0,0 +1,425 @@
+/**
+ * `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 { QuicCidTable } from "nish/net/quic-conn-cid";
+ *
+ *     const ids = new QuicCidTable(4, 4);         // the active_connection_id_limit advertised; local slots
+ *     ids.addLocal(serverScid, token);             // sequence 0
+ *     ids.addPeer(0, 0, clientScid, none);         // the client's first SCID, sequence 0
+ *     const error: i64 = ids.retireLocal(frame.value, packetDcid);
+ *
+ * **Local IDs** 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** 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 in `retirePending`, for this side to send
+ * RETIRE_CONNECTION_ID for, and `current` 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).
+ */
+import { timingSafeEqualAt } from "nish/crypto/ct"
+import {
+  QUIC_ERROR_CONNECTION_ID_LIMIT,
+  QUIC_ERROR_NO_ERROR,
+  QUIC_ERROR_PROTOCOL_VIOLATION,
+  QUIC_RESET_TOKEN_SIZE,
+} from "nish/net/quic-frame"
+import { QUIC_MAX_CID_LENGTH } from "nish/net/quic-packet"
+
+/** A typed zero: a bare literal is an `f64` under `--number-mode f64`. */
+const QUIC_CID_ZERO: i32 = 0
+
+/**
+ * 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.
+ */
+export class QuicCidEntry {
+  sequence: i64 = 0
+  cid: u8[]
+  /** The stateless reset token issued with it (RFC 9000 §10.3); `hasToken` is false for a peer's sequence 0. */
+  resetToken: u8[]
+  length: i32 = 0
+  used: boolean = false
+  hasToken: boolean = false
+  /** For a local ID: whether a NEW_CONNECTION_ID frame announced it yet. Sequence 0 needs none. */
+  announced: boolean = false
+
+  constructor() {
+    this.cid = new Array<u8>(QUIC_MAX_CID_LENGTH)
+    this.resetToken = new Array<u8>(QUIC_RESET_TOKEN_SIZE)
+  }
+}
+
+/** Copies `length` bytes of `from` at `at` into the start of `to`, and zeroes the rest of `to`. */
+export const quicCidCopy = (to: u8[], from: u8[], at: i32, length: i32): void => {
+  for (let k: i32 = 0; k < toI32(to.length); k += 1) {
+    to[k] = k < length && at + k >= 0 && at + k < toI32(from.length) ? from[at + k] : toU8(0)
+  }
+}
+
+/** The index of the used entry with the smallest sequence number above `after`, only unannounced ones when `unannounced`, or -1. */
+const quicCidOldest = (entries: QuicCidEntry[], after: i64, unannounced: boolean): i32 => {
+  let best: i32 = -1
+  let bestSequence: i64 = -1
+  for (let k: i32 = 0; k < toI32(entries.length); k += 1) {
+    const entry: QuicCidEntry = entries[k]
+    if (
+      entry.used &&
+      entry.sequence > after &&
+      (!unannounced || !entry.announced) &&
+      (bestSequence < 0 || entry.sequence < bestSequence)
+    ) {
+      best = k
+      bestSequence = entry.sequence
+    }
+  }
+  return best
+}
+
+/** The index of the first unused entry, or -1 when every one is taken. */
+const quicCidFree = (entries: QuicCidEntry[]): i32 => {
+  for (let k: i32 = 0; k < toI32(entries.length); k += 1) {
+    if (!entries[k].used) {
+      return k
+    }
+  }
+  return -1
+}
+
+/** Empties one slot: its sequence and flags reset and its bytes zeroed, the token among them. */
+const quicCidClear = (entry: QuicCidEntry): void => {
+  entry.used = false
+  entry.hasToken = false
+  entry.announced = false
+  entry.sequence = 0
+  entry.length = 0
+  secureZero(entry.cid)
+  secureZero(entry.resetToken)
+}
+
+/** `count` empty slots. */
+const quicCidSlots = (count: i32): QuicCidEntry[] => {
+  const out: QuicCidEntry[] = []
+  for (let k: i32 = 0; k < count; k += 1) {
+    out.push(new QuicCidEntry())
+  }
+  return out
+}
+
+/**
+ * Both sides of one connection's IDs. `limit` is the
+ * `active_connection_id_limit` this side advertised, which bounds the peer's.
+ */
+export class QuicCidTable {
+  local: QuicCidEntry[]
+  peer: QuicCidEntry[]
+  /** Peer sequence numbers this side must send RETIRE_CONNECTION_ID for, oldest first, as a ring of `retireCount` from `retireHead`. */
+  retirePending: i64[]
+  /** The next local sequence number to issue. */
+  nextLocal: i64 = 0
+  /** The peer's highest Retire Prior To so far. */
+  peerRetirePriorTo: i64 = 0
+  limit: i64 = 2
+  /** The index in `peer` of the ID this side sends to, or -1 before the peer gave one. */
+  current: i32 = -1
+  retireHead: i32 = 0
+  retireCount: i32 = 0
+
+  /** A table for an advertised `limit` (2 to 8 in practice) with `localCapacity` slots for this side's IDs. */
+  constructor(limit: i64, localCapacity: i32) {
+    const peerSlots: i32 = limit < 1 ? 1 : toI32(limit)
+    this.local = quicCidSlots(localCapacity)
+    this.peer = quicCidSlots(peerSlots)
+    this.retirePending = new Array<i64>(peerSlots * 2)
+    this.limit = limit
+  }
+
+  /** Empties the table, for a connection slot reused for another peer; the slots and their bytes are kept, zeroed. */
+  reset(): void {
+    for (const entry of this.local) {
+      quicCidClear(entry)
+    }
+    for (const entry of this.peer) {
+      quicCidClear(entry)
+    }
+    this.nextLocal = 0
+    this.peerRetirePriorTo = 0
+    this.current = -1
+    this.retireHead = 0
+    this.retireCount = 0
+  }
+
+  /**
+   * Issues the first `length` bytes of `cid` 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.
+   */
+  addLocal(cid: u8[], resetToken: u8[]): i64 {
+    const k: i32 = quicCidFree(this.local)
+    if (k < 0) {
+      return -1
+    }
+    const entry: QuicCidEntry = this.local[k]
+    const sequence: i64 = this.nextLocal
+    const length: i32 = toI32(cid.length) > QUIC_MAX_CID_LENGTH ? QUIC_MAX_CID_LENGTH : toI32(cid.length)
+    quicCidCopy(entry.cid, cid, 0, length)
+    entry.length = length
+    entry.hasToken = toI32(resetToken.length) === QUIC_RESET_TOKEN_SIZE
+    quicCidCopy(entry.resetToken, resetToken, 0, entry.hasToken ? QUIC_RESET_TOKEN_SIZE : 0)
+    entry.sequence = sequence
+    entry.used = true
+    // Sequence 0 travels in the long header's SCID, never in a frame.
+    entry.announced = sequence === 0
+    this.nextLocal = sequence + 1
+    return sequence
+  }
+
+  /** How many local IDs are active: a retired one leaves its slot. */
+  activeLocal(): i32 {
+    let n: i32 = 0
+    for (const entry of this.local) {
+      if (entry.used) {
+        n += 1
+      }
+    }
+    return n
+  }
+
+  /** Whether `dcid` is an active local ID: whether a packet sent to it is this connection's. */
+  ownsLocal(dcid: u8[]): boolean {
+    return this.ownsLocalAt(dcid, QUIC_CID_ZERO, toI32(dcid.length))
+  }
+
+  /** Whether `buf[at .. at + length)` is an active local ID. Every slot is compared, each in constant time. */
+  ownsLocalAt(buf: u8[], at: i32, length: i32): boolean {
+    let owned: boolean = false
+    for (const entry of this.local) {
+      if (entry.used && entry.length === length && timingSafeEqualAt(entry.cid, 0, buf, at, length)) {
+        owned = true
+      }
+    }
+    return owned
+  }
+
+  /**
+   * 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.
+   */
+  retireLocal(sequence: i64, buf: u8[], at: i32, length: i32): i64 {
+    if (sequence < 0 || sequence >= this.nextLocal) {
+      return QUIC_ERROR_PROTOCOL_VIOLATION
+    }
+    for (const entry of this.local) {
+      if (entry.used && entry.sequence === sequence) {
+        if (entry.length === length && timingSafeEqualAt(entry.cid, 0, buf, at, length)) {
+          return QUIC_ERROR_PROTOCOL_VIOLATION
+        }
+        quicCidClear(entry)
+      }
+    }
+    return QUIC_ERROR_NO_ERROR
+  }
+
+  /** How many peer IDs are active: retired ones leave their slots. */
+  activePeer(): i32 {
+    let n: i32 = 0
+    for (const entry of this.peer) {
+      if (entry.used) {
+        n += 1
+      }
+    }
+    return n
+  }
+
+  /** `addPeerAt` of whole arrays: `resetToken` empty for none. */
+  addPeer(sequence: i64, retirePriorTo: i64, cid: u8[], resetToken: u8[]): i64 {
+    return this.addPeerAt(
+      sequence,
+      retirePriorTo,
+      cid,
+      QUIC_CID_ZERO,
+      toI32(cid.length),
+      resetToken,
+      QUIC_CID_ZERO,
+      toI32(resetToken.length) === QUIC_RESET_TOKEN_SIZE
+    )
+  }
+
+  /**
+   * 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.
+   */
+  addPeerAt(
+    sequence: i64,
+    retirePriorTo: i64,
+    cid: u8[],
+    cidAt: i32,
+    cidLength: i32,
+    token: u8[],
+    tokenAt: i32,
+    hasToken: boolean
+  ): i64 {
+    if (cidLength < 0 || cidLength > QUIC_MAX_CID_LENGTH) {
+      return QUIC_ERROR_PROTOCOL_VIOLATION
+    }
+    for (const entry of this.peer) {
+      if (!entry.used) {
+        continue
+      }
+      const sameId: boolean =
+        entry.length === cidLength && timingSafeEqualAt(entry.cid, 0, cid, cidAt, cidLength)
+      if (entry.sequence === sequence) {
+        const sameToken: boolean =
+          entry.hasToken === hasToken &&
+          (!hasToken || timingSafeEqualAt(entry.resetToken, 0, token, tokenAt, QUIC_RESET_TOKEN_SIZE))
+        return sameId && sameToken ? QUIC_ERROR_NO_ERROR : QUIC_ERROR_PROTOCOL_VIOLATION
+      }
+      if (sameId) {
+        return QUIC_ERROR_PROTOCOL_VIOLATION
+      }
+    }
+    // Count what the frame would leave before changing anything, so a frame
+    // refused for a limit leaves the table as it was.
+    const priorTo: i64 = retirePriorTo > this.peerRetirePriorTo ? retirePriorTo : this.peerRetirePriorTo
+    let active: i64 = sequence < priorTo ? 0 : 1
+    let pending: i64 = toI64(this.retireCount) + (sequence < priorTo ? 1 : 0)
+    for (const old of this.peer) {
+      if (!old.used) {
+        continue
+      }
+      if (old.sequence < priorTo) {
+        pending += 1
+      } else {
+        active += 1
+      }
+    }
+    if (
+      active > this.limit ||
+      pending > this.limit * 2 ||
+      pending > toI64(toI32(this.retirePending.length))
+    ) {
+      return QUIC_ERROR_CONNECTION_ID_LIMIT
+    }
+    this.peerRetirePriorTo = priorTo
+    // §19.15: every ID below Retire Prior To is retired, oldest first, and
+    // one that arrives already below it is retired as it arrives.
+    let k: i32 = quicCidOldest(this.peer, -1, false)
+    while (k >= 0 && k < toI32(this.peer.length) && this.peer[k].sequence < priorTo) {
+      const old: QuicCidEntry = this.peer[k]
+      this.queueRetire(old.sequence)
+      const after: i64 = old.sequence
+      quicCidClear(old)
+      k = quicCidOldest(this.peer, after, false)
+    }
+    if (sequence < priorTo) {
+      this.queueRetire(sequence)
+    } else {
+      const free: i32 = quicCidFree(this.peer)
+      if (free >= 0 && free < toI32(this.peer.length)) {
+        const entry: QuicCidEntry = this.peer[free]
+        quicCidCopy(entry.cid, cid, cidAt, cidLength)
+        entry.length = cidLength
+        entry.hasToken = hasToken
+        quicCidCopy(entry.resetToken, token, tokenAt, hasToken ? QUIC_RESET_TOKEN_SIZE : 0)
+        entry.sequence = sequence
+        entry.used = true
+      }
+    }
+    this.prune()
+    return QUIC_ERROR_NO_ERROR
+  }
+
+  /** Points `current` at the oldest active peer ID, or -1 when none is. */
+  prune(): void {
+    this.current = quicCidOldest(this.peer, -1, false)
+  }
+
+  /** The peer ID this side sends to: its slot, or `null` before the peer gave any. */
+  currentPeerEntry(): QuicCidEntry | null {
+    const at: i32 = this.current
+    return at >= 0 && at < toI32(this.peer.length) ? this.peer[at] : null
+  }
+
+  /** A copy of the peer ID this side sends to, or empty before the peer gave any. */
+  currentPeer(): u8[] {
+    const entry: QuicCidEntry | null = this.currentPeerEntry()
+    const length: i32 = entry !== null ? entry.length : 0
+    const out: u8[] = new Array<u8>(length)
+    if (entry !== null) {
+      quicCidCopy(out, entry.cid, 0, length)
+    }
+    return out
+  }
+
+  /** Queues a RETIRE_CONNECTION_ID for peer sequence `sequence`, unless it is queued already or the ring is full. */
+  queueRetire(sequence: i64): void {
+    const size: i32 = toI32(this.retirePending.length)
+    for (let k: i32 = 0; k < this.retireCount; k += 1) {
+      const at: i32 = (this.retireHead + k) % size
+      if (at >= 0 && at < size && this.retirePending[at] === sequence) {
+        return
+      }
+    }
+    if (this.retireCount >= size || size === 0) {
+      return
+    }
+    const at: i32 = (this.retireHead + this.retireCount) % size
+    if (at >= 0 && at < size) {
+      this.retirePending[at] = sequence
+      this.retireCount = this.retireCount + 1
+    }
+  }
+
+  /** The oldest queued retirement, or -1 when none is queued. Taking it removes it. */
+  takeRetire(): i64 {
+    const size: i32 = toI32(this.retirePending.length)
+    if (this.retireCount === 0 || size === 0) {
+      return -1
+    }
+    const at: i32 = this.retireHead
+    const first: i64 = at >= 0 && at < size ? this.retirePending[at] : -1
+    this.retireHead = (at + 1) % size
+    this.retireCount = this.retireCount - 1
+    return first
+  }
+
+  /** The first local ID still to be announced in a NEW_CONNECTION_ID frame, oldest first, or `null`. */
+  nextUnannounced(): QuicCidEntry | null {
+    const k: i32 = quicCidOldest(this.local, -1, true)
+    return k >= 0 && k < toI32(this.local.length) ? this.local[k] : null
+  }
+}