// 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 takes the mutex if it is free and otherwise //! leaves the frame in a small buffer that whoever next holds the mutex //! flushes first. That turns "the reader is stuck behind the writer" into //! "control frames are a little late", which is survivable. //! //! 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, /// 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, }; pub fn init(io: Io, out: *Io.Writer) Serializer { return .{ .io = io, .out = out }; } /// Takes the lock, flushes anything the outbox is holding, and hands back a /// writer to put a frame on. The caller must `release` 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; } /// 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. pub fn release(s: *Serializer) void { s.out.flush() catch s.fail(); s.mutex.unlock(s.io); } /// One complete frame, under one hold. 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(); } /// A control frame that must not block. /// /// Sent immediately if the lock is free; otherwise left for whoever holds it. pub fn sendControl(s: *Serializer, header: frame.Header, payload: []const u8) (Error || OutboxError)!void { if (s.failed.load(.acquire)) return error.WriteFailed; if (s.mutex.tryLock()) { defer s.release(); s.drainOutbox() catch |err| return err; header.writeTo(s.out) catch return s.failWrite(); s.out.writeAll(payload) catch return s.failWrite(); return; } 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; } /// GOAWAY, which takes the blocking path on purpose. 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(); } /// Must be called with `mutex` held. fn drainOutbox(s: *Serializer) Error!void { s.outbox_mutex.lockUncancelable(s.io); defer s.outbox_mutex.unlock(s.io); if (s.outbox_used == 0) return; s.out.writeAll(s.outbox[0..s.outbox_used]) catch return s.failWrite(); s.outbox_used = 0; } 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 }, &.{}); 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 }, &.{}, )); }