tiny.quic.connection.stream

1/// Tracks what the peer has allowed this endpoint to send, over one stream or over the whole2/// connection. The sending part of a stream and the connection each hold one so every byte sent is3/// charged against it. Its fields are that allowance, how much of it has gone, and the figure a4/// BLOCKED frame last reported. What has gone stays inside the allowance.5pub const Credit = struct {6    limit: u62,7    used: u62 = 0,8    blocked_limit: ?u62 = null,910    pub fn init(limit: u62) Credit {11        return .{ .limit = limit };12    }1314    /// Counts what is left to send under the allowance so the send path sizes each chunk against15    /// it.16    pub fn available(self: Credit) u62 {17        std.debug.assert(self.used <= self.limit);18        return self.limit - self.used;19    }2021    /// Lifts the allowance to a larger figure the peer has granted. An arriving MAX_DATA or22    /// MAX_STREAM_DATA frame reaches the credit through this call. A figure at or under the23    /// allowance in hand leaves it alone, so a frame arriving behind its neighbors is harmless.24    pub fn raise(self: *Credit, maximum: u62) void {25        std.debug.assert(self.used <= self.limit);26        if (maximum <= self.limit) return;27        self.limit = maximum;28    }2930    /// Charges bytes that have gone out against the allowance so the send path records each newly31    /// sent byte here. The count stays inside what was left.32    pub fn consume(self: *Credit, count: u62) void {33        std.debug.assert(count <= self.available());34        self.used += count;35        std.debug.assert(self.used <= self.limit);36    }3738    /// Hands back the figure a BLOCKED frame would report so the send path decides whether that39    /// frame belongs in the packet it is building. The call answers while bytes are waiting and the40    /// allowance is spent. Each figure is reported once: one a sent frame already carried yields41    /// nothing until the peer lifts the allowance.42    pub fn blocked(self: Credit, waiting: bool) ?u62 {43        if (!waiting) return null;44        if (self.available() != 0) return null;45        const reported = self.blocked_limit orelse return self.limit;46        return if (reported == self.limit) null else self.limit;47    }4849    /// Notes which figure a BLOCKED frame has carried. The send path calls this once the frame is50    /// in a sealed packet. That figure stays at or under the allowance in force.51    pub fn markBlocked(self: *Credit, limit: u62) void {52        std.debug.assert(limit <= self.limit);53        self.blocked_limit = limit;54    }5556    /// Forgets the figure noted for the loss path so a sender still held up reports itself a second57    /// time after the report is lost. A lost frame carrying a stale figure leaves the note alone,58    /// because a later frame has carried the figure in force since.59    pub fn loseBlocked(self: *Credit, limit: u62) void {60        const reported = self.blocked_limit orelse return;61        std.debug.assert(reported <= self.limit);62        if (reported != limit) return;63        self.blocked_limit = null;64    }65};

1/// Tracks what this endpoint has told the peer it will take, over one stream or over the whole2/// connection. The receiving part of a stream and the connection each hold one so the window3/// decides both what arriving data is allowed and when a limit frame goes out. Its fields are the4/// window width, the figure in force, the totals arrived and given up to the application, and the5/// given-up total at which that figure was set. `init` opens with the figure set to the window6/// width.7pub const Window = struct {8    size: u62,9    limit: u62,10    received: u62 = 0,11    consumed: u62 = 0,12    update_base: u62 = 0,13    /// Flag set when the packet carrying the figure in force was lost, so a window with no new room14    /// still asks for a limit frame by having `update` offer that same figure a second time.15    /// `advertise` clears it.16    limit_lost: bool = false,1718    pub fn init(size: u62) Window {19        return .{ .size = size, .limit = size };20    }2122    /// Says whether an arrived total is still inside what this endpoint offered so the receiving23    /// part checks arriving data before accepting it, because a false answer closes the connection24    /// with FLOW_CONTROL_ERROR. A total level with the figure is taken, and one byte beyond it is25    /// turned away.26    pub fn allows(self: Window, received: u64) bool {27        return received <= self.limit;28    }2930    /// Notes an arrived total for the receiving part after `allows` has accepted the data. The31    /// total stays inside the figure in force. A total under one already noted leaves it alone.32    pub fn record(self: *Window, received: u62) void {33        std.debug.assert(received <= self.limit);34        if (received > self.received) self.received = received;35    }3637    /// Notes bytes the application has taken, or bytes a reset has thrown away, so reading stream38    /// bytes earns the peer more room. The given-up total climbs and stays at or under the arrived39    /// total.40    pub fn release(self: *Window, consumed: u62) void {41        std.debug.assert(consumed >= self.consumed);42        std.debug.assert(consumed <= self.received);43        self.consumed = consumed;44    }4546    /// Offers a larger figure once the application has taken half a window so the send path decides47    /// whether a MAX_DATA or MAX_STREAM_DATA frame belongs in the packet it is building. That48    /// figure is the given-up total plus one window width, stopping at the largest u62 value. With49    /// `limit_lost` set and no larger figure due, the call offers the figure in force a second50    /// time. The call offers nothing when no frame is called for.51    pub fn update(self: Window) ?u62 {52        std.debug.assert(self.consumed >= self.update_base);53        const progress: u64 = self.consumed - self.update_base;54        if (progress * 2 >= self.size) {55            const next = std.math.add(u62, self.consumed, self.size) catch std.math.maxInt(u62);56            if (next > self.limit) return next;57        }58        return if (self.limit_lost) self.limit else null;59    }6061    /// Notes the figure carried by a MAX_DATA frame, or by a MAX_STREAM_DATA frame, that has gone62    /// out, then clears `limit_lost`. The send path calls this once the limit frame is in a sealed63    /// packet. The figure climbs, save when a loss forces the same one out a second time. Noting a64    /// larger figure moves the mark that the next half window is counted from.65    pub fn advertise(self: *Window, limit: u62) void {66        std.debug.assert(limit <= std.math.add(u62, self.consumed, self.size) catch limit);67        if (limit == self.limit) {68            std.debug.assert(self.limit_lost);69            self.limit_lost = false;70            return;71        }72        std.debug.assert(limit > self.limit);73        self.limit_lost = false;74        self.limit = limit;75        self.update_base = self.consumed;76    }7778    /// Marks the figure in force as lost for the loss path when the lost frame carried it, so the79    /// peer still learns a limit whose frame was lost. A lost frame carrying a stale figure calls80    /// for nothing, because a later frame has carried the figure in force since.81    pub fn loseLimit(self: *Window, limit: u62) void {82        std.debug.assert(limit <= self.limit);83        if (limit != self.limit) return;84        self.limit_lost = true;85    }86};

1/// Whether one endpoint or both may send on a stream. This connection carries one bidirectional2/// stream, so a unidirectional identifier closes the connection.3pub const Direction = enum { bidirectional, unidirectional };

1/// Which of the two endpoints opened a stream. `admitStream` compares it against this endpoint's2/// own role to decide whether an arriving frame names a stream this endpoint opened.3pub const Initiator = enum { client, server };

1/// One stretch of arrived bytes for the caller sizing the range table, held as the offset it starts2/// at and the offset it ends at. Every stretch sits at or above the read offset, because a read3/// trims away what it takes.4pub const Range = struct {5    start: u62,6    end: u62,78    pub fn empty() Range {9        return .{ .start = 0, .end = 0 };10    }11};

1/// Result of one read, recording how many bytes the call copied and whether it carried the read2/// offset to the final size. `read` returns this result so an application learns from the FIN flag3/// that the stream ended.4pub const ReadResult = struct {5    bytes: usize,6    fin: bool,7};

1/// The half of one stream that takes data in, held for stream 0 by the connection and driven from2/// arriving frames, working out of a ring and a range table the caller supplies. This half holds3/// that ring and table, the stream's window, the state, the read offset, the final size, and the4/// codes a reset and a stop carried. `init` wants both the ring and the table nonempty, and a5/// window no wider than the ring.6pub const Receive = struct {7    bytes: []u8,8    ranges: []Range,9    window: stream.Window,10    state: stream.ReceiveState = .recv,11    count: u16 = 0,12    head: usize = 0,13    read_offset: u62 = 0,14    final_size: ?u62 = null,15    reset_code: ?u62 = null,16    stop_code: ?u62 = null,17    stop_pending: bool = false,1819    pub fn init(bytes: []u8, ranges: []Range, window: u62) Receive {20        std.debug.assert(bytes.len > 0);21        std.debug.assert(ranges.len > 0);22        std.debug.assert(ranges.len <= std.math.maxInt(u16));23        std.debug.assert(window <= bytes.len);24        for (ranges) |*range| range.* = Range.empty();25        return .{ .bytes = bytes, .ranges = ranges, .window = stream.Window.init(window) };26    }2728    /// Takes in one arriving STREAM frame's data for the stream, putting up with bytes that repeat29    /// or overlap what has arrived already. The bytes new to the half are charged against this30    /// stream's window and against the connection window handed in. Data past either window answers31    /// `FlowControl`, and data that moves a settled final size or runs beyond one answers32    /// `FinalSize`. Data ending past the highest offset a stream can reach answers `FlowControl` as33    /// well. A packet that would want one stretch more than the table holds answers `RangesFull`.34    /// Once the half has everything, or has been reset, later data is charged against both windows35    /// and then thrown away. A frame carrying FIN settles the final size and moves the half to Size36    /// Known.37    pub fn receive(38        self: *Receive,39        connection: *stream.Window,40        offset: u62,41        data: []const u8,42        fin: bool,43    ) ReceiveError!void {44        if (data.len > std.math.maxInt(u62) - offset) return error.FlowControl;45        const end = offset + @as(u62, @intCast(data.len));46        try self.checkFinal(end, fin);47        const growth = try self.admit(connection, end);48        if (self.discarding()) return;49        const start = @max(offset, self.read_offset);50        if (start < end) {51            try self.insert(start, end);52            const skipped: usize = @intCast(start - offset);53            stream.ring.write(self.bytes, self.ringIndex(start), data[skipped..]);54        }55        self.window.record(end);56        connection.record(connection.received + growth);57        if (fin and self.final_size == null) {58            self.final_size = end;59            self.state = stream.receiveTransition(self.state, .receive_fin) catch unreachable;60        }61        self.observeComplete();62    }6364    /// Counts the bytes waiting in order at the read offset, so the caller learns how much one read65    /// can copy. The call answers zero after a reset, and zero while a hole sits at the read66    /// offset.67    pub fn readable(self: *const Receive) usize {68        if (self.reset_code != null) return 0;69        if (self.count == 0) return 0;70        const first = self.ranges[0];71        if (first.start != self.read_offset) return 0;72        return @intCast(first.end - first.start);73    }7475    /// Copies the waiting bytes in offset order for an application taking its bytes, and says76    /// whether the read reached the final size. What the call copies is given up to this stream's77    /// window and to the connection window, releasing room back to the peer so the peer earns more78    /// room. A read that passes the final size moves the half to Data Read. On a stream the peer79    /// reset, the call copies nothing and moves the half to Reset Read.80    pub fn read(self: *Receive, connection: *stream.Window, output: []u8) ReadResult {81        switch (self.state) {82            .reset_recvd => {83                self.state = stream.receiveTransition(.reset_recvd, .read_reset) catch unreachable;84                return .{ .bytes = 0, .fin = false };85            },86            .reset_read => return .{ .bytes = 0, .fin = false },87            .recv, .size_known, .data_recvd, .data_read => {},88        }89        const count = @min(output.len, self.readable());90        stream.ring.read(self.bytes, self.head, output[0..count]);91        self.consume(count);92        connection.release(connection.consumed + @as(u62, @intCast(count)));93        const fin = if (self.final_size) |final| self.read_offset == final else false;94        if (fin and self.state == .data_recvd) {95            self.state = stream.receiveTransition(.data_recvd, .read_all) catch unreachable;96        }97        return .{ .bytes = count, .fin = fin };98    }99100    /// Applies one arriving RESET_STREAM frame for the stream once the final size and both windows101    /// check out. A final size at odds with one already settled, or under what has arrived already,102    /// answers `FinalSize`, and a final size past either window answers `FlowControl`. Every byte103    /// up to the final size is given up to the connection window, the ones the application will104    /// never see among them. The call throws away the arrived stretches, keeps the error code,105    /// drops a STOP_SENDING that was waiting, and moves the half to Reset Recvd.106    pub fn resetReceived(107        self: *Receive,108        connection: *stream.Window,109        code: u62,110        final: u62,111    ) error{ FlowControl, FinalSize }!void {112        if (self.final_size) |known| {113            if (final != known) return error.FinalSize;114        }115        if (final < self.window.received) return error.FinalSize;116        const growth = try self.admit(connection, final);117        if (self.discarding()) return;118        self.window.record(final);119        connection.record(connection.received + growth);120        connection.release(connection.consumed + (final - self.read_offset));121        self.final_size = final;122        self.reset_code = code;123        self.stop_pending = false;124        self.removeRanges(0, self.count);125        self.state = stream.receiveTransition(self.state, .receive_reset) catch unreachable;126    }127128    /// Puts a STOP_SENDING frame in the queue while the peer might still send, so an application129    /// tells the peer to stop sending. The call answers false on a second call, and false once the130    /// half holds everything or has been reset, so the returned flag says whether the request was131    /// taken.132    pub fn stop(self: *Receive, code: u62) bool {133        if (self.stop_code != null) return false;134        if (self.discarding()) return false;135        self.stop_code = code;136        self.stop_pending = true;137        return true;138    }139140    /// Puts STOP_SENDING back in the queue for the loss path after its packet was lost, so the141    /// frame goes out again. The call queues nothing once the half holds everything or has been142    /// reset, because the peer has stopped by then. A stop code is in hand when this function is143    /// called.144    pub fn loseStop(self: *Receive) void {145        std.debug.assert(self.stop_code != null);146        if (self.discarding()) return;147        self.stop_pending = true;148    }149150    /// Offers a larger MAX_STREAM_DATA figure while more data may yet arrive, so the send path can151    /// decide whether a MAX_STREAM_DATA frame belongs in the packet it is building. Once the half152    /// has left Recv the final size is settled, so more room would buy nothing and the call offers153    /// none.154    pub fn windowUpdate(self: *const Receive) ?u62 {155        if (self.state != .recv) return null;156        return self.window.update();157    }158159    fn checkFinal(self: *const Receive, end: u62, fin: bool) error{FinalSize}!void {160        if (self.final_size) |final| {161            if (end > final) return error.FinalSize;162            if (fin and end != final) return error.FinalSize;163            return;164        }165        if (fin and end < self.window.received) return error.FinalSize;166    }167168    fn admit(169        self: *const Receive,170        connection: *const stream.Window,171        end: u62,172    ) error{FlowControl}!u62 {173        if (!self.window.allows(end)) return error.FlowControl;174        const growth = end -| self.window.received;175        if (!connection.allows(@as(u64, connection.received) + growth)) return error.FlowControl;176        return growth;177    }178179    fn discarding(self: *const Receive) bool {180        return switch (self.state) {181            .recv, .size_known => false,182            .data_recvd, .data_read, .reset_recvd, .reset_read => true,183        };184    }185186    fn insert(self: *Receive, start: u62, end: u62) error{RangesFull}!void {187        std.debug.assert(start < end);188        std.debug.assert(start >= self.read_offset);189        var first: usize = self.count;190        for (0..self.count) |index| {191            if (self.ranges[index].end >= start) {192                first = index;193                break;194            }195        }196        var last = first;197        for (first..self.count) |index| {198            if (self.ranges[index].start > end) break;199            last = index + 1;200        }201        if (first == last) return self.insertAt(first, .{ .start = start, .end = end });202        self.ranges[first] = .{203            .start = @min(start, self.ranges[first].start),204            .end = @max(end, self.ranges[last - 1].end),205        };206        self.removeRanges(first + 1, last - first - 1);207    }208209    fn insertAt(self: *Receive, at: usize, range: Range) error{RangesFull}!void {210        std.debug.assert(at <= self.count);211        if (self.count == self.ranges.len) return error.RangesFull;212        for (0..self.count - at) |step| {213            const index = self.count - step;214            self.ranges[index] = self.ranges[index - 1];215        }216        self.ranges[at] = range;217        self.count += 1;218    }219220    fn removeRanges(self: *Receive, at: usize, removed: usize) void {221        std.debug.assert(at + removed <= self.count);222        const remaining = self.count - removed;223        for (at..remaining) |index| self.ranges[index] = self.ranges[index + removed];224        for (remaining..self.count) |index| self.ranges[index] = Range.empty();225        self.count = @intCast(remaining);226    }227228    fn consume(self: *Receive, count: usize) void {229        if (count == 0) return;230        std.debug.assert(count <= self.readable());231        const advance: u62 = @intCast(count);232        self.read_offset += advance;233        self.head = (self.head + count) % self.bytes.len;234        self.ranges[0].start += advance;235        if (self.ranges[0].start == self.ranges[0].end) self.removeRanges(0, 1);236        self.window.release(self.read_offset);237    }238239    fn observeComplete(self: *Receive) void {240        if (self.state != .size_known) return;241        const final = self.final_size.?;242        const contiguous = self.read_offset + @as(u62, @intCast(self.readable()));243        if (contiguous != final) return;244        self.stop_pending = false;245        self.state = stream.receiveTransition(.size_known, .all_received) catch unreachable;246    }247248    fn ringIndex(self: *const Receive, offset: u62) usize {249        std.debug.assert(offset >= self.read_offset);250        const distance: usize = @intCast(offset - self.read_offset);251        std.debug.assert(distance < self.bytes.len);252        return (self.head + distance) % self.bytes.len;253    }254};

1pub const ReceiveError = error{ FlowControl, FinalSize, RangesFull };

1/// The bytes and the closing flag picked out for one STREAM frame, so the packet builder can turn2/// the chunk into a frame. The chunk holds the offset, those bytes, and that flag. The bytes point3/// into the send ring.4pub const Chunk = struct {5    offset: u62,6    data: []const u8,7    fin: bool,8};

1/// The half of one stream that puts data out, working out of a ring and a range table the caller2/// supplies, so the connection holds one for stream 0 and drives it from application writes and3/// recovery. The half holds that ring and table, the peer's credit, the state, the offsets4/// acknowledged, sent, and written, the final size, and the reset state. Those three offsets keep5/// their order, acknowledged at or under sent and sent at or under written. `init` wants both the6/// ring and the table nonempty.7pub const Send = struct {8    bytes: []u8,9    ranges: []SentRange,10    credit: stream.Credit,11    state: stream.SendState = .ready,12    head: usize = 0,13    acknowledged: u62 = 0,14    sent: u62 = 0,15    written: u62 = 0,16    final_size: ?u62 = null,17    fin_sent: bool = false,18    fin_acknowledged: bool = false,19    /// The stretch of the stream that a lost frame put back in the queue, so the next chunk can20    /// start below the sent offset. Those bytes go out ahead of anything the application has newly21    /// written.22    lost: quic.connection.recovery.LostRange = .{},23    /// Flag set when a lost frame carried the closing flag before an acknowledgment covered it,24    /// because a lost closing flag carries no bytes of its own and needs a dedicated flag. The flag25    /// clears once a copy goes out, once an acknowledgment covers the flag, or once a reset26    /// abandons the stream.27    fin_lost: bool = false,28    reset_code: ?u62 = null,29    reset_pending: bool = false,3031    pub fn init(bytes: []u8, ranges: []SentRange, limit: u62) Send {32        std.debug.assert(bytes.len > 0);33        std.debug.assert(ranges.len > 0);34        for (ranges) |*range| range.* = SentRange.empty();35        return .{ .bytes = bytes, .ranges = ranges, .credit = stream.Credit.init(limit) };36    }3738    /// Counts what the ring is holding, measured from the oldest byte the peer has yet to39    /// acknowledge, so `write` accepts what room remains. The count fits inside the ring.40    pub fn buffered(self: *const Send) usize {41        std.debug.assert(self.acknowledged <= self.sent);42        std.debug.assert(self.sent <= self.written);43        const count: usize = @intCast(self.written - self.acknowledged);44        std.debug.assert(count <= self.bytes.len);45        return count;46    }4748    /// Takes application bytes into the ring so they enter the stream, accepting as many as free49    /// room allows, and reports how many it took. The call accepts nothing once the final size is50    /// settled or a reset has abandoned the stream. The call also stops at the highest offset a51    /// stream can reach.52    pub fn write(self: *Send, input: []const u8) usize {53        if (!self.writable()) return 0;54        const free = self.bytes.len - self.buffered();55        const offset_room: u64 = std.math.maxInt(u62) - self.written;56        const count: usize = @intCast(@min(free, input.len, offset_room));57        if (count == 0) return 0;58        stream.ring.write(self.bytes, self.ringIndex(self.written), input[0..count]);59        self.written += @intCast(count);60        std.debug.assert(self.buffered() <= self.bytes.len);61        return count;62    }6364    /// Settles the final size at the last byte the application wrote, so the application ends its65    /// side of the stream. The call leaves state unchanged when the final size is settled already66    /// or the stream stands reset.67    pub fn finish(self: *Send) void {68        if (!self.writable()) return;69        self.final_size = self.written;70    }7172    /// Says whether this half has anything for the packet being built, so the send path decides73    /// whether to request a frame. Lost bytes, a lost closing flag, bytes never sent, and a closing74    /// flag never sent each count. A reset leaves nothing waiting, having abandoned what was there.75    pub fn pending(self: *const Send) bool {76        if (self.reset_code != null) return false;77        if (!self.lost.isEmpty() or self.fin_lost) return true;78        if (self.sent < self.written) return true;79        const final = self.final_size orelse return false;80        std.debug.assert(final == self.sent);81        return !self.fin_sent;82    }8384    /// Gives the offset the next STREAM frame will start at, so the packet builder can size the85    /// frame header against that offset before asking for a chunk. The start is the first byte86    /// waiting to go a second time, or, with none waiting, the first byte never sent.87    pub fn nextOffset(self: *const Send) u62 {88        if (self.lost.isEmpty()) return self.sent;89        std.debug.assert(self.lost.start >= self.acknowledged);90        std.debug.assert(self.lost.end <= self.sent);91        return self.lost.start;92    }9394    /// Picks out up to `data_max` bytes in order for the next STREAM frame, so the packet builder95    /// receives the payload for that frame. Bytes going a second time come first, then a closing96    /// flag on its own, and both travel free of credit. Bytes going out for the first time stop at97    /// this stream's own credit and at `connection_credit`. The pick also stops at the buffer end98    /// where the ring wraps, and at the longest payload a frame may carry. The closing flag travels99    /// with the pick that reaches the final size. The call returns null when the half has nothing100    /// waiting, and returns null when every entry in the table is taken.101    pub fn nextChunk(self: *const Send, data_max: usize, connection_credit: u62) ?Chunk {102        if (!self.pending()) return null;103        if (self.freeRange() == null) return null;104        if (!self.lost.isEmpty()) return self.lostChunk(data_max);105        if (self.fin_lost) return self.lostFin();106        const index = self.ringIndex(self.sent);107        const credit: u64 = @min(self.credit.available(), connection_credit);108        const waiting: u64 = self.written - self.sent;109        const room: u64 = @min(data_max, self.bytes.len - index, std.math.maxInt(u16));110        const count: usize = @intCast(@min(waiting, credit, room));111        const end = self.sent + @as(u62, @intCast(count));112        const fin = if (self.final_size) |final| end == final and !self.fin_sent else false;113        if (count == 0 and !fin) return null;114        return .{ .offset = self.sent, .data = self.bytes[index..][0..count], .fin = fin };115    }116117    /// Takes an entry in the table for the pick that has gone out, and reports how many of its118    /// bytes had never gone before, for the packet builder to call once the packet holding the119    /// frame is sealed and charge that count to connection credit. Only that figure is charged to120    /// the connection credit, because bytes going a second time sit under the highest offset121    /// already reached. A pick that had gone before reports zero and takes its bytes out of the122    /// waiting stretch. A pick of fresh bytes moves the sent offset on, spends this stream's123    /// credit, and moves the half's state.124    pub fn commitChunk(self: *Send, offset: u62, length: u16, fin: bool) u16 {125        const slot = self.freeRange() orelse unreachable;126        self.ranges[slot] = .{127            .offset = offset,128            .length = length,129            .fin = fin,130            .outstanding = true,131        };132        if (offset < self.sent or (fin and self.fin_sent)) {133            self.commitLost(offset, length, fin);134            return 0;135        }136        std.debug.assert(offset == self.sent);137        std.debug.assert(length <= self.written - self.sent);138        self.sent += length;139        self.credit.consume(length);140        if (fin) {141            std.debug.assert(self.sent == self.final_size.?);142            self.fin_sent = true;143        }144        const event: stream.SendEvent = if (fin) .send_fin else .send_data;145        self.state = stream.sendTransition(self.state, event) catch unreachable;146        return length;147    }148149    /// Hands back the figure a STREAM_DATA_BLOCKED frame would report while this stream's own150    /// credit holds the sender up, so the send path decides whether that frame belongs in the151    /// packet being built. The sender counts as held up while the stream stands unreset and bytes152    /// wait to go.153    pub fn blocked(self: *const Send) ?u62 {154        const waiting = self.reset_code == null and self.sent < self.written;155        return self.credit.blocked(waiting);156    }157158    /// Notes that a STREAM_DATA_BLOCKED frame went out, for the send path to call once the frame is159    /// in a sealed packet. That frame also starts the half moving, taking it out of Ready.160    pub fn commitBlocked(self: *Send, limit: u62) void {161        self.credit.markBlocked(limit);162        if (self.state != .ready) return;163        self.state = stream.sendTransition(.ready, .send_data) catch unreachable;164    }165166    /// Frees the ring bytes one acknowledged STREAM frame covered, and trims them off whichever end167    /// of the waiting stretch they reach, so an acknowledged packet frees the send buffer. An168    /// acknowledgment covering the closing flag clears a lost one. Bytes come free in offset order,169    /// so an acknowledgment above a frame still outstanding frees nothing yet. The call passes over170    /// a frame this half has already released. The closing flag acknowledged with every byte behind171    /// it carries the half to Data Recvd.172    pub fn acknowledge(self: *Send, offset: u62, length: u16, fin: bool) void {173        const slot = self.findRange(offset, length, fin) orelse return;174        self.ranges[slot] = SentRange.empty();175        self.lost.acknowledge(offset, length);176        if (fin) {177            self.fin_acknowledged = true;178            self.fin_lost = false;179        }180        self.releaseAcknowledged();181        if (self.state != .data_sent) return;182        if (!self.fin_acknowledged) return;183        if (self.acknowledged != self.sent) return;184        self.state = stream.sendTransition(.data_sent, .all_acknowledged) catch unreachable;185    }186187    /// Gives up the table entry a lost STREAM frame held, and puts its bytes, with a closing flag188    /// no acknowledgment has covered, in the stretch that goes ahead of fresh bytes, so lost bytes189    /// go out again ahead of new ones. A frame whose entry an acknowledgment or a reset has already190    /// given up calls for nothing.191    pub fn lose(self: *Send, offset: u62, length: u16, fin: bool) void {192        const slot = self.findRange(offset, length, fin) orelse return;193        std.debug.assert(offset >= self.acknowledged);194        std.debug.assert(offset + length <= self.sent);195        self.ranges[slot] = SentRange.empty();196        self.lost.add(offset, length);197        if (fin and !self.fin_acknowledged) self.fin_lost = true;198    }199200    /// Gives up on the bytes waiting, sent and unsent alike, and queues RESET_STREAM so an201    /// application can abandon the stream, returning whether the reset was taken. What a reset202    /// gives up on has no route back onto the wire. The call settles the final size at the highest203    /// offset already sent. The call returns false on a second call, and false once the half holds204    /// every acknowledgment or has sent its reset already.205    pub fn reset(self: *Send, code: u62) bool {206        if (self.reset_code != null) return false;207        switch (self.state) {208            .ready, .send, .data_sent => {},209            .data_recvd, .reset_sent, .reset_recvd => return false,210        }211        self.reset_code = code;212        self.reset_pending = true;213        self.written = self.sent;214        self.final_size = self.sent;215        self.lost = .{};216        self.fin_lost = false;217        for (self.ranges) |*range| range.* = SentRange.empty();218        self.releaseAcknowledged();219        std.debug.assert(self.buffered() == 0);220        return true;221    }222223    /// Hands back the RESET_STREAM frame that is waiting for a packet, so the send path can insert224    /// that frame into the packet being built. That frame carries the error code, and the highest225    /// offset sent as its final size. The call returns null when no reset waits.226    pub fn resetFrame(self: *const Send, stream_id: u62) ?quic.frame.ResetStream {227        if (!self.reset_pending) return null;228        const code = self.reset_code.?;229        return .{ .stream_id = stream_id, .error_code = code, .final_size = self.sent };230    }231232    /// Notes that a RESET_STREAM frame went out and carries the half into Reset Sent, for the send233    /// path to call once the frame is in a sealed packet. When a loss has put one RESET_STREAM234    /// frame out already, the half stands in Reset Sent as the copy goes, and stays there.235    pub fn commitReset(self: *Send) void {236        std.debug.assert(self.reset_pending);237        self.reset_pending = false;238        if (self.state == .reset_sent) return;239        self.state = stream.sendTransition(self.state, .send_reset) catch unreachable;240    }241242    /// Puts RESET_STREAM back in the queue after a loss, while the half sits in Reset Sent, so a243    /// lost RESET_STREAM goes out again. The copy carries the same code and final size, because244    /// `resetFrame` reads both out of the same fields. Once an acknowledgment has carried the half245    /// to Reset Recvd the peer knows, so nothing goes in the queue.246    pub fn loseReset(self: *Send) void {247        if (self.state != .reset_sent) return;248        std.debug.assert(self.reset_code != null);249        self.reset_pending = true;250    }251252    /// Notes the acknowledgment of the RESET_STREAM frame and carries the half into Reset Recvd, so253    /// an acknowledged RESET_STREAM ends the sending part. Called from any state other than Reset254    /// Sent, the call leaves state unchanged.255    pub fn acknowledgeReset(self: *Send) void {256        if (self.state != .reset_sent) return;257        self.reset_pending = false;258        self.state = stream.sendTransition(.reset_sent, .reset_acknowledged) catch unreachable;259    }260261    fn writable(self: *const Send) bool {262        if (self.final_size != null) return false;263        if (self.reset_code != null) return false;264        std.debug.assert(self.state != .data_sent);265        std.debug.assert(self.state != .data_recvd);266        return true;267    }268269    fn lostChunk(self: *const Send, data_max: usize) ?Chunk {270        std.debug.assert(!self.lost.isEmpty());271        const offset = self.lost.start;272        const index = self.ringIndex(offset);273        const room: u64 = @min(data_max, self.bytes.len - index, std.math.maxInt(u16));274        const count: usize = @intCast(@min(self.lost.length(), room));275        if (count == 0) return null;276        const end = offset + @as(u62, @intCast(count));277        const fin = self.fin_lost and end == self.final_size.?;278        return .{ .offset = offset, .data = self.bytes[index..][0..count], .fin = fin };279    }280281    fn lostFin(self: *const Send) Chunk {282        std.debug.assert(self.fin_lost);283        std.debug.assert(self.fin_sent);284        std.debug.assert(self.final_size.? == self.sent);285        const index = self.ringIndex(self.sent);286        return .{ .offset = self.sent, .data = self.bytes[index..][0..0], .fin = true };287    }288289    fn commitLost(self: *Send, offset: u62, length: u16, fin: bool) void {290        if (fin) {291            std.debug.assert(self.fin_lost);292            self.fin_lost = false;293        }294        if (length == 0) return;295        std.debug.assert(offset == self.lost.start);296        self.lost.advance(length);297    }298299    fn releaseAcknowledged(self: *Send) void {300        var lowest = self.sent;301        if (!self.lost.isEmpty()) lowest = @min(lowest, self.lost.start);302        for (self.ranges) |range| {303            if (range.outstanding and range.offset < lowest) lowest = range.offset;304        }305        std.debug.assert(lowest >= self.acknowledged);306        const released: usize = @intCast(lowest - self.acknowledged);307        std.debug.assert(released <= self.bytes.len);308        self.head = (self.head + released) % self.bytes.len;309        self.acknowledged = lowest;310    }311312    fn ringIndex(self: *const Send, offset: u62) usize {313        std.debug.assert(offset >= self.acknowledged);314        const distance: usize = @intCast(offset - self.acknowledged);315        std.debug.assert(distance <= self.bytes.len);316        return (self.head + distance) % self.bytes.len;317    }318319    fn freeRange(self: *const Send) ?usize {320        for (self.ranges, 0..) |range, index| {321            if (!range.outstanding) return index;322        }323        return null;324    }325326    fn findRange(self: *const Send, offset: u62, length: u16, fin: bool) ?usize {327        for (self.ranges, 0..) |range, index| {328            if (!range.outstanding) continue;329            if (range.offset != offset) continue;330            if (range.length == length and range.fin == fin) return index;331        }332        return null;333    }334};

1/// One STREAM frame that has gone out, held until an acknowledgment or a loss settles it, so the2/// caller can size the range table to hold one entry for each outstanding frame. The entry holds3/// the offset, the byte count, whether that frame closed the stream, and whether the entry is4/// taken.5pub const SentRange = struct {6    offset: u62,7    length: u16,8    fin: bool,9    outstanding: bool,1011    pub fn empty() SentRange {12        return .{ .offset = 0, .length = 0, .fin = false, .outstanding = false };13    }14};

1/// Events that carry the receiving part from one state to the next, grouped so a caller names2/// everything that can move that half.3pub const ReceiveEvent = enum {4    /// A frame carrying data without the closing flag has arrived.5    receive_data,6    /// A frame carrying the closing flag has arrived.7    receive_fin,8    /// Every byte up to the final size has arrived.9    all_received,10    /// The application has taken every byte up to the final size.11    read_all,12    /// A RESET_STREAM frame has arrived.13    receive_reset,14    /// The application has seen the reset.15    read_reset,16};

1/// States the other half of a stream, the receiving part, passes through, returned by2/// `Connection.receiveState` so a caller learns how far the receiving part has traveled. These3/// states are recv, size_known, data_recvd, data_read, reset_recvd, and reset_read.4pub const ReceiveState = enum {5    recv,6    size_known,7    data_recvd,8    data_read,9    reset_recvd,10    reset_read,11};

1/// Events that carry the sending part from one state to the next, grouped so a caller names2/// everything that can move that half.3pub const SendEvent = enum {4    /// A frame carrying data without the closing flag, or a STREAM_DATA_BLOCKED frame, has gone5    /// out.6    send_data,7    /// A frame carrying the closing flag has gone out.8    send_fin,9    /// The peer has acknowledged every byte up to the final size, and the closing flag with them.10    all_acknowledged,11    /// A RESET_STREAM frame has gone out.12    send_reset,13    /// The peer has acknowledged the RESET_STREAM frame.14    reset_acknowledged,15};

1/// States one half of a stream, the sending part, passes through, returned by2/// `Connection.sendState` so a caller learns how far the sending part has traveled. These states3/// are ready, send, data_sent, data_recvd, reset_sent, and reset_recvd.4pub const SendState = enum {5    ready,6    send,7    data_sent,8    data_recvd,9    reset_sent,10    reset_recvd,11};

1pub const TransitionError = error{InvalidTransition};

1/// Reads out of the identifier's second bit whether both sides may send, so `admitStream` rejects a2/// unidirectional stream outright. A zero there names a stream both sides send on, and a one names3/// a stream only its opener sends on.4pub fn direction(id: StreamId) Direction {5    return if (id & 0x02 == 0) .bidirectional else .unidirectional;6}

1/// Reads the opener out of the identifier's lowest bit, so `admitStream` calls this function first2/// because a frame for a stream this endpoint should have opened itself is a state error. A zero3/// there names the client and a one names the server.4pub fn initiator(id: StreamId) Initiator {5    return if (id & 0x01 == 0) .client else .server;6}

1/// Counts the streams of the same opener and kind that come before this one, so `admitStream`2/// compares the sequence against the advertised stream limit. The sequence is the identifier3/// shifted past its two lowest bits.4pub fn sequence(id: StreamId) u60 {5    return @intCast(id >> 2);6}

1/// Assembles the STREAM frame around one pick, so the packet builder turns the chunk into the frame2/// it encodes. The OFF bit goes in whenever the offset stands above zero.3pub fn frame(stream_id: u62, chunk: Chunk, length_present: bool) quic.frame.Frame {4    return .{ .stream = .{5        .stream_id = stream_id,6        .offset = chunk.offset,7        .offset_present = chunk.offset != 0,8        .length_present = length_present,9        .fin = chunk.fin,10        .data = chunk.data,11    } };12}

1/// Works out the most data a STREAM frame can carry inside `available` bytes, so the packet builder2/// turns the room left in a packet into a byte count it can ask the sending part for. The call3/// returns null when even a frame without data cannot fit. The length field widens as the data4/// grows, so the answer is settled in two passes.5pub fn frameDataCapacity(6    stream_id: u62,7    offset: u62,8    available: usize,9    length_present: bool,10) ?usize {11    const empty = frameHeaderBytes(stream_id, offset, 0, length_present);12    if (empty > available) return null;13    const first = available - empty;14    const header = frameHeaderBytes(stream_id, offset, first, length_present);15    if (header + first <= available) return first;16    std.debug.assert(header <= available);17    const second = available - header;18    const second_header = frameHeaderBytes(stream_id, offset, second, length_present);19    std.debug.assert(second_header + second <= available);20    return second;21}

1/// Counts the bytes a STREAM frame spends ahead of `length` bytes of data, so the packet builder2/// knows the header size before determining how many data bytes fit. Those bytes carry the frame3/// type and the stream identifier always, the offset whenever it stands above zero, and the length4/// whenever the caller asks for one.5pub fn frameHeaderBytes(stream_id: u62, offset: u62, length: usize, length_present: bool) usize {6    std.debug.assert(length <= std.math.maxInt(u62));7    var bytes: usize = 1 + @as(usize, quic.varint.encodedLength(stream_id));8    if (offset != 0) bytes += quic.varint.encodedLength(offset);9    if (length_present) bytes += quic.varint.encodedLength(@intCast(length));10    return bytes;11}

1/// Applies every move of the receiving part, taking one event against the current state and giving2/// back the state it lands in so a move the table has no entry for is caught at the table. An event3/// the current state has no entry for answers `InvalidTransition`. Data Read and Reset Read lead4/// nowhere further.5pub fn receiveTransition(state: ReceiveState, event: ReceiveEvent) TransitionError!ReceiveState {6    return switch (state) {7        .recv => switch (event) {8            .receive_data => .recv,9            .receive_fin => .size_known,10            .receive_reset => .reset_recvd,11            .all_received, .read_all, .read_reset => error.InvalidTransition,12        },13        .size_known => switch (event) {14            .receive_data => .size_known,15            .all_received => .data_recvd,16            .receive_reset => .reset_recvd,17            .receive_fin, .read_all, .read_reset => error.InvalidTransition,18        },19        .data_recvd => if (event == .read_all) .data_read else error.InvalidTransition,20        .reset_recvd => if (event == .read_reset) .reset_read else error.InvalidTransition,21        .data_read, .reset_read => error.InvalidTransition,22    };23}

1/// Applies every move of the sending part, taking one event against the current state and giving2/// back the state it lands in so a move the table has no entry for is caught at the table. An event3/// the current state has no entry for answers `InvalidTransition`. Data Recvd and Reset Recvd lead4/// nowhere further.5pub fn sendTransition(state: SendState, event: SendEvent) TransitionError!SendState {6    return switch (state) {7        .ready, .send => switch (event) {8            .send_data => .send,9            .send_fin => .data_sent,10            .send_reset => .reset_sent,11            .all_acknowledged, .reset_acknowledged => error.InvalidTransition,12        },13        .data_sent => switch (event) {14            .all_acknowledged => .data_recvd,15            .send_reset => .reset_sent,16            .send_data, .send_fin, .reset_acknowledged => error.InvalidTransition,17        },18        .reset_sent => switch (event) {19            .reset_acknowledged => .reset_recvd,20            .send_data, .send_fin, .all_acknowledged, .send_reset => error.InvalidTransition,21        },22        .data_recvd, .reset_recvd => error.InvalidTransition,23    };24}

1/// The number that names one QUIC stream serves as the type for every stream argument in the public2/// API. The value is sixty-two bits wide and unsigned.3pub const StreamId = u62;

1pub const stream = @import("stream/root.zig");

1const flow = @import("flow.zig");2const id = @import("id.zig");3const receive = @import("receive.zig");4const send = @import("send.zig");5const state = @import("state.zig");67pub const ring = @import("ring.zig");89pub const StreamId = id.StreamId;10pub const Initiator = id.Initiator;11pub const Direction = id.Direction;12pub const initiator = id.initiator;13pub const direction = id.direction;14pub const sequence = id.sequence;1516pub const SendState = state.SendState;17pub const SendEvent = state.SendEvent;18pub const ReceiveState = state.ReceiveState;19pub const ReceiveEvent = state.ReceiveEvent;20pub const TransitionError = state.TransitionError;21pub const sendTransition = state.sendTransition;22pub const receiveTransition = state.receiveTransition;2324pub const Credit = flow.Credit;25pub const Window = flow.Window;2627pub const SentRange = send.SentRange;28pub const Chunk = send.Chunk;29pub const Send = send.Send;30pub const frameHeaderBytes = send.frameHeaderBytes;31pub const frameDataCapacity = send.frameDataCapacity;32pub const frame = send.frame;3334pub const Range = receive.Range;35pub const ReadResult = receive.ReadResult;36pub const ReceiveError = receive.ReceiveError;37pub const Receive = receive.Receive;