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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! The six settings RFC 9113 §6.5.2 defines, the rules about their values,//! and the seventh that RFC 8441 adds.//!//! A struct of named fields rather than an array of sixteen-bit identifiers,//! because most of them are read on nearly every frame and the rest are//! read once.
const std = @import("std");
const frame = @import("frame.zig");const Writer = std.Io.Writer;
const Settings = @This();
/// The initial values of §6.5.2 are the field defaults, so `Settings{}` is/// exactly what both endpoints are required to assume before any SETTINGS/// frame has arrived.header_table_size: u32 = 4096,enable_push: bool = true,/// "Initially, there is no limit to this value", which is what null is.max_concurrent_streams: ?u32 = null,initial_window_size: u31 = 65535,max_frame_size: u24 = 16384,max_header_list_size: ?u32 = null,/// `SETTINGS_ENABLE_CONNECT_PROTOCOL`, RFC 8441 §3. Its initial value is 0,/// which is what makes the extended CONNECT of that document something a/// client may only use after being told it is available.enable_connect_protocol: bool = false,
pub const Id = enum(u16) { header_table_size = 0x01, enable_push = 0x02, max_concurrent_streams = 0x03, initial_window_size = 0x04, max_frame_size = 0x05, max_header_list_size = 0x06, /// RFC 8441 §9.1, which is a registration in RFC 9113's registry rather /// than a setting of RFC 9113's own. enable_connect_protocol = 0x08, /// §6.5.2: "An endpoint that receives a SETTINGS frame with any unknown /// or unsupported identifier MUST ignore that setting." _,};
pub const Entry = struct { id: Id, value: u32 };
/// The smallest and largest `SETTINGS_MAX_FRAME_SIZE` §6.5.2 allows.pub const min_max_frame_size: u24 = 16384;pub const max_max_frame_size: u24 = (1 << 24) - 1;
/// The largest flow-control window §6.9.1 allows.pub const max_window_size: u32 = (1 << 31) - 1;
/// Walks a SETTINGS payload six octets at a time.////// `frame.checkHeader` has already established that the length is a multiple/// of six, which is what lets a payload of any size be applied without ever/// being buffered whole: a peer sending ten thousand settings costs time and/// nothing else.pub const Iterator = struct { rest: []const u8,
/// The next entry, or null once fewer than six octets are left. Unknown /// identifiers are returned like any other, for `apply` to ignore; a /// trailing fragment shorter than six octets is dropped without comment, /// which `frame.checkHeader` has already made impossible. pub fn next(it: *Iterator) ?Entry { if (it.rest.len < 6) return null; defer it.rest = it.rest[6..]; return .{ .id = @fromBackingInt(@intCast(std.mem.readInt(u16, it.rest[0..2], .big))), .value = std.mem.readInt(u32, it.rest[2..6], .big), }; }
test next { var it = iterate(&.{ 0x00, 0x05, 0x00, 0x00, 0x40, 0x00 }); // MAX_FRAME_SIZE = 16384 const e = it.next().?; try testing.expectEqual(Id.max_frame_size, e.id); try testing.expectEqual(@as(u32, 16384), e.value); try testing.expect(it.next() == null); }};
/// An iterator over a SETTINGS payload, which borrows `payload` rather than/// copying it.pub fn iterate(payload: []const u8) Iterator { return .{ .rest = payload };}
test iterate { var peer: Settings = .{}; var it = iterate(&.{ 0x00, 0x03, 0x00, 0x00, 0x00, 0x64, // MAX_CONCURRENT_STREAMS = 100 0x00, 0x02, 0x00, 0x00, 0x00, 0x00, // ENABLE_PUSH = 0 }); while (it.next()) |e| try peer.apply(e); try testing.expectEqual(@as(?u32, 100), peer.max_concurrent_streams); try testing.expect(!peer.enable_push);}
pub const ApplyError = error{ /// `ENABLE_PUSH` was neither 0 nor 1, or `MAX_FRAME_SIZE` was outside /// the range §6.5.2 gives it. Protocol, /// `INITIAL_WINDOW_SIZE` above 2^31-1, which §6.5.2 singles out as /// FLOW_CONTROL_ERROR — the one setting whose out-of-range value is not /// a protocol error. FlowControl,};
/// Exhaustive, so a new member cannot be added without deciding what the peer/// is told.pub fn errorCode(err: ApplyError) frame.ErrorCode { return switch (err) { error.Protocol => .protocol_error, error.FlowControl => .flow_control_error, };}
test errorCode { try testing.expectEqual(frame.ErrorCode.protocol_error, errorCode(error.Protocol)); try testing.expectEqual(frame.ErrorCode.flow_control_error, errorCode(error.FlowControl));}
/// Takes one entry from a peer's SETTINGS frame. An out-of-range value is/// refused and leaves `s` as it was; an identifier this does not know is/// ignored, as §6.5.2 requires. Either error is a connection error, with the/// code `errorCode` gives.pub fn apply(s: *Settings, e: Entry) ApplyError!void { switch (e.id) { .header_table_size => s.header_table_size = e.value, .enable_push => switch (e.value) { 0 => s.enable_push = false, 1 => s.enable_push = true, // §6.5.2: "Any value other than 0 or 1 MUST be treated as a // connection error of type PROTOCOL_ERROR." else => return error.Protocol, }, .max_concurrent_streams => s.max_concurrent_streams = e.value, .initial_window_size => { if (e.value > max_window_size) return error.FlowControl; s.initial_window_size = @intCast(e.value); }, .max_frame_size => { if (e.value < min_max_frame_size or e.value > max_max_frame_size) { return error.Protocol; } s.max_frame_size = @intCast(e.value); }, .max_header_list_size => s.max_header_list_size = e.value, .enable_connect_protocol => switch (e.value) { 0 => s.enable_connect_protocol = false, 1 => s.enable_connect_protocol = true, // RFC 8441 §3: "The value of the parameter MUST be 0 or 1." else => return error.Protocol, }, // Ignored, per §6.5.2. Not an error, and not something to remember. _ => {}, }}
test apply { var peer: Settings = .{}; try peer.apply(.{ .id = .initial_window_size, .value = 1 << 20 }); try testing.expectEqual(@as(u31, 1 << 20), peer.initial_window_size); // Below §6.5.2's floor, refused, and nothing changed. try testing.expectError(error.Protocol, peer.apply(.{ .id = .max_frame_size, .value = 100 })); try testing.expectEqual(@as(u24, 16384), peer.max_frame_size);}
/// Writes the settings that differ from `previous`, which for a first/// SETTINGS frame (`previous` of `.{}`) means the ones that differ from the/// initial values. Only the payload: the frame header, with `payloadLen` as/// its length, is the caller's.////// A SETTINGS frame that restates a default is legal and wasteful; there is/// no reason to spend six octets telling a peer something it already assumed.////// A limit that changes back to null is not written, because the protocol has/// no value for "no limit": the peer goes on holding the old one.pub fn writePayload(s: Settings, out: *Writer, previous: Settings) Writer.Error!void { if (s.header_table_size != previous.header_table_size) { try writeEntry(out, .header_table_size, s.header_table_size); } if (s.enable_push != previous.enable_push) { try writeEntry(out, .enable_push, @intFromBool(s.enable_push)); } if (s.max_concurrent_streams != previous.max_concurrent_streams) { if (s.max_concurrent_streams) |n| try writeEntry(out, .max_concurrent_streams, n); } if (s.initial_window_size != previous.initial_window_size) { try writeEntry(out, .initial_window_size, s.initial_window_size); } if (s.max_frame_size != previous.max_frame_size) { try writeEntry(out, .max_frame_size, s.max_frame_size); } if (s.max_header_list_size != previous.max_header_list_size) { if (s.max_header_list_size) |n| try writeEntry(out, .max_header_list_size, n); } if (s.enable_connect_protocol != previous.enable_connect_protocol) { try writeEntry(out, .enable_connect_protocol, @intFromBool(s.enable_connect_protocol)); }}
test writePayload { var buffer: [32]u8 = undefined; var out: Writer = .fixed(&buffer); const ours: Settings = .{ .enable_push = false }; try ours.writePayload(&out, .{}); // One entry, the only one that differs from the initial values. try testing.expectEqualSlices(u8, &.{ 0x00, 0x02, 0x00, 0x00, 0x00, 0x00 }, out.buffered());}
/// How many octets `writePayload` will write, which the frame header has to/// say before the payload goes out.pub fn payloadLen(s: Settings, previous: Settings) u24 { var count: u24 = 0; if (s.header_table_size != previous.header_table_size) count += 1; if (s.enable_push != previous.enable_push) count += 1; if (s.max_concurrent_streams != previous.max_concurrent_streams and s.max_concurrent_streams != null) count += 1; if (s.initial_window_size != previous.initial_window_size) count += 1; if (s.max_frame_size != previous.max_frame_size) count += 1; if (s.max_header_list_size != previous.max_header_list_size and s.max_header_list_size != null) count += 1; if (s.enable_connect_protocol != previous.enable_connect_protocol) count += 1; return count * 6;}
test payloadLen { const ours: Settings = .{ .max_concurrent_streams = 100, .enable_connect_protocol = true }; try testing.expectEqual(@as(u24, 12), ours.payloadLen(.{})); // Against itself there is nothing to say. try testing.expectEqual(@as(u24, 0), ours.payloadLen(ours));}
fn writeEntry(out: *Writer, id: Id, value: u32) Writer.Error!void { var bytes: [6]u8 = undefined; std.mem.writeInt(u16, bytes[0..2], @backingInt(id), .big); std.mem.writeInt(u32, bytes[2..6], value, .big); try out.writeAll(&bytes);}
const testing = std.testing;
test "the defaults are the initial values of RFC 9113 6.5.2" { const s: Settings = .{}; try testing.expectEqual(@as(u32, 4096), s.header_table_size); try testing.expect(s.enable_push); try testing.expect(s.max_concurrent_streams == null); try testing.expectEqual(@as(u31, 65535), s.initial_window_size); try testing.expectEqual(@as(u24, 16384), s.max_frame_size); try testing.expect(s.max_header_list_size == null);}
test "each setting's range" { var s: Settings = .{};
try s.apply(.{ .id = .enable_push, .value = 0 }); try testing.expect(!s.enable_push); try s.apply(.{ .id = .enable_push, .value = 1 }); try testing.expect(s.enable_push); try testing.expectError(error.Protocol, s.apply(.{ .id = .enable_push, .value = 2 }));
try testing.expectError(error.FlowControl, s.apply(.{ .id = .initial_window_size, .value = max_window_size + 1, })); try s.apply(.{ .id = .initial_window_size, .value = max_window_size }); try testing.expectEqual(@as(u31, max_window_size), s.initial_window_size);
try testing.expectError(error.Protocol, s.apply(.{ .id = .max_frame_size, .value = 16383 })); try testing.expectError(error.Protocol, s.apply(.{ .id = .max_frame_size, .value = 1 << 24 })); try s.apply(.{ .id = .max_frame_size, .value = 16384 }); try s.apply(.{ .id = .max_frame_size, .value = max_max_frame_size });
// Unknown identifiers are ignored rather than refused. try s.apply(.{ .id = @fromBackingInt(@intCast(0x99)), .value = 0xdeadbeef });}
test "a payload is walked six octets at a time" { var it = iterate(&.{ 0x00, 0x03, 0x00, 0x00, 0x00, 0x64, // MAX_CONCURRENT_STREAMS = 100 0x00, 0x04, 0x00, 0x01, 0x00, 0x00, // INITIAL_WINDOW_SIZE = 65536 }); const first = it.next().?; try testing.expectEqual(Id.max_concurrent_streams, first.id); try testing.expectEqual(@as(u32, 100), first.value); const second = it.next().?; try testing.expectEqual(Id.initial_window_size, second.id); try testing.expectEqual(@as(u32, 65536), second.value); try testing.expect(it.next() == null);}
test "only what changed is written, and it reads back the same" { var buffer: [128]u8 = undefined; var w: Writer = .fixed(&buffer);
const ours: Settings = .{ .max_concurrent_streams = 100, .initial_window_size = 1 << 20, .enable_push = false, }; try testing.expectEqual(@as(u24, 18), ours.payloadLen(.{})); try ours.writePayload(&w, .{}); try testing.expectEqual(@as(usize, 18), w.end);
var back: Settings = .{}; var it = iterate(buffer[0..w.end]); while (it.next()) |e| try back.apply(e); try testing.expectEqual(ours.max_concurrent_streams, back.max_concurrent_streams); try testing.expectEqual(ours.initial_window_size, back.initial_window_size); try testing.expectEqual(ours.enable_push, back.enable_push); // And the ones that did not change were not sent, so they are still the // initial values. try testing.expectEqual(@as(u24, 16384), back.max_frame_size);
// Nothing to say is nothing written. w = .fixed(&buffer); try (Settings{}).writePayload(&w, .{}); try testing.expectEqual(@as(usize, 0), w.end); try testing.expectEqual(@as(u24, 0), (Settings{}).payloadLen(.{}));}