nish/net/quic-stream

The streams of one QUIC version 1 connection (RFC 9000 §2-§4): stream IDs and their four types, the sending and receiving state machines, reassembly, flow control per stream and for the connection, and the stream limits. Sans-IO, like the rest of nish/net: nish/net/quic's QuicConnection hands it every stream frame it reads, asks it for the frames to send, and reports which of them a packet that was acknowledged or lost carried. An application reaches it through the connection's stream calls (openStream, streamWrite, streamRead, nextStreamEvent and the rest), not directly.

import {
  QUIC_RECV_DATA_READ,
  QUIC_RECV_DATA_RECVD,
  QUIC_RECV_NONE,
  QUIC_RECV_RECV,
  QUIC_RECV_RESET_READ,
  QUIC_RECV_RESET_RECVD,
  QUIC_RECV_SIZE_KNOWN,
  QUIC_SEND_DATA_RECVD,
  QUIC_SEND_DATA_SENT,
  QUIC_SEND_NONE,
  QUIC_SEND_READY,
  QUIC_SEND_RESET_RECVD,
  QUIC_SEND_RESET_SENT,
  QUIC_SEND_SEND,
  QUIC_STREAM_CONTROL_DATA_BLOCKED,
  QUIC_STREAM_CONTROL_MAX_DATA,
  QUIC_STREAM_CONTROL_MAX_STREAMS_BIDI,
  QUIC_STREAM_CONTROL_MAX_STREAMS_UNI,
  QUIC_STREAM_CONTROL_MAX_STREAM_DATA,
  QUIC_STREAM_CONTROL_RESET,
  QUIC_STREAM_CONTROL_STOP_SENDING,
  QUIC_STREAM_CONTROL_STREAMS_BLOCKED_BIDI,
  QUIC_STREAM_CONTROL_STREAMS_BLOCKED_UNI,
  QUIC_STREAM_CONTROL_STREAM_DATA_BLOCKED,
  QUIC_STREAM_END,
  QUIC_STREAM_ERR_DIRECTION,
  QUIC_STREAM_ERR_FINISHED,
  QUIC_STREAM_ERR_FLOW,
  QUIC_STREAM_ERR_LIMIT,
  QUIC_STREAM_ERR_RESET,
  QUIC_STREAM_ERR_STATE,
  QUIC_STREAM_ERR_STOPPED,
  QUIC_STREAM_ERR_UNKNOWN,
  QUIC_STREAM_OK,
  QuicStream,
  QuicStreamPools,
  QuicStreams,
  quicStreamBit,
  quicStreamGrowFree,
  quicStreamIsLocal,
  quicStreamIsUni,
  quicStreamSetBit,
} from "nish/net/quic-stream";
const pools = new QuicStreamPools(65536, 111, 64)         // 64 connections of 100 + 3 + 8 slots
const streams = new QuicStreams(100, 3, 8, 65536, 1048576) // client bidi, client uni, own; bytes
streams.share(pools)                                       // before any stream has borrowed
streams.setPeerLimits(maxData, bidiLocal, bidiRemote, uni, maxStreamsBidi, maxStreamsUni)
streams.prime(packetLength)                                // per packet, before its frames: fills the reserve
const error: i64 = streams.onStream(frame.streamId, frame.offset, payload, frame.dataStart,
  frame.dataLength, frame.fin)                             // 0, or the transport error to close with
const id: i64 = frame.streamId                             // the stream the frame was for
const got: i32 = streams.read(id, into, 0, 4096)           // bytes, 0, QUIC_STREAM_END or an error
const taken: i32 = streams.write(id, reply, 0, toI32(reply.length), true)
streams.beginPacket()
const next: i32 = streams.putNextChunk(out, at, end)       // `at` when no frame fits

IDs (§2.1). The low bit says who opened a stream (0 the client, 1 the server) and the next one whether it carries data both ways (0) or only from its opener (1).

This side is a server: it opens IDs 1 and 3 modulo 4, and the client 0 and 2. A frame for a stream of the client's that is past the limit this side advertised is STREAM_LIMIT_ERROR; for one of the server's that it has not opened, STREAM_STATE_ERROR; and a frame that only makes sense on a side the stream does not have (STREAM, RESET_STREAM or STREAM_DATA_BLOCKED on the server's unidirectional stream; MAX_STREAM_DATA or STOP_SENDING on the client's) is STREAM_STATE_ERROR (§19.4-§19.13). A client's stream opens every lower one of its type with it (§3.2).

Fixed slots

The table is sized once, from the configuration: one slot per stream that may be open at once — as many client-opened bidirectional and unidirectional streams as this side lets the client have, and localStreams of its own. A stream lives in its slot from the frame (or open) that starts it until both of its sides are done, and then the slot is free for the next. A stream is found by its ID through a hash index, never by a scan.

Lent buffers

A slot holds no buffers of its own. A side borrows a bufferSize-byte buffer, and a bit per byte beside it, from the table's QuicStreamPools when it first needs one: the receive side on the first byte that lands, the send side on the first byte written.

Each goes back, its used extent zeroed, once it is done with: the receive side once the application has read to the final size or the stream is reset, the send side once every byte up to the final size is acknowledged or the stream is reset, never before, since a lost byte is resent from the send buffer.

The pools hold two buffers per slot at most, the reserve's included, so a borrow never fails, and a server shares one pool across all its connections (share), so what it holds follows the streams moving bytes, not the slots it was sized for. Once the pools are warm, nothing a peer sends and nothing the application writes allocates.

Receiving

Receiving (§3.2, §2.2). Data lands in the receive buffer at its offset modulo the buffer's size, in any order and overlapping, with a bit set per byte; what continues the stream from the last byte read is what read hands out. The credit this side gives a stream (MAX_STREAM_DATA) is never more than what the buffer can hold past the last byte read, so a byte beyond it is FLOW_CONTROL_ERROR and the buffer cannot overflow; it is raised by a whole buffer once the application has read half of one.

The connection's credit (MAX_DATA) is raised the same way, by windowData once half of it is read. A FIN or RESET_STREAM fixes the final size, and a frame that disagrees with it, or a size below what already arrived, is FINAL_SIZE_ERROR (§4.5). A reset stream's bytes count as read for the connection's credit.

Sending

Sending (§3.1). The application writes into the send buffer as far as it has room, a chunk at a time: what write takes is its back-pressure, and the stream's event fires again once acknowledgements free room. Bytes stay in the buffer until acknowledged: the acknowledged bits move the buffer's start, and a range a lost packet carried is sent again from it. New bytes go out only within both the stream's credit and the connection's; at either limit the stream owes STREAM_DATA_BLOCKED or the connection DATA_BLOCKED, once per limit. A STOP_SENDING from the peer is answered with RESET_STREAM (§3.5), and RESET_STREAM from the application gives up what was not sent; either is sent until acknowledged.

Limits (§4.6). The client may open as many streams of each type as the configuration allows at once; MAX_STREAMS raises its limit as its streams finish, once half of the configured number have. The server opens streams within the client's limits and its own localStreams; past the client's limit it owes STREAMS_BLOCKED.

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

Functions

quicStreamBit

Whether bit k of bits is set; false outside the array.

const quicStreamBit: (bits: u8[], k: i32) => boolean
bitsu8[]required

A bitmap, bit k in byte k >> 3 at bit k & 7.

ki32required

The bit's index, from 0.

returnsboolean

True when the bit is set; false when it is clear or k is outside the array.

quicStreamGrowFree

Pushes none onto free until it is target long, then pops each one off again: the capacity stays, so giving back that many buffers to the pool the list belongs to never grows the arena.

const quicStreamGrowFree: (
  free: u8[][],
  target: i32,
  none: u8[],
) => void
freeu8[][]required

A pool's free list; its length is unchanged on return.

targeti32required

The capacity, in entries, the list is grown to. No larger than its length does nothing.

noneu8[]required

The placeholder pushed and popped, the table's empty array.

quicStreamIsLocal

Whether id is a stream this side, the server, opens: its low bit is 1.

const quicStreamIsLocal: (id: i64) => boolean
idi64required

A stream ID (§2.1).

returnsboolean

True for a server-opened stream, false for a client-opened one.

quicStreamIsUni

Whether id is a unidirectional stream: its second bit is 1.

const quicStreamIsUni: (id: i64) => boolean
idi64required

A stream ID (§2.1).

returnsboolean

True when only the opener sends on it, false for a bidirectional stream.

quicStreamSetBit

Sets or clears bit k of bits.

const quicStreamSetBit: (
  bits: u8[],
  k: i32,
  on: boolean,
) => void
bitsu8[]required

A bitmap, bit k in byte k >> 3 at bit k & 7; changed in place.

ki32required

The bit's index, from 0. An index outside the array changes nothing.

onbooleanrequired

True to set the bit, false to clear it.

Classes

QuicStream

One stream slot. id is -1 while the slot is free. The fields are readable — the states, resetCode once the peer reset it, stopCode once it asked this side to stop — and written only by QuicStreams.

class QuicStream
Member
new QuicStream(bufferSize: i32, none: u8[]) A slot for buffers of bufferSize bytes, holding none: each side starts as none, the table's empty array.
id: i64 The stream ID (RFC 9000 §2.1), or -1 while the slot is free.
recvBuf: u8[] The receive buffer: byte o of the stream at o % size, its bit in recvHave set while unread. Both are the table's empty array until the first byte arrives and after the side is done, and borrowed in between.
recvContiguous: i64 Every byte below this has arrived.
recvFinal: i64 The final size once a FIN or RESET_STREAM fixed it, or -1.
recvHave: u8[] The bitmap beside recvBuf: a bit per buffer byte, set while that byte has arrived and is unread.
recvHighest: i64 The highest offset any frame reached, which flow control counts.
recvLimit: i64 The credit this side gave: no byte at or past this offset may arrive.
recvState: i32 The receive side's state (RFC 9000 §3.2), a QUIC_RECV_* constant.
resendHigh: i64 One past the last byte to send again, or -1 when nothing is owed; see resendLow.
resendLow: i64 Bytes a lost packet carried, [resendLow, resendHigh), or -1; resendFin when the FIN was among them.
resetCode: i64 The peer's RESET_STREAM error code, or -1.
sendAcked: u8[] The bitmap beside sendBuf: a bit per buffer byte, set once acknowledged and not yet released.
sendBase: i64 Every byte below this was acknowledged, and its room released.
sendBuf: u8[] The send buffer: byte o at o % size, its bit in sendAcked set once acknowledged and not yet released. Borrowed by the first write, and kept until every byte is acknowledged or the side is reset, since a lost packet is sent again from it.
sendEnd: i64 One past the last byte written.
sendNext: i64 The next byte never sent: the stream's credit and the connection's count up to here.
sendState: i32 The send side's state (RFC 9000 §3.1), a QUIC_SEND_* constant.
stopCode: i64 The peer's STOP_SENDING error code, or -1.
at(offset: i64): i32 The buffer index of stream offset offset.
room(): i64 How many more bytes the send buffer takes. The buffer is the stream's maxStreamData and is the memory bound of its send side: bytes stay in it until the peer acknowledges them, so one lost packet holds back everything written after it until its resend is acknowledged (quic.ts probes early meanwhile, so a peer whose address changes is still seen).

QuicStreamPools

The buffers a connection's streams borrow: data lends the receive and send buffers of bufferSize bytes, bits the bitmaps beside them, a bit per byte. One table makes a private set for itself; a server makes one set for every slot and hands it to each connection's table with QuicStreams.share, so the memory follows the streams moving bytes rather than the slots the server was sized for. Each pool's ceiling is two buffers for every stream it serves, one a side, which is what holding every buffer at once costs.

The reserve below counts against it too, so a send side that finds the pools out takes the reserve's last buffer (lendSend): with that side holding none, not every buffer is lent, and the one left over is in the reserve.

Frames are handled inside the arena scope a packet is opened in, where nothing may allocate, grow a list or push onto one. So the frames lend and take back receive buffers through a reserve the pools keep beside their free lists, by index alone: lend hands one out, keep takes one back zeroed. Before each scope prime trims the reserve to hold buffers, giving the rest to the pools, and tops it up to as many as the packet could start receive sides, taking them.

hold is one connection's stream count, and the reserve three times that long, so a packet that lends nothing and takes back every buffer its connection held still fits. Once warm, the reserve mostly circulates on its own and prime costs a handful of comparisons, with no take or give. The pools count the reserve's buffers as lent. prime and the drain before each give-back outside a packet trim it to hold for the whole server, not each connection, but keep inside a packet can raise it to three times hold, and it stays there until the next prime or drain.

class QuicStreamPools
Member
new QuicStreamPools(bufferSize: i32, streams: i32, connections: i32) Pools for connections connections of streams stream slots each, bufferSize bytes each way.
bits: BufferPool The pool of bitmaps beside them, a bit per buffer byte: which bytes are unread or acknowledged.
data: BufferPool The pool of stream buffers, bufferSize bytes each, that the send and receive sides borrow.
ready: i32 How many buffers the reserve holds.
readyBits: u8[][] The reserve's bitmaps, one beside each readyData buffer at the same index.
readyData: u8[][] The reserve: ready buffers and their bitmaps, taken from the pools and not lent to a stream; the rest of each list is none.
lent(): i32 How many buffers and bitmaps are lent to streams now, the reserve's left out: 0 once every stream that borrowed has given back.

QuicStreams

The streams of one connection: their slots, the index by ID, the limits both ways, the connection's flow control both ways, and the ring of streams with something new for the application (nextEvent). The counters are readable for a test or a log.

class QuicStreams
Member
new QuicStreams(maxBidi: i64, maxUni: i64, localStreams: i64, bufferSize: i32, windowData: i64) The table for a connection that lets the client open maxBidi bidirectional and maxUni unidirectional streams at once and opens localStreams of its own, each stream with bufferSize bytes each way, and a connection receive window of windowData bytes.
bufferSize: i32 The bytes of each stream's buffer, each way.
freeCount: i32 How many slots free holds.
lastFin: boolean Whether the last putNextChunk carried the FIN, for the packet's record.
lastId: i64 What the last putNextChunk or putNextControl wrote, for the packet's record.
lastKind: i32 Which control frame putNextControl last wrote, a QUIC_STREAM_CONTROL_* constant.
lastLength: i32 The bytes of the last chunk putNextChunk wrote.
lastOffset: i64 The stream offset of the last chunk putNextChunk wrote.
lastValue: i64 The stream the last control frame putNextControl wrote names, or 0 for a connection-level one.
peerBidiClosed: i64 How many of the client's bidirectional streams finished, which is what lets the limit rise.
peerBidiLimit: i64 The bidirectional stream limit this side last advertised to the client (MAX_STREAMS).
peerBidiOpened: i64 How many of each type the client opened, the limit advertised, and how many of them finished.
peerUniClosed: i64 How many of the client's unidirectional streams finished, which is what lets the limit rise.
peerUniLimit: i64 The unidirectional stream limit this side last advertised to the client (MAX_STREAMS).
peerUniOpened: i64 How many unidirectional streams the client opened.
pools: QuicStreamPools | null Where the streams borrow their buffers: the table's own pools, or the set a server shares across its connections (share). null when the streams have no buffers at all (bufferSize 0, or no slots).
recvMaxData: i64 The connection's receive credit: what was advertised, its window, what arrived, and what was read.
recvTotal: i64 Bytes the connection received, counted at each stream's highest offset, against recvMaxData.
sendMaxData: i64 The connection's send credit from the peer, what was sent against it, and what is written but not sent.
slots: QuicStream[] The stream slots, a fixed count set at construction; a free one has id -1.
windowData: i64 The connection's receive window in bytes: how far past what was read the credit is raised.
writtenTotal: i64 Bytes the application wrote to every stream, sent or not; a write may not take it past sendMaxData.
beginPacket(): void Starts a packet: the next putNextChunk calls look at each stream at most once.
chunkAcked(id: i64, offset: i64, length: i32, fin: boolean): void A packet that carried bytes [offset, offset + length) of stream id, and its FIN when fin, was acknowledged: the bytes are marked, the buffer's start moves past every acknowledged one, and once all of them and the FIN are, the sending side is done (§3.1 "Data Recvd").
chunkLost(id: i64, offset: i64, length: i32, fin: boolean): void A packet that carried those bytes was lost: they are queued to go again, unless the side is done or reset.
find(id: i64): QuicStream | null The stream id, or null when it is not open.
giveBack(): void Gives every slot's borrowed buffers back, each with its used extent zeroed.
onMaxStreamData(id: i64, limit: i64): i64 MAX_STREAM_DATA (§19.10): more credit for the stream. Answers 0 or the transport error.
onReset(id: i64, code: i64, finalSize: i64): i64 RESET_STREAM (§19.4): the peer abandons the stream at finalSize with code. Answers 0 or the transport error.
onStopSending(id: i64, code: i64): i64 STOP_SENDING (§19.5): the peer wants no more of the stream, which this side answers with RESET_STREAM carrying the same code (§3.5). Answers 0 or the transport error.
onStream(id: i64, offset: i64, buf: u8[], from: i32, length: i32, fin: boolean): i64 A STREAM frame: length bytes of buf from from, at stream offset offset, and the FIN when fin. Answers 0, or the transport error that closes the connection: the stream's ID (see locate), a stream only this side sends on, the final size, or the credit.
prime(bytes: i32): void Readies the pools for a packet of bytes bytes, before the arena scope its frames are handled in: one buffer for every receive side it could start, which is no more than the sides holding none, nor than one per three bytes (the smallest STREAM frame carrying a byte, but for a last one without a length).

The peer's remaining stream credit is no tighter bound: an ACK earlier in the same packet can finish a stream, and release then raises the limit before a later STREAM frame opens past the old one. A bound that allows for every such release is one buffer per side holding none, which idle already is. Once warm the buffers a packet gives back refill the reserve for the next one, so this costs a handful of comparisons, not a take per side.
putNextChunk(buf: u8[], at: i32, end: i32): i32 Writes one STREAM frame into buf[at .. end) for the next stream, in turn, that has one to send: its lost bytes first, else as many new ones as fit and both credits allow, with the FIN when the rest fits. Answers the offset past it, with lastId, lastOffset, lastLength and lastFin describing it for the packet's record; or at when no stream has a frame that fits.
read(id: i64, buf: u8[], at: i32, length: i32): i32 Reads up to length bytes of stream id into buf from at. Answers how many it read; 0 when nothing is there yet; QUIC_STREAM_END once every byte up to the FIN was read; QUIC_STREAM_ERR_RESET once the peer reset it; or another QUIC_STREAM_ERR_*. Reading half a buffer gives the peer more credit. A stream's receiving side is done when a read answers QUIC_STREAM_END or QUIC_STREAM_ERR_RESET, so read until one does. After QuicConnection.release, a stream that still owed bytes answers QUIC_STREAM_END and copies nothing: its buffer went back to the pool.
reset(): void Frees every slot and puts every counter back, for a connection slot reused for another peer. Every buffer a stream still held goes back to its pool first.
resetStream(id: i64, code: i64): i32 Resets stream id's sending side with code. Answers QUIC_STREAM_OK or a QUIC_STREAM_ERR_*.
setPeerLimits(maxData: i64, bidiLocal: i64, bidiRemote: i64, uni: i64, maxStreamsBidi: i64, maxStreamsUni: i64): void Takes the peer's transport parameters (RFC 9000 §18.2): its limits on the streams this side opens, the credit each kind of stream starts with, and the connection's.
share(pools: QuicStreamPools): void Borrows the stream buffers from pools from now on, in place of the table's own: how a server's connections share one set. Call it before any stream has borrowed, or after reset. Panics when the pools' buffers are not bufferSize bytes.
slotOf(id: i64): i32 The slot of stream id, or -1 when it is not open.
stopSending(id: i64, code: i64): i32 Asks the peer to stop sending on stream id, with code (STOP_SENDING, §3.5). Answers QUIC_STREAM_OK or a QUIC_STREAM_ERR_*.
write(id: i64, buf: u8[], from: i32, length: i32, fin: boolean): i32 Writes up to length bytes of buf from from to stream id, and its FIN when fin and every byte fit. Answers how many bytes it took — fewer than length when the send buffer is full, and the stream's event fires once acknowledgements free room — or a QUIC_STREAM_ERR_*.

Constants

3

QUIC_RECV_DATA_READ: i32

Every byte was read: the side is done (§3.2 "Data Read").

2

QUIC_RECV_DATA_RECVD: i32

Every byte up to the final size arrived (§3.2 "Data Recvd").

6

QUIC_RECV_NONE: i32

The stream has no receiving side here: a unidirectional stream this side opened.

0

QUIC_RECV_RECV: i32

Receiving, the final size not known yet (§3.2 "Recv").

5

QUIC_RECV_RESET_READ: i32

The application saw the reset: the side is done (§3.2 "Reset Read").

4

QUIC_RECV_RESET_RECVD: i32

The peer reset the stream (§3.2 "Reset Recvd").

1

QUIC_RECV_SIZE_KNOWN: i32

The FIN fixed the final size; bytes are still missing (§3.2 "Size Known").

3

QUIC_SEND_DATA_RECVD: i32

Every byte and the FIN acknowledged: the side is done (§3.1 "Data Recvd").

2

QUIC_SEND_DATA_SENT: i32

Every byte and the FIN sent, not all acknowledged (§3.1 "Data Sent").

6

QUIC_SEND_NONE: i32

The stream has no sending side here: a unidirectional stream the peer opened.

0

QUIC_SEND_READY: i32

A sending side with nothing written yet (§3.1 "Ready").

5

QUIC_SEND_RESET_RECVD: i32

RESET_STREAM acknowledged: the side is done (§3.1 "Reset Recvd").

4

QUIC_SEND_RESET_SENT: i32

RESET_STREAM sent, not yet acknowledged (§3.1 "Reset Sent").

1

QUIC_SEND_SEND: i32

Data written, not all of it sent with the FIN (§3.1 "Send").

7

QUIC_STREAM_CONTROL_DATA_BLOCKED: i32

DATA_BLOCKED.

3

QUIC_STREAM_CONTROL_MAX_DATA: i32

MAX_DATA, the connection's credit.

5

QUIC_STREAM_CONTROL_MAX_STREAMS_BIDI: i32

MAX_STREAMS for bidirectional streams.

6

QUIC_STREAM_CONTROL_MAX_STREAMS_UNI: i32

MAX_STREAMS for unidirectional streams.

4

QUIC_STREAM_CONTROL_MAX_STREAM_DATA: i32

MAX_STREAM_DATA for the stream the record's value names.

11

QUIC_STREAM_CONTROL_RESET: i32

RESET_STREAM for the stream the value names.

12

QUIC_STREAM_CONTROL_STOP_SENDING: i32

STOP_SENDING for the stream the value names.

9

QUIC_STREAM_CONTROL_STREAMS_BLOCKED_BIDI: i32

STREAMS_BLOCKED for bidirectional streams.

10

QUIC_STREAM_CONTROL_STREAMS_BLOCKED_UNI: i32

STREAMS_BLOCKED for unidirectional streams.

8

QUIC_STREAM_CONTROL_STREAM_DATA_BLOCKED: i32

STREAM_DATA_BLOCKED for the stream the value names.

-7

QUIC_STREAM_END: i32

A read past the end: every byte up to the FIN has been read.

-5

QUIC_STREAM_ERR_DIRECTION: i32

The stream has no such side: a write to a stream only the peer sends on, or a read of one only this side sends on.

-2

QUIC_STREAM_ERR_FINISHED: i32

The stream's sending side is finished: a FIN was written, or the stream was reset.

-3

QUIC_STREAM_ERR_FLOW: i32

The data would pass the credit the peer gave, or the room in the send buffer (all-or-nothing writeStream).

-6

QUIC_STREAM_ERR_LIMIT: i32

No stream can be opened now: the peer's MAX_STREAMS is reached (STREAMS_BLOCKED is sent), or every local slot is taken.

-8

QUIC_STREAM_ERR_RESET: i32

The peer reset the stream (RESET_STREAM): resetCode holds its error code.

-4

QUIC_STREAM_ERR_STATE: i32

The connection is not connected.

-9

QUIC_STREAM_ERR_STOPPED: i32

The peer asked this side to stop sending (STOP_SENDING), which reset the stream: stopCode holds its code.

-1

QUIC_STREAM_ERR_UNKNOWN: i32

No such stream: never opened, or already finished both ways and gone.

0

QUIC_STREAM_OK: i32

Done: the data was taken, or the frame queued.