// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The one seam onto the connection's writer. //! //! Every frame this server sends goes through here, from every task: N stream //! tasks writing HEADERS and DATA, and the reader task writing SETTINGS acks, //! PING acks, RST_STREAM, WINDOW_UPDATE and GOAWAY. A `transport.Connection` //! has exactly one `Io.Writer` and no lock of its own, so this supplies both //! the lock and the rule about who may hold it. //! //! ## A mutex, not a writer task //! //! The tidy-looking alternative is a task that owns the writer and is fed //! frames through an `Io.Queue`. It is the wrong trade here. A DATA frame's //! payload is the handler's memory, still live on its stack inside //! `Io.Writer.drain`, so handing a slice to another task means either copying //! every octet of every body or blocking the handler until the writer says it //! is done — which is a mutex with two extra context switches in front of it. //! And HEADERS with its CONTINUATION frames may not be interleaved with //! anything (§6.2), so the queue would need a "hold everything" mode, which //! is a lock again. //! //! ## The outbox, and the deadlock it exists to break //! //! With a plain mutex there is a genuine deadlock, not merely a stall. Our //! writes block because the peer has stopped reading; the task holding the //! mutex therefore blocks; the reader task blocks trying to take the mutex to //! send a PING ack or a WINDOW_UPDATE; so we stop reading; so the peer's //! writes block; and neither end will ever move again. //! //! `sendControl` never blocks. It leaves the frame in a small buffer, the //! outbox, which whoever next holds the mutex flushes first, and wakes //! `runControlWriter` -- a task of its own, and the only one that writes //! control frames to the socket on the reader's behalf. That turns "the reader //! is stuck behind the writer" into "control frames are a little late", which //! is survivable. //! //! The reader cannot write them itself even when the mutex is free, which is //! what this once did: a free mutex does not make the socket writable, and a //! reader blocked in a flush on a peer that has stopped reading is the same //! deadlock with one fewer task in it. //! //! GOAWAY deliberately does not use the outbox: it is the last thing this //! connection will ever say, and it must not be left sitting in a buffer that //! is about to be freed. const std = @import("std"); const Io = std.Io; const frame = @import("frame.zig"); const Serializer = @This(); io: Io, out: *Io.Writer, /// Held across the socket write. The one place this library serialises on /// I/O, and the reason for the lock-order rule at the top of /// `Connection.zig`: nothing else may be acquired while this is held. mutex: Io.Mutex = .init, /// Control frames the reader wanted to send while a stream held `mutex`. /// Guarded by `outbox_mutex`, which is never held across I/O and so is only /// ever contended for nanoseconds. outbox_mutex: Io.Mutex = .init, outbox: [outbox_len]u8 = undefined, outbox_used: usize = 0, /// Signalled when the outbox gains a frame, for `runControlWriter`. Waited on /// under `outbox_mutex`. outbox_ready: Io.Condition = .init, /// Set once the write side has failed, so that N tasks do not each discover /// it by hammering a dead socket. failed: std.atomic.Value(bool) = .init(false), /// Room for about sixty control frames. A backlog past that means the peer /// has stopped reading and is still sending us things that demand a reply, /// which is `ENHANCE_YOUR_CALM` rather than something to buffer. pub const outbox_len = 1024; pub const Error = error{ /// The connection's writer failed, or has already failed. WriteFailed, /// This task was cancelled while waiting for the lock. `Io.recancel` has /// already been called, so the next cancellation point will fire. Canceled, }; pub const OutboxError = error{ /// The outbox is full: the peer is not reading and will not stop talking. OutboxFull, }; /// A serializer for `out`, which it does not own: `out` must outlive it, and /// nothing else may write to `out` once frames are going through here. pub fn init(io: Io, out: *Io.Writer) Serializer { return .{ .io = io, .out = out }; } test init { var buffer: [64]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); try s.send(.{ .length = 0, .type = .settings, .flags = 0, .stream_id = 0 }, &.{}); try testing.expectEqual(@as(usize, frame.header_len), out.end); } /// Takes the lock, flushes anything the outbox is holding, and hands back a /// writer to put a frame on. The caller must `release` it — but only on /// success: an error has already let the lock go, or never took it. /// /// Separate from `send` because HEADERS and its CONTINUATION frames have to /// go out under one hold, and so does a DATA frame whose payload the caller /// is streaming rather than holding. pub fn acquire(s: *Serializer) Error!*Io.Writer { if (s.failed.load(.acquire)) return error.WriteFailed; s.mutex.lock(s.io) catch { s.io.recancel(); return error.Canceled; }; errdefer s.mutex.unlock(s.io); try s.drainOutbox(); return s.out; } test acquire { var buffer: [64]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); // A HEADERS and its CONTINUATION, which nothing may come between. const w = try s.acquire(); defer s.release(); try (frame.Header{ .length = 0, .type = .headers, .flags = 0, .stream_id = 1 }).writeTo(w); try (frame.Header{ .length = 0, .type = .continuation, .flags = 0x04, .stream_id = 1 }).writeTo(w); try testing.expectEqual(@as(usize, 2 * frame.header_len), out.end); } /// Flushes and releases. Flushing on every release is deliberate and is not /// merely tidy: a DATA frame left sitting in the connection writer's buffer, /// while its stream waits for a WINDOW_UPDATE the peer will only send once it /// has seen that data, is a deadlock. /// /// A flush that fails is not reported here, but it is remembered: every /// later call refuses with `error.WriteFailed`. pub fn release(s: *Serializer) void { s.out.flush() catch s.fail(); s.mutex.unlock(s.io); } test release { var buffer: [64]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); _ = try s.acquire(); s.release(); // Released, so the lock is free for the next frame. try s.send(.{ .length = 0, .type = .settings, .flags = 0x01, .stream_id = 0 }, &.{}); } /// One complete frame, under one hold. `header.length` is the caller's to /// make agree with `payload`; nothing here checks it. pub fn send(s: *Serializer, header: frame.Header, payload: []const u8) Error!void { const out = try s.acquire(); defer s.release(); header.writeTo(out) catch return s.failWrite(); out.writeAll(payload) catch return s.failWrite(); } test send { var buffer: [64]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); try s.send(.{ .length = 8, .type = .ping, .flags = 0, .stream_id = 0 }, "12345678"); var in: Io.Reader = .fixed(out.buffered()); const h = try frame.Header.read(&in); try testing.expectEqual(frame.Type.ping, h.type); try testing.expectEqualStrings("12345678", try in.take(h.length)); } /// Queues a control frame -- an acknowledgement, a WINDOW_UPDATE, a /// RST_STREAM -- and returns without waiting for it to be written, so that the /// reader task can call it however stuck the socket is. `runControlWriter` /// sends it, or whichever task next takes the lock, whichever comes first. /// /// `error.OutboxFull` when there is no room: a peer that has stopped reading /// and keeps sending things that demand a reply. See `outbox_len`. pub fn sendControl(s: *Serializer, header: frame.Header, payload: []const u8) (Error || OutboxError)!void { if (s.failed.load(.acquire)) return error.WriteFailed; s.outbox_mutex.lockUncancelable(s.io); defer s.outbox_mutex.unlock(s.io); const needed = frame.header_len + payload.len; if (needed > s.outbox.len - s.outbox_used) return error.OutboxFull; header.write(s.outbox[s.outbox_used..][0..frame.header_len]); @memcpy(s.outbox[s.outbox_used + frame.header_len ..][0..payload.len], payload); s.outbox_used += needed; s.outbox_ready.signal(s.io); } test sendControl { var buffer: [64]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); // Queued, not written... try s.sendControl(.{ .length = 0, .type = .settings, .flags = 0x01, .stream_id = 0 }, &.{}); try testing.expectEqual(@as(usize, 0), out.end); // ...until something next holds the lock, which sends it first. try s.send(.{ .length = 0, .type = .data, .flags = 0, .stream_id = 1 }, &.{}); var in: Io.Reader = .fixed(out.buffered()); try testing.expectEqual(frame.Type.settings, (try frame.Header.read(&in)).type); try testing.expectEqual(frame.Type.data, (try frame.Header.read(&in)).type); } /// Sends what `sendControl` queues, for as long as the connection lasts: the /// task that takes the lock and blocks on the socket so that the reader never /// has to. Returns when cancelled, or once the writer has failed. pub fn runControlWriter(s: *Serializer) void { while (!s.failed.load(.acquire)) { { s.outbox_mutex.lock(s.io) catch return; defer s.outbox_mutex.unlock(s.io); while (s.outbox_used == 0) s.outbox_ready.wait(s.io, &s.outbox_mutex) catch return; } // `acquire` empties the outbox, and `release` flushes it. _ = s.acquire() catch return; s.release(); } } test runControlWriter { var buffer: [64]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); var group: Io.Group = .init; defer group.cancel(testing.io); try group.concurrent(testing.io, runControlWriter, .{&s}); try s.sendControl(.{ .length = 0, .type = .settings, .flags = 0x01, .stream_id = 0 }, &.{}); // Written by the other task, with nothing here taking the lock. var waited: usize = 0; while (@atomicLoad(usize, &out.end, .acquire) == 0 and waited < 500) : (waited += 1) { try testing.io.sleep(.fromMilliseconds(10), .awake); } s.mutex.lockUncancelable(testing.io); defer s.mutex.unlock(testing.io); try testing.expectEqual(@as(usize, frame.header_len), out.end); } /// GOAWAY, which takes the blocking path on purpose: waiting for the lock is /// better than leaving the last frame in an outbox nobody will flush. pub fn sendGoaway(s: *Serializer, last_stream_id: u31, code: frame.ErrorCode, debug: []const u8) Error!void { const out = try s.acquire(); defer s.release(); frame.writeGoaway(out, last_stream_id, code, debug) catch return s.failWrite(); } test sendGoaway { var buffer: [64]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); try s.sendGoaway(5, .enhance_your_calm, ""); var in: Io.Reader = .fixed(out.buffered()); const h = try frame.Header.read(&in); try testing.expectEqual(frame.Type.goaway, h.type); const g = try frame.parseGoaway(try in.take(h.length)); try testing.expectEqual(@as(u31, 5), g.last_stream_id); try testing.expectEqual(frame.ErrorCode.enhance_your_calm, g.code); } /// Must be called with `mutex` held. /// Writes what the outbox holds. Called with `mutex` held, which is what keeps /// the frames in order: nothing else can write between the copy and the /// write. /// /// Copied out under `outbox_mutex` and written after letting it go, because /// the write can block and `sendControl` takes that lock on the reader's task. /// Writing under it was the reader blocked on the socket by another route. fn drainOutbox(s: *Serializer) Error!void { var pending: [outbox_len]u8 = undefined; const len = blk: { s.outbox_mutex.lockUncancelable(s.io); defer s.outbox_mutex.unlock(s.io); const len = s.outbox_used; @memcpy(pending[0..len], s.outbox[0..len]); s.outbox_used = 0; break :blk len; }; if (len == 0) return; s.out.writeAll(pending[0..len]) catch return s.failWrite(); } fn fail(s: *Serializer) void { s.failed.store(true, .release); } fn failWrite(s: *Serializer) Error { s.fail(); return error.WriteFailed; } const testing = std.testing; test "frames go out in the order they were sent" { var buffer: [256]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); try s.send(.{ .length = 0, .type = .settings, .flags = 0, .stream_id = 0 }, &.{}); try s.sendControl(.{ .length = 0, .type = .settings, .flags = 0x01, .stream_id = 0 }, &.{}); // What `runControlWriter` does when it wakes. _ = try s.acquire(); s.release(); try testing.expectEqualSlices(u8, &.{ 0, 0, 0, 0x04, 0x00, 0, 0, 0, 0, 0, 0, 0, 0x04, 0x01, 0, 0, 0, 0, }, buffer[0..out.end]); } test "a control frame waits in the outbox while the lock is held" { var buffer: [256]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); // Hold the lock the way a stream writing a body would. const held = try s.acquire(); try testing.expect(s.outbox_used == 0); // The reader wants to acknowledge a PING and must not block to do it. try s.sendControl(.{ .length = 0, .type = .settings, .flags = 0x01, .stream_id = 0 }, &.{}); try testing.expectEqual(@as(usize, frame.header_len), s.outbox_used); // And nothing of it has reached the wire yet. try testing.expectEqual(@as(usize, 0), out.end); // The holder writes its own frame and lets go. try (frame.Header{ .length = 0, .type = .data, .flags = 0x01, .stream_id = 1 }).writeTo(held); s.release(); // The next frame out flushes the outbox before its own. try s.send(.{ .length = 0, .type = .headers, .flags = 0x04, .stream_id = 3 }, &.{}); try testing.expectEqual(@as(usize, 0), s.outbox_used); var in: Io.Reader = .fixed(buffer[0..out.end]); try testing.expectEqual(frame.Type.data, (try frame.Header.read(&in)).type); try testing.expectEqual(frame.Type.settings, (try frame.Header.read(&in)).type); try testing.expectEqual(frame.Type.headers, (try frame.Header.read(&in)).type); } test "an outbox that fills is a connection that has stopped listening" { var buffer: [4096]u8 = undefined; var out: Io.Writer = .fixed(&buffer); var s: Serializer = .init(testing.io, &out); _ = try s.acquire(); defer s.release(); var sent: usize = 0; while (sent < outbox_len / frame.header_len) : (sent += 1) { try s.sendControl(.{ .length = 0, .type = .ping, .flags = 0x01, .stream_id = 0 }, &.{}); } try testing.expectError(error.OutboxFull, s.sendControl( .{ .length = 0, .type = .ping, .flags = 0x01, .stream_id = 0 }, &.{}, )); } test "a failed write is remembered rather than rediscovered" { // A writer with no room at all: the first frame fails and every later // attempt is refused without touching it again. var out: Io.Writer = .fixed(&.{}); var s: Serializer = .init(testing.io, &out); try testing.expectError(error.WriteFailed, s.send( .{ .length = 0, .type = .settings, .flags = 0, .stream_id = 0 }, &.{}, )); try testing.expect(s.failed.load(.acquire)); try testing.expectError(error.WriteFailed, s.send( .{ .length = 0, .type = .settings, .flags = 0, .stream_id = 0 }, &.{}, )); try testing.expectError(error.WriteFailed, s.sendControl( .{ .length = 0, .type = .settings, .flags = 0, .stream_id = 0 }, &.{}, )); }