tiny.zen.SitePageStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    bytes: []u8,5    in_use: bool = false,6    loaded_page_bytes: usize = 0,7    high_water_page_bytes: usize = 0,8    rejected_page_count: u64 = 0,910    pub const Limits: type = capacity_mod.Limits;11    pub const Capacity: type = capacity_mod.Capacity;12    pub const Exhaustion: type = model.Exhaustion;13    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;1415    pub const claim: alloc_phase.capacity.Declaration = .{16        .source = .{17            .id = "zen.site_page_storage",18            .kind = .phase_static,19            .limit_source = .caller,20            .storage = .{21                .covered = &.{22                    .{23                        .id = "one_reusable_surveyed_markdown_page_plus_overload_lookahead_byte",24                        .lifetime = .steady,25                        .detail = "one reusable surveyed Markdown page plus overload lookahead byte",26                    },27                },28                .excluded = &.{29                    "caller-owned page paths, source directory capability, and kernel file state",30                    "frontmatter, retained site catalog, rendered page, theme, asset, and filesystem output owners",31                },32            },33            .capacity = .{34                .inputs = &.{35                    alloc_phase.capacity.bindInput(Limits, "max_page_bytes", "max_page_bytes"),36                },37                .type_selectors = &.{},38                .nodes = &.{39                    .{ .input = 0 },40                    .{ .constant = 1 },41                    .{ .add = .{ .left = 0, .right = 1 } },42                },43                .assertions = &.{.{44                    .scope = .closure_total,45                    .measure = .retained,46                    .relation = .exact,47                    .expression = 2,48                }},49            },50            .overload = .{51                .kind = .drop,52                .detail = "an oversized or concurrently grown page is rejected before parser mutation and the reusable input region remains available",53            },54            .risks = .{55                .transitive = .{56                    .status = .witnessed,57                    .detail = "activated page acquisition uses only the preacquired byte region and consumers release every borrow before reuse",58                },59                .foreign = .{60                    .status = .excluded,61                    .detail = "directory reads and kernel file state remain effects outside the reusable page input owner",62                },63            },64            .obligations = &.{65                .{ .key = "zen_site_page_capacity", .role = .capacity_model },66                .{ .key = "zen_site_page_acquisition", .role = .custom },67                .{ .key = "zen_site_page_oom", .role = .custom },68                .{ .key = "zen_site_page_boundaries", .role = .overload },69                .{ .key = "zen_site_page_growth", .role = .overload },70                .{ .key = "zen_site_page_reuse", .role = .custom },71                .{ .key = "zen_site_page_sealed", .role = .transitive_risk },72                .{ .key = "zen_site_page_root", .role = .custom },73                .{ .key = "zen_site_page_consumer_transitive_risk", .role = .transitive_risk },74                .{ .key = "zen_site_page_consumer_foreign_risk", .role = .foreign_risk },75            },76        },77        .bindings = .{78            .owner = @This(),79            .seal = .{80                .family = alloc_phase.capacity.selector(@This().activate),81                .premise = .{82                    .class = .checked_semantic_fact,83                    .authority = .checker,84                },85            },86            .teardown = .{87                .family = alloc_phase.capacity.selector(@This().deinit),88                .premise = .{89                    .class = .checked_semantic_fact,90                    .authority = .checker,91                },92            },93        },94    };9596    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {97        const capacity = try Capacity.derive(limits);98        const bytes = try allocator.alloc(u8, capacity.storage_bytes);99        return .{100            .phase = .initialization,101            .capacity = capacity,102            .bytes = bytes,103        };104    }105106    pub fn activate(self: *Storage) void {107        std.debug.assert(self.phase == .initialization);108        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);109        std.debug.assert(self.bytes.len > self.capacity.page_bytes);110        self.phase = .steady;111    }112113    pub fn readFile(114        self: *Storage,115        directory: std.Io.Dir,116        io: std.Io,117        relative_path: []const u8,118    ) ![]const u8 {119        try self.requireAvailable();120        const page = directory.readFile(io, relative_path, self.bytes) catch |err| switch (err) {121            error.FileTooBig => return self.reject(),122            else => return err,123        };124        return try self.admit(page.len);125    }126127    pub fn release(self: *Storage) void {128        std.debug.assert(self.phase == .steady);129        std.debug.assert(self.in_use);130        self.in_use = false;131        self.loaded_page_bytes = 0;132    }133134    pub fn status(self: *const Storage) Status {135        return .{136            .phase = self.phase,137            .in_use = self.in_use,138            .storage_bytes = self.capacity.storage_bytes,139            .max_page_bytes = self.capacity.page_bytes,140            .loaded_page_bytes = self.loaded_page_bytes,141            .high_water_page_bytes = self.high_water_page_bytes,142            .rejected_page_count = self.rejected_page_count,143        };144    }145146    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {147        std.debug.assert(self.phase != .teardown);148        std.debug.assert(!self.in_use);149        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);150        self.phase = .teardown;151        allocator.free(self.bytes);152        self.bytes = &.{};153        self.loaded_page_bytes = 0;154    }155156    fn requireAvailable(self: *Storage) Exhaustion!void {157        std.debug.assert(self.phase == .steady);158        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);159        std.debug.assert(self.loaded_page_bytes <= self.capacity.page_bytes);160        if (self.in_use) return error.SitePageStorageInUse;161        std.debug.assert(self.loaded_page_bytes == 0);162    }163164    fn admit(self: *Storage, page_bytes: usize) Exhaustion![]const u8 {165        std.debug.assert(self.phase == .steady);166        std.debug.assert(!self.in_use);167        std.debug.assert(page_bytes <= self.capacity.storage_bytes);168        if (page_bytes > self.capacity.page_bytes) return self.reject();169        self.in_use = true;170        self.loaded_page_bytes = page_bytes;171        self.high_water_page_bytes = @max(self.high_water_page_bytes, page_bytes);172        return self.bytes[0..page_bytes];173    }174175    fn reject(self: *Storage) Exhaustion {176        std.debug.assert(self.phase == .steady);177        std.debug.assert(!self.in_use);178        std.debug.assert(self.loaded_page_bytes == 0);179        self.rejected_page_count +|= 1;180        return error.SitePageCapacityExceeded;181    }182};

1/// Reusable caller-allocated buffer for one surveyed Markdown page.2pub const SitePageStorage = site_page.Storage;