// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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(.{})); }