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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253// 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 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 }, &.{}, ));}