Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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 }, &.{}, ));}