nish/net/quic-datagram

A fixed ring of QUIC DATAGRAM payloads (RFC 9221), one each way per connection: what the application queued to send, waiting for room in a packet and in the congestion window, and what the peer sent, waiting for the application to read it. Sans-IO, like the rest of nish/net; nish/net/quic's QuicConnection owns both rings and the application reaches them through its sendDatagram and readDatagram.

import {
  QuicDatagramQueue,
} from "nish/net/quic-datagram";
import { QuicDatagramQueue } from "nish/net/quic-datagram";

const outgoing: QuicDatagramQueue = new QuicDatagramQueue(16, 1200);  // 16 payloads, each 1200 bytes at most
if (!outgoing.push(message, 0, toI32(message.length))) { … full or too big: dropped … }
at = outgoing.putFrame(packet, at, packetEnd);                         // `at` again when nothing fit

const incoming: QuicDatagramQueue = new QuicDatagramQueue(16, 1200);
const length: i32 = incoming.pop(into, 0, toI32(into.length));         // -1 empty, -2 `into` too small
Fixed

A ring is entries payloads of at most entrySize bytes, allocated once; a payload is copied in and out, and nothing allocates after the ring is made. A datagram is unreliable by definition (RFC 9221 §5), so a full ring refuses the next rather than growing, and what the peer sends past a full receive ring, or past entrySize, is dropped and counted in dropped.

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

Classes

QuicDatagramQueue

A ring of entries datagram payloads of at most entrySize bytes each, oldest first.

class QuicDatagramQueue
Member
new QuicDatagramQueue(entries: i32, entrySize: i32) Makes an empty ring, allocating all of its storage now: entries * entrySize bytes of payload and a 4-byte length per entry.
count: i32 How many datagrams wait in the ring, from 0 to its entry count.
data: u8[] Entry k's bytes are data[k * entrySize ..], lengths[k] of them.
dropped: i32 Datagrams refused for want of room or for their size, which the peer's side counts as dropped.
entrySize: i32 The largest payload an entry holds, in bytes, fixed when the ring is made; it is also the stride of data. A longer datagram is refused and counted in dropped.
head: i32 The index of the oldest entry; the j-th oldest is entry (head + j) % capacity().
lengths: i32[] Each entry's payload length in bytes, 0 to entrySize; entry k's is lengths[k].
capacity(): i32 How many datagrams the ring holds at most.
deferOldest(): void Moves the oldest datagram behind the newest, unsent and not counted as dropped, so the ones queued after it go out first; for one too large for now that a later packet may carry. A ring of one is left as it is.
dropOldest(): void Forgets the oldest datagram unsent and counts it in dropped, for one that no packet can carry any more; an empty ring is left as it is.
peekLength(): i32 The oldest datagram's length, or -1 when the ring is empty.
pop(buf: u8[], at: i32, cap: i32): i32 Copies the oldest datagram into buf at at and forgets it. Answers its length, -1 when the ring is empty, or -2, keeping it, when it does not fit in cap bytes from at inside buf.
push(buf: u8[], from: i32, length: i32): boolean Copies buf[from .. from + length) in as the newest datagram. Answers whether it could: not when the ring is full, nor for a payload past entrySize or a window outside buf, each of which counts in dropped.
putFrame(buf: u8[], at: i32, end: i32): i32 Writes the oldest datagram as a DATAGRAM frame into buf[at .. end) and forgets it. Answers the offset past the frame, or at when the ring is empty or the frame does not fit, keeping it for the next packet.
reset(): void Empties the ring, for a connection slot reused for another peer.