tiny.http.ClientResponseStorage

1/// Storage provides reusable response slots cut from memory sized by caller2/// limits. Sizing with zero storage bytes skips allocation entirely, while3/// non-zero requirements allocate a single contiguous block up front. That4/// allocation is partitioned into three sequential regions: all header entries5/// for all slots, followed by all head bytes, and finally all body bytes. Each6/// slot draws its corresponding slices from each of these three regions.7///8/// Calling `activate` ends the initialization phase, after which `response`9/// hands out a slot's scratch slices. Handing out a slot invokes no allocator.10/// Specifying an index at or beyond the configured slot count returns11/// `error.ClientResponseCapacityExceeded`.12///13/// A response parsed into a slot borrows that slot directly. The backing14/// storage must remain alive and unchanged while the response is in use, with15/// slot reuse for another parse and calling `deinit` serving as explicit16/// invalidation points.17pub const Storage = struct {18    phase: alloc_phase.capacity.Phase,19    capacity: model.Capacity,20    bytes: []align(@alignOf(Header)) u8,2122    pub const Limits: type = model.Limits;23    pub const Capacity: type = model.Capacity;24    pub const Exhaustion: type = StorageExhaustion;25    pub const InitError = std.mem.Allocator.Error || error{CapacityOverflow};2627    pub const claim: alloc_phase.capacity.Declaration = .{28        .source = .{29            .id = "http.client_response_storage",30            .kind = .phase_static,31            .limit_source = .caller,32            .storage = .{33                .covered = &.{34                    .{35                        .id = "fixed_parsed_client_response_header_entries_for_eve_451da7e2df60",36                        .lifetime = .steady,37                        .detail = "fixed parsed client-response header entries for every response slot",38                    },39                    .{40                        .id = "fixed_response_head_bytes_retaining_borrowed_header_27c2e730fc7e",41                        .lifetime = .steady,42                        .detail = "fixed response-head bytes retaining borrowed header names and values",43                    },44                    .{45                        .id = "fixed_buffered_or_decoded_response_body_bytes",46                        .lifetime = .steady,47                        .detail = "fixed buffered or decoded response-body bytes",48                    },49                },50                .excluded = &.{51                    "request serialization, URL targets, TLS state, certificate bundles, sockets, and kernel queues",52                    "streaming response header accumulation, chunk fragmentation, and handler-owned output",53                },54            },55            .capacity = .{56                .inputs = &.{57                    alloc_phase.capacity.bindInput(Limits, "response_count", "response_count"),58                    alloc_phase.capacity.bindInput(Limits, "header_count_per_response", "header_count_per_response"),59                    alloc_phase.capacity.bindInput(Limits, "head_bytes_per_response", "head_bytes_per_response"),60                    alloc_phase.capacity.bindInput(Limits, "body_bytes_per_response", "body_bytes_per_response"),61                },62                .type_selectors = &.{63                    alloc_phase.capacity.bindType(Header, "header"),64                },65                .nodes = &.{66                    .{ .input = 0 },67                    .{ .input = 1 },68                    .{ .product = .{ .left = 0, .right = 1 } },69                    .{ .constant = 1 },70                    .{ .scale = .{ .node = 3, .coefficient = .{ .size_of_concrete_type = 0 } } },71                    .{ .product = .{ .left = 2, .right = 4 } },72                    .{ .input = 2 },73                    .{ .product = .{ .left = 0, .right = 6 } },74                    .{ .input = 3 },75                    .{ .product = .{ .left = 0, .right = 8 } },76                    .{ .add = .{ .left = 5, .right = 7 } },77                    .{ .add = .{ .left = 10, .right = 9 } },78                },79                .assertions = &.{.{80                    .scope = .closure_total,81                    .measure = .retained,82                    .relation = .exact,83                    .expression = 11,84                }},85            },86            .overload = .{87                .kind = .terminal,88                .detail = "direct parse rejects atomically; a network response exceeding its slot terminates that one-shot connection without publishing a response",89            },90            .risks = .{91                .transitive = .{92                    .status = .witnessed,93                    .detail = "response parsing and chunk decoding allocate no storage after activation",94                },95                .foreign = .{96                    .status = .excluded,97                    .detail = "network reads may discover remote overflow after bounded scratch mutation but never publish an over-capacity response",98                },99            },100            .obligations = &.{101                .{ .key = "http_client_response_capacity", .role = .capacity_model },102                .{ .key = "http_client_response_oom_retry", .role = .custom },103                .{ .key = "http_client_response_partition", .role = .custom },104                .{ .key = "http_client_response_sealed", .role = .transitive_risk },105                .{ .key = "http_client_response_atomic", .role = .overload },106                .{ .key = "http_client_response_boundary", .role = .custom },107                .{ .key = "http_client_response_network_overload", .role = .overload },108                .{ .key = "http_client_response_network_foreign_risk", .role = .foreign_risk },109            },110        },111        .bindings = .{112            .owner = @This(),113            .seal = .{114                .family = alloc_phase.capacity.selector(@This().activate),115                .premise = .{116                    .class = .checked_semantic_fact,117                    .authority = .checker,118                },119            },120            .teardown = .{121                .family = alloc_phase.capacity.selector(@This().deinit),122                .premise = .{123                    .class = .checked_semantic_fact,124                    .authority = .checker,125                },126            },127        },128    };129130    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {131        const capacity = try Capacity.derive(limits);132        const bytes = if (capacity.storage_bytes == 0)133            @as([]align(@alignOf(Header)) u8, &.{})134        else135            try allocator.alignedAlloc(u8, .of(Header), capacity.storage_bytes);136        return .{137            .phase = .initialization,138            .capacity = capacity,139            .bytes = bytes,140        };141    }142143    pub fn activate(self: *Storage) void {144        std.debug.assert(self.phase == .initialization);145        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);146        self.phase = .steady;147    }148149    pub fn response(self: *Storage, index: usize) Exhaustion!Scratch {150        std.debug.assert(self.phase == .steady);151        if (index >= self.capacity.response_count) {152            return error.ClientResponseCapacityExceeded;153        }154        const all_headers = std.mem.bytesAsSlice(155            Header,156            self.bytes[0..self.capacity.header_bytes],157        );158        const header_start = index * self.capacity.header_count_per_response;159        const head_start = self.capacity.header_bytes +160            index * self.capacity.head_bytes_per_response;161        const body_region_start = self.capacity.header_bytes + self.capacity.head_bytes;162        const body_start = body_region_start + index * self.capacity.body_bytes_per_response;163        return .{164            .headers = all_headers[header_start..][0..self.capacity.header_count_per_response],165            .head = self.bytes[head_start..][0..self.capacity.head_bytes_per_response],166            .body = self.bytes[body_start..][0..self.capacity.body_bytes_per_response],167        };168    }169170    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {171        std.debug.assert(self.phase != .teardown);172        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);173        self.phase = .teardown;174        if (self.bytes.len != 0) allocator.free(self.bytes);175        self.bytes = &.{};176    }177};

1pub const ClientResponseStorage = client.ResponseStorage;