//! The framed, append-only, content-addressed log over the `StorageFile`
//! capability. One file: a 64-byte header followed by 8-byte-aligned
//! frames, each self-verifying via a header checksum (over the fixed
//! fields) plus a whole-frame checksum (over header+payload). The header
//! checksum is what makes torn-vs-corrupt discrimination exact and
//! size-independent: without it, a torn write (a clean prefix, safe to
//! truncate) and a corrupted length field (unsafe to trust) both read as
//! "not enough of a frame," and nothing short of decoding payload bytes
//! that may not exist could tell them apart.
//!
//! No RFC section behind this file: native storage-engine design. The
//! oracle is this file's own framing invariants, checked by
//! sim/storage_sweep.zig's DST sweep: every acknowledged put stays
//! readable and hash-verifies; a torn tail truncates to exactly the last
//! complete frame; the index rebuilt on open matches the write-time
//! model; and corruption always surfaces as an error, never as silently
//! wrong bytes.
//!
//! A second, narrower checksum guards the frame's fixed 6-byte prefix
//! (`len|flags|hash_len`) on its own, in a 10-byte window whose size
//! never depends on `hash_len`. Without it, scanning a frame whose
//! `hash_len` byte is itself the bitflipped one has no way to know how
//! many bytes the rest of the header needs before it can check the
//! header checksum -- a corrupted `hash_len` that happens to demand more
//! bytes than the file has left reads exactly like a torn tail. The
//! prefix checksum removes that ambiguity: `hash_len` is proven correct
//! (or rejected outright) from a fixed-size read, before it is ever used
//! to size anything else.
const std = @import("std");
const storage = @import("zit_storage");
const delta = @import("zit").delta;
const flate = std.compress.flate;
/// Local artifact id: dense, 1-based, assigned in intern/put order. 0 is
/// never issued (mirrors repostate.zig's MemStore).
pub const Rid = u64;
/// FILE header size: magic(4) | version u16(2) | hash_kind u8(1) |
/// reserved(53) | crc32(4).
pub const header_len: u64 = 64;
/// Explicit payload bound: keeps a single frame's read/decode work
/// bounded no matter how large a check-in gets.
pub const max_payload: u64 = 1 << 30;
pub const max_hash_len: u8 = 32;
pub const min_hash_len: u8 = 1;
/// Every frame's on-disk span is a multiple of this.
pub const frame_align: u64 = 8;
/// Frozen on-disk format version — the `.zit` ship-format identity. A reader
/// accepts only this exact stored version and rejects any other, older
/// included (`validateHeader`): the writer emits exactly this value, so a
/// header carrying anything else is not a zit-written file. An unknown frame
/// flag-kind is likewise a clean reject, never UB (`scanOneFrame`). Bumped
/// only on a layout change — a copied `.zit` file is a complete,
/// self-verifying repository, so this field is what absorbs any future layout
/// evolution; widening to a compatibility range belongs to that change, not
/// to a version this reader has never produced.
pub const version: u16 = 1;
/// Smallest possible frame span: hash_len=1, payload=0 ->
/// align8(26+1+0) = 32.
const min_frame: u64 = 32;
/// Explicit upper bound on delta-chain resolution: a `content()` on a
/// delta frame walks at most this many `delta_of` hops before rejecting
/// the chain as corrupt. Caps read recursion and read-amplification;
/// generous versus the short chains a real store produces.
pub const max_delta_chain: u8 = 32;
/// The deepest delta chain `putArtifact` will CREATE (write policy), kept
/// strictly below the READ bound `max_delta_chain` so a retained foreign
/// chain (a peer with no write cap) still has headroom to resolve. A base
/// already at this depth is stored full, so a locally-produced chain never
/// exceeds this and `content()`'s read walk stays shallow.
pub const delta_chain_write_max: u8 = 16;
/// A delta is "materially smaller" — worth storing as a delta rather than a
/// full container — when its raw length is under 90% of the full artifact:
/// `raw_delta.len * den < bytes.len * num`. Integer math, no float; the raw
/// length is the cheap proxy for the eventual container sizes.
const delta_profit_num: u64 = 9;
const delta_profit_den: u64 = 10;
const magic = "zitL";
/// Payload encoding. `raw` = uncompressed bytes; `zlib` = a fossil zlib
/// container (4-byte BE uncompressed length + RFC1950 stream, sync §4.1);
/// `delta` = a zlib-contained delta whose `delta_of` is the byte offset of
/// the base frame, so resolving a chain link costs one seek and never a
/// second index lookup; `config` = a distinguished singleton repo-config
/// record, NOT content-addressed and never interned. Any other flag byte
/// is an unknown kind and rejected on open. The
/// content hash always names the UNCOMPRESSED, fully-reconstructed bytes, so
/// encoding never affects naming (sync §4.1 L1206-1208).
pub const FrameKind = enum(u8) { raw = 0, zlib = 1, delta = 2, config = 3, _ };
/// Repo-local config: default-branch name, project id, the sync project
/// code (§9.1 `projectcode`, the repository's shared identity — distinct
/// from `project_id`), and an opaque hash-policy byte the storage layer
/// round-trips but never interprets (exactly like the header's
/// `hash_kind`). It has a home IN the file as one distinguished `config`
/// frame; "last config frame wins" is derived by scan order, reusing the
/// log's own append-prefix property.
pub const max_config_str: usize = 255;
/// Fixed config record bound: `[hash_policy u8][branch_len u16][branch]
/// [pid_len u16][pid][pcode_len u16][pcode][login_len u16][login]
/// [secret_len u16][secret]` — five length-prefixed strings after the policy
/// byte (the last two, sync §6.3, are the stored login credential).
pub const max_config_payload: usize = 1 + 5 * (2 + max_config_str); // = 1286
/// A config frame is never keyed by hash — it is found only via
/// `config_offset`, never through `index`/`lookup` — so its 1-byte embedded
/// hash is inert bookkeeping (`appendFrame` requires some hash). It is never
/// an index key and never compared.
const config_sentinel: []const u8 = "\x00";
/// One repo config. Both slices borrow a backing buffer (`OwnedConfig`);
/// `hash_policy` is opaque to storage.
pub const Config = struct {
hash_policy: u8,
default_branch: []const u8,
project_id: []const u8,
/// sync §9.1 — the repository's shared project code (`projectcode`,
/// an artifact-hash-shaped identifier). Empty on a repo that predates
/// it; `init` generates one and a clone adopts the origin's. Defaulted
/// so existing construction sites need not restate it.
project_code: []const u8 = "",
/// sync §6.3 — the login name a `zit push` authenticates as, or empty
/// when no credential is stored. Paired with `login_secret_hex`.
login_user: []const u8 = "",
/// sync §6.3/DECISION-3 — the 40-hex derived shared secret
/// (`SHA1(project-code "/" login "/" password)`), NOT the plaintext
/// password: it is all a signer needs (§6.4) and is scoped to this
/// repo+login. Empty when no credential is stored; exactly 40 bytes
/// otherwise. Persisted only under 0600 file permissions by the caller.
login_secret_hex: []const u8 = "",
};
/// A `readConfig` result: the owned frame payload plus a `Config` whose
/// slices point into it. Mirrors `OwnedConfig`'s owned-backing shape.
pub const OwnedConfig = struct {
backing: []u8,
config: Config,
pub fn deinit(self: *OwnedConfig, gpa: std.mem.Allocator) void {
gpa.free(self.backing);
self.* = undefined;
}
};
pub const OpenError = error{ OutOfMemory, Storage, Corrupt };
/// No read happens on the write path, so `Corrupt` can't occur here —
/// advertising it would be dead mechanism.
pub const PutError = error{ OutOfMemory, Storage };
/// A phantom is purely in-memory bookkeeping: no I/O, so no `Storage`.
pub const InternError = error{OutOfMemory};
pub const ContentError = error{ OutOfMemory, Storage, Corrupt };
pub const CommitError = error{Storage};
/// The framed, content-addressed log. `open` rebuilds `entries`/`index`
/// from the file each time — there is no persistent side index yet.
/// O(n) on open is correct at this scale; a persistent, regenerable
/// sidecar is a noted future extension, built only if a benchmark shows
/// open time missing its target at large artifact counts.
pub const LogStore = struct {
gpa: std.mem.Allocator,
file: storage.StorageFile,
hash_kind: u8,
/// Structural end of the log: header + every complete frame written so
/// far. Always a multiple of `frame_align`.
end: u64,
entries: std.ArrayList(Entry) = .empty,
index: std.StringHashMapUnmanaged(Rid) = .empty,
/// Byte offset of the live (latest in scan order) config frame, or null
/// when the log carries none. Config is found ONLY through this — never
/// via `index`/`entries` (§E).
config_offset: ?u64 = null,
/// Set when a rollback truncate fails and `end` can no longer be proven
/// equal to the file's physical end. Every append refuses to run while it
/// is set, so a later frame never lands at a diverged offset (the storage
/// invariant: offset bookkeeping equals the file end). One-way: a store
/// only ever goes healthy -> poisoned, never back.
poisoned: bool = false,
/// Set once `openReadOnly` has scanned and whole-frame-CRC-verified every
/// complete frame in the file (and proven `end == file_size`, so no writer
/// can extend it). While set, `readFrameAt` trusts that verification and
/// skips the redundant per-read whole-frame CRC — a read-only verb must not
/// CRC the entire log a second time after open already did. Every frame's
/// CRC is thus verified exactly once (at scan), never zero times: the header
/// prefix/header CRCs still run on every read, and a short payload read is
/// still corruption. The append path (`open`) leaves this false, so writes
/// and post-write reads keep full at-use verification.
verified_on_open: bool = false,
const Entry = struct {
/// Owned duplicate; also the index's key (stable across `entries`
/// reallocation since it's a separate heap allocation).
hash: []u8,
/// Frame start offset. Meaningless while `phantom`.
offset: u64,
/// On-disk (container/wire) payload length: raw bytes for `raw`,
/// the zlib-container length for `zlib`/`delta`.
payload_len: u32,
/// Payload encoding of this frame. `.raw` while `phantom` (no frame).
kind: FrameKind,
/// A phantom was `intern`ed but never `put`: no frame on disk.
phantom: bool,
/// Delta-chain depth: 0 for a phantom or a non-delta frame; one more
/// than the base's depth for a `.delta` frame. Set at `insert`/`scan`
/// and read by `putArtifact` to enforce `delta_chain_write_max`, so a
/// locally-created chain never grows past the write cap.
depth: u8 = 0,
};
/// Opens for append, creating or repairing the file when necessary, and
/// rebuilds the in-memory index by scanning every complete frame.
pub fn open(gpa: std.mem.Allocator, file: storage.StorageFile, hash_kind: u8) OpenError!LogStore {
const file_size = file.size() catch return error.Storage;
var self: LogStore = .{ .gpa = gpa, .file = file, .hash_kind = hash_kind, .end = header_len };
errdefer self.deinit(gpa);
if (file_size == 0) {
try writeHeader(file, hash_kind);
std.debug.assert(self.end % frame_align == 0);
return self;
}
if (file_size < header_len) {
// Torn header: nothing before byte `header_len` can be trusted
// as a frame boundary either, so start clean.
file.truncate(0) catch return error.Storage;
try writeHeader(file, hash_kind);
std.debug.assert(self.end % frame_align == 0);
return self;
}
self.hash_kind = try validateHeader(file);
try scan(&self, true);
std.debug.assert(self.end % frame_align == 0);
return self;
}
/// Opens an existing log strictly for reads. Unlike `open`, this path never
/// creates, rewrites, or truncates storage: an empty file, torn header, or
/// torn frame tail is corruption. Complete-frame checksum and encoding
/// faults are rejected by the same scanner used by the append path.
pub fn openReadOnly(gpa: std.mem.Allocator, file: storage.StorageFile) OpenError!LogStore {
const file_size = file.size() catch return error.Storage;
if (file_size < header_len) return error.Corrupt;
var self: LogStore = .{ .gpa = gpa, .file = file, .hash_kind = 0, .end = header_len };
errdefer self.deinit(gpa);
self.hash_kind = try validateHeader(file);
try scan(&self, false);
std.debug.assert(self.end == file_size);
std.debug.assert(self.end % frame_align == 0);
// scan() whole-frame-CRC-verified every frame and proved end == file
// size; reads may now skip the redundant per-frame CRC (see the field).
self.verified_on_open = true;
return self;
}
pub fn deinit(self: *LogStore, gpa: std.mem.Allocator) void {
for (self.entries.items) |e| gpa.free(e.hash);
self.entries.deinit(gpa);
self.index.deinit(gpa);
self.* = undefined;
}
/// Clone = copy + derive: byte-copies `source` into `dest`, then opens
/// `dest` — rebuilding the index and recovering
/// config with no network (no network capability is even in scope here).
/// The result is an independent, equal repository: same artifact set, same
/// config, byte-identical log. A damaged copy needs no clone-specific
/// error — `open`'s torn-tail truncation drops exactly the incomplete
/// tail, so the copy degrades gracefully through the shared derive path.
/// Precondition (documented, not asserted — assertions carry no I/O):
/// `dest` is empty. `hash_kind` is a don't-care: `dest` is non-empty after
/// the copy, so `open` reads the copied header's stored kind.
pub fn cloneInto(
gpa: std.mem.Allocator,
source: storage.StorageFile,
dest: storage.StorageFile,
) OpenError!LogStore {
const src_size = source.size() catch return error.Storage;
var chunk: [64 * 1024]u8 = undefined;
var copied: u64 = 0;
// Bounded: `copied` rises by `n > 0` every pass, so the loop runs at
// most ceil(src_size / chunk.len) times before `copied == src_size`.
while (copied < src_size) {
const n = source.pread(copied, &chunk) catch return error.Storage;
// A 0-count before EOF on a stable file is a device failure, not a
// boundary — return rather than spin (no unbounded loop).
if (n == 0) return error.Storage;
dest.append(chunk[0..n]) catch return error.Storage;
copied += n;
}
std.debug.assert(copied == src_size);
return open(gpa, dest, 0);
}
/// Resolves `hash` to its rid, creating a phantom (no I/O) when
/// unknown. Phantoms never reach disk.
pub fn intern(self: *LogStore, hash: []const u8) InternError!Rid {
std.debug.assert(hash.len >= min_hash_len and hash.len <= max_hash_len);
if (self.index.get(hash)) |rid| return rid;
try self.entries.ensureUnusedCapacity(self.gpa, 1);
const owned = try self.gpa.dupe(u8, hash);
errdefer self.gpa.free(owned);
const rid: Rid = self.entries.items.len + 1;
try self.index.put(self.gpa, owned, rid);
self.entries.appendAssumeCapacity(.{ .hash = owned, .offset = 0, .payload_len = 0, .kind = .raw, .phantom = true });
return rid;
}
/// Stores `bytes` verbatim (a `raw` frame) under `hash`. Idempotent for
/// an already-content-bearing hash (returns the existing rid, appends
/// nothing); upgrades a phantom in place.
pub fn put(self: *LogStore, hash: []const u8, bytes: []const u8) PutError!Rid {
std.debug.assert(bytes.len <= max_payload);
return self.insert(hash, bytes, .raw, 0, 0);
}
/// Store `bytes` under `hash`, delta-encoded against `base` when the delta
/// is materially smaller (`< 90%` of the full artifact) AND the base's
/// chain depth leaves room under `delta_chain_write_max`, else as a §4.1
/// zlib container. `base` is a HINT, never a requirement: a null,
/// phantom, config, unreadable, over-deep, or unprofitable base all
/// silently store the full form — there is no error path for an ineligible
/// base, only a compactness difference. Idempotent + phantom-upgrade like
/// `put`/`putZlib`: an already content-bearing `hash` keeps its stored
/// form and no encode work runs. This one method hides the whole storage
/// policy so callers pass only the base hint they naturally hold.
pub fn putArtifact(self: *LogStore, hash: []const u8, bytes: []const u8, base: ?Rid) PutError!Rid {
std.debug.assert(hash.len >= min_hash_len and hash.len <= max_hash_len);
std.debug.assert(bytes.len <= max_payload);
// Idempotent: return before any encode work when the artifact is held.
if (self.index.get(hash)) |rid| {
if (!self.entries.items[@intCast(rid - 1)].phantom) return rid;
}
if (base) |base_rid| {
std.debug.assert(base_rid >= 1 and base_rid <= self.entries.items.len);
const base_entry = self.entries.items[@intCast(base_rid - 1)];
// Eligible base: a committed content frame (never a phantom or the
// config singleton) whose chain still has write-cap headroom.
const eligible = !base_entry.phantom and base_entry.kind != .config and
base_entry.depth < delta_chain_write_max;
if (eligible) {
if (try self.tryDelta(hash, bytes, base_rid)) |rid| return rid;
}
}
return self.putZlib(hash, bytes);
}
/// Attempt to store `bytes` as a delta against `base_rid`. Returns the new
/// rid when the delta is stored (profitable), or null when the caller
/// should fall back to the full form (unreadable base, unencodable, or an
/// unprofitable delta). Only `OutOfMemory`/`Storage` escape as errors.
fn tryDelta(self: *LogStore, hash: []const u8, bytes: []const u8, base_rid: Rid) PutError!?Rid {
const base_bytes = self.content(self.gpa, base_rid) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.Storage => return error.Storage,
error.Corrupt => return null, // an unreadable base is not a delta basis; store full
} orelse return null; // a phantom base carries no content; store full
defer self.gpa.free(base_bytes);
const raw_delta = delta.create(self.gpa, base_bytes, bytes) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.TargetTooLarge => return null, // too large to encode; store full
};
defer self.gpa.free(raw_delta);
// "Materially smaller": raw_delta.len < 90% of the full artifact.
if (@as(u64, raw_delta.len) * delta_profit_den >= @as(u64, bytes.len) * delta_profit_num) {
return null; // unprofitable; store full
}
return try self.putDelta(hash, base_rid, raw_delta);
}
/// Stores `bytes` compressed into a fossil zlib container (§4.1, default
/// level) under `hash`. The hash still names the UNCOMPRESSED bytes, so
/// storage compression never changes an artifact's address (§4.1
/// L1206-1208). Idempotent + phantom-upgrade like `put`.
pub fn putZlib(self: *LogStore, hash: []const u8, bytes: []const u8) PutError!Rid {
std.debug.assert(bytes.len <= max_payload);
const container = try containerEncode(self.gpa, bytes);
defer self.gpa.free(container);
return self.insert(hash, container, .zlib, 0, 0);
}
/// Stores `raw_delta` (a delta reconstructing this artifact from the frame
/// at `base_rid`) as a zlib-contained `delta` frame; `delta_of` records
/// the base frame's byte offset. The stored container IS the wire payload
/// a `cfile` serves verbatim (§7.2). Idempotent + phantom-upgrade like
/// `put`.
pub fn putDelta(self: *LogStore, hash: []const u8, base_rid: Rid, raw_delta: []const u8) PutError!Rid {
std.debug.assert(base_rid >= 1 and base_rid <= self.entries.items.len);
const base = &self.entries.items[@intCast(base_rid - 1)];
std.debug.assert(!base.phantom);
std.debug.assert(base.offset >= header_len and base.offset < self.end);
std.debug.assert(raw_delta.len >= 1 and raw_delta.len <= max_payload);
const base_off = base.offset;
// Bookkeeping only: the WRITE cap is `putArtifact`'s job (it refuses a
// base at `delta_chain_write_max`). `putDelta` itself is the low-level
// primitive and stays permissive — a caller may build a chain past the
// READ bound to prove `content()` rejects it. Saturating so depth never
// wraps on a pathologically deep foreign chain.
const depth: u8 = base.depth +| 1;
const container = try containerEncode(self.gpa, raw_delta);
defer self.gpa.free(container);
return self.insert(hash, container, .delta, base_off, depth);
}
/// Shared insert core: append one frame carrying `payload` under `hash`
/// with encoding `kind` (and `delta_of` for `.delta`), then update the
/// index. Idempotent for an already-content-bearing hash; upgrades a
/// phantom in place. On a bookkeeping failure after the frame landed, the
/// file is truncated back so disk and memory stay in lockstep; a rollback
/// truncate that itself fails poisons the store.
fn insert(self: *LogStore, hash: []const u8, payload: []const u8, kind: FrameKind, delta_of: u64, depth: u8) PutError!Rid {
std.debug.assert(hash.len >= min_hash_len and hash.len <= max_hash_len);
std.debug.assert(payload.len <= max_payload);
std.debug.assert((depth == 0) == (kind != .delta)); // depth is delta-only
if (self.index.get(hash)) |rid| {
const entry = &self.entries.items[@intCast(rid - 1)];
if (!entry.phantom) return rid;
const res = try self.appendFrame(hash, payload, kind, delta_of);
entry.offset = res.offset;
entry.payload_len = res.len;
entry.kind = kind;
entry.phantom = false;
entry.depth = depth;
return rid;
}
try self.entries.ensureUnusedCapacity(self.gpa, 1);
const owned = try self.gpa.dupe(u8, hash);
errdefer self.gpa.free(owned);
const res = try self.appendFrame(hash, payload, kind, delta_of);
const rid: Rid = self.entries.items.len + 1;
self.index.put(self.gpa, owned, rid) catch |e| {
// Frame already landed on disk but bookkeeping failed: undo the
// write so the file matches in-memory state exactly. If the
// rollback truncate itself fails, `end` and the file end diverge
// and no later append can be trusted — poison the store.
self.file.truncate(res.offset) catch {
self.poisoned = true;
};
self.end = res.offset;
return e;
};
self.entries.appendAssumeCapacity(.{ .hash = owned, .offset = res.offset, .payload_len = res.len, .kind = kind, .phantom = false, .depth = depth });
return rid;
}
/// The payload encoding of `rid` (`.raw` for a phantom). Lets a serve
/// loop pick a full-content versus delta cfile without a frame read.
pub fn kindOf(self: *const LogStore, rid: Rid) FrameKind {
std.debug.assert(rid >= 1 and rid <= self.entries.items.len);
return self.entries.items[@intCast(rid - 1)].kind;
}
/// The on-disk (container/wire) payload length of `rid`; 0 for a phantom.
/// Symmetric with `hashOf`; the DST sweep uses it to bound the crc-covered
/// span of a frame whose uncompressed content differs in length.
pub fn payloadLenOf(self: *const LogStore, rid: Rid) u32 {
std.debug.assert(rid >= 1 and rid <= self.entries.items.len);
return self.entries.items[@intCast(rid - 1)].payload_len;
}
/// The delta-chain depth of the entry whose frame starts at `offset`, for
/// recovering a delta's depth during the open-time scan. Entries are
/// appended in ascending offset order there (real frames only, no
/// phantoms), so a binary search resolves the base with no auxiliary map.
/// Returns 0 when no entry starts at `offset` (a dangling `delta_of` that
/// `content()` rejects). Precondition: `entries` is offset-sorted — true
/// only mid-`scan`, which is this method's sole caller.
fn depthForBaseOffset(self: *const LogStore, offset: u64) u8 {
const items = self.entries.items;
var lo: usize = 0;
var hi: usize = items.len;
while (lo < hi) {
const mid = lo + (hi - lo) / 2;
const o = items[mid].offset;
if (o == offset) return items[mid].depth;
if (o < offset) lo = mid + 1 else hi = mid;
}
return 0;
}
/// Owned uncompressed bytes for a rid, or null while it's a phantom.
/// Re-reads and re-verifies the frame (both checksums, embedded hash) on
/// every call, then decodes by kind: `raw` copied out, `zlib` inflated,
/// `delta` resolved by walking `delta_of` and applying via `delta.apply`.
/// Never trusts a stale scan result.
pub fn content(self: *LogStore, gpa: std.mem.Allocator, rid: Rid) ContentError!?[]u8 {
std.debug.assert(rid >= 1 and rid <= self.entries.items.len);
const entry = &self.entries.items[@intCast(rid - 1)];
if (entry.phantom) return null;
return try self.contentAtOffset(gpa, entry.offset, max_delta_chain, entry.hash, null);
}
/// Like `content`, but resolves delta bases through `cache` — a bounded
/// plaintext memo the caller owns for the span of one derivation sweep. A
/// full sweep over delta chains would otherwise re-reconstruct each base
/// once per referencing delta (the k(k+1)/2 read-amplification the plan
/// projects at ~8.5x on depth-16 chains); memoizing a base's plaintext on
/// first use makes every later reference a lookup, so each frame is fully
/// reconstructed at most about twice regardless of chain depth. A `.delta`
/// frame's own plaintext is also memoized so a deeper delta built on it
/// hits; `.raw`/`.zlib` top-level results are never inserted, so an
/// all-raw repository pays zero cache overhead. Identical bytes to
/// `content(rid)`; the cache changes only the work, never the answer.
pub fn contentCached(self: *LogStore, gpa: std.mem.Allocator, rid: Rid, cache: *PlaintextCache) ContentError!?[]u8 {
std.debug.assert(rid >= 1 and rid <= self.entries.items.len);
const entry = &self.entries.items[@intCast(rid - 1)];
if (entry.phantom) return null;
const bytes = try self.contentAtOffset(gpa, entry.offset, max_delta_chain, entry.hash, cache);
// Keep a resolved delta's plaintext hot for any deeper delta that names
// this frame as its base; raw/zlib top-level frames are left uncached so
// a delta-free sweep never dups a byte. Best-effort: a failed insert
// just means no memo, never a wrong or missing answer.
if (entry.kind == .delta) cache.put(gpa, entry.offset, bytes) catch {};
return bytes;
}
/// Reconstructs the uncompressed content of the frame at `offset`.
/// `depth_remaining` bounds delta recursion: each `delta` hop consumes
/// one, and a delta reached at zero is `error.Corrupt` (never unbounded
/// recursion). `expect_hash`, when non-null, requires the frame's embedded
/// hash to match (the top-level integrity check); recursion into a base
/// passes null since a base carries its own name. `cache`, when non-null,
/// memoizes delta-base plaintext (see `contentCached`).
fn contentAtOffset(self: *LogStore, gpa: std.mem.Allocator, offset: u64, depth_remaining: u8, expect_hash: ?[]const u8, cache: ?*PlaintextCache) ContentError![]u8 {
std.debug.assert(depth_remaining <= max_delta_chain);
const fv = try self.readFrameAt(gpa, offset);
if (expect_hash) |eh| {
if (!std.mem.eql(u8, fv.hash[0..fv.hash_len], eh)) {
gpa.free(fv.payload);
return error.Corrupt;
}
}
switch (fv.kind) {
.raw => return fv.payload, // ownership transfers to the caller
.zlib => {
defer gpa.free(fv.payload);
return containerDecode(gpa, fv.payload, max_payload);
},
.delta => {
defer gpa.free(fv.payload);
if (depth_remaining == 0) return error.Corrupt;
// A base must be an earlier, in-range frame: a forward or
// self reference is corruption, and a mid-frame/garbage
// offset fails `readFrameAt`'s checksums below.
if (fv.delta_of < header_len or fv.delta_of >= offset) return error.Corrupt;
const raw_delta = try containerDecode(gpa, fv.payload, max_payload);
defer gpa.free(raw_delta);
// A memoized base: apply against the borrowed plaintext, never
// re-reading or re-reconstructing the base frame this sweep.
if (cache) |c| {
if (c.get(fv.delta_of)) |hit| {
return delta.apply(gpa, hit, raw_delta) catch |e| switch (e) {
error.OutOfMemory => error.OutOfMemory,
error.MalformedDelta, error.ChecksumMismatch => error.Corrupt,
};
}
}
const base = try self.contentAtOffset(gpa, fv.delta_of, depth_remaining - 1, null, cache);
defer gpa.free(base);
// A base is referenced by at least this delta, so memoize it.
if (cache) |c| c.put(gpa, fv.delta_of, base) catch {};
return delta.apply(gpa, base, raw_delta) catch |e| switch (e) {
error.OutOfMemory => error.OutOfMemory,
error.MalformedDelta, error.ChecksumMismatch => error.Corrupt,
};
},
.config => {
// A delta base (or content lookup) resolving to a config
// frame is corruption: config is not content-addressed and
// never a base (§E).
gpa.free(fv.payload);
return error.Corrupt;
},
_ => unreachable, // readFrameAt rejects any flag byte outside {raw,zlib,delta,config}
}
}
/// One fully validated frame read from `offset`: kind, `delta_of`, the
/// embedded hash, and the owned on-disk payload (raw bytes, or the zlib
/// container for `zlib`/`delta`). Caller owns `payload`.
const FrameView = struct {
kind: FrameKind,
delta_of: u64,
hash: [max_hash_len]u8,
hash_len: u8,
payload: []u8,
};
/// Reads and checksum-verifies the frame at `offset`, returning its
/// decoded fields and owned payload. Shares the fixed-header validation
/// (`readFrameHeader`) with the open-time scanner; unlike the scanner, a
/// short read here is `error.Corrupt` — the frame was known to exist, so
/// missing bytes mean the file lied or lost data, not a torn tail to
/// recover. Any flag byte outside {raw,zlib,delta,config} is rejected.
fn readFrameAt(self: *LogStore, gpa: std.mem.Allocator, offset: u64) ContentError!FrameView {
const fh = switch (try readFrameHeader(self.file, offset)) {
.torn => return error.Corrupt,
.header => |h| h,
};
const pl: usize = fh.payload_len;
if (pl > max_payload) return error.Corrupt; // wire-derived bound before allocation
const payload = try gpa.alloc(u8, pl);
errdefer gpa.free(payload);
const payload_offset: u64 = offset + fh.fixed_and_crc_len;
const npay = self.file.pread(payload_offset, payload) catch return error.Storage;
if (npay < pl) return error.Corrupt;
// Whole-frame CRC: skipped only when `openReadOnly` already verified
// every frame at scan time (the file is proven immutable-length there).
// The header prefix/header CRCs in `readFrameHeader` always run, so a
// frame is never read wholly unchecked; a short payload read above is
// still corruption regardless.
if (!self.verified_on_open) {
var trailer: [4]u8 = undefined;
const nt = self.file.pread(payload_offset + pl, &trailer) catch return error.Storage;
if (nt < 4) return error.Corrupt;
var fcrc = std.hash.Crc32.init();
fcrc.update(fh.header_bytes[0..fh.fixed_and_crc_len]);
fcrc.update(payload);
if (fcrc.final() != std.mem.readInt(u32, &trailer, .little)) return error.Corrupt;
}
return .{
.kind = fh.kind,
.delta_of = fh.delta_of,
.hash = fh.hash,
.hash_len = fh.hash_len,
.payload = payload,
};
}
/// A stored artifact's cfile wire payload (sync §7.2), served verbatim.
/// Two forms, matching the two stored container kinds:
/// * `full` — a §4.1 zlib container of the whole artifact; USIZE is its
/// own 4-byte big-endian prefix (`writeCfileVerbatim`).
/// * `delta` — a §4.1 zlib container of a [FossilDelta], plus the base
/// artifact's hash (DELTASRC) and the reconstructed-target size read
/// from the delta header (delta §3.2). USIZE is that `target_size` —
/// NEVER the container's 4-byte prefix, which is the raw delta's length
/// (sync §7.2 L1142-1144: "in delta form it is not delta size").
/// `deinit` frees the owned `container` in either arm.
pub const Wire = union(enum) {
full: []u8,
delta: Delta,
pub const Delta = struct {
container: []u8,
base_hash_buf: [max_hash_len]u8,
base_hash_len: u8,
/// delta §3.2 — the reconstructed target length; the cfile USIZE.
target_size: u64,
pub fn baseHash(self: *const Delta) []const u8 {
return self.base_hash_buf[0..self.base_hash_len];
}
};
pub fn container(self: *const Wire) []const u8 {
return switch (self.*) {
.full => |c| c,
.delta => |d| d.container,
};
}
pub fn deinit(self: *Wire, gpa: std.mem.Allocator) void {
switch (self.*) {
.full => |c| gpa.free(c),
.delta => |d| gpa.free(d.container),
}
self.* = undefined;
}
};
/// The stored cfile payload for `rid` served verbatim (sync §4.1/§7.2), or
/// null when the frame holds no stored container: a `.raw` frame or a
/// phantom (the serve loop then falls back to compressing `content()`). A
/// `.zlib` frame yields the `full` arm; a `.delta` frame yields the `delta`
/// arm, carrying the base hash (read from the base frame) and the target
/// size (read from the delta header — one small inflate). The stored
/// container IS the wire payload (normative §4.1/§7.2), so this exposes no
/// representation the RFC does not already fix. Caller owns the `Wire`.
pub fn wire(self: *LogStore, gpa: std.mem.Allocator, rid: Rid) ContentError!?Wire {
std.debug.assert(rid >= 1 and rid <= self.entries.items.len);
const entry = &self.entries.items[@intCast(rid - 1)];
if (entry.phantom) return null;
switch (entry.kind) {
.raw => return null,
.zlib => {
const fv = try self.readFrameAt(gpa, entry.offset);
std.debug.assert(fv.kind == .zlib);
return .{ .full = fv.payload };
},
.delta => {
const fv = try self.readFrameAt(gpa, entry.offset);
errdefer gpa.free(fv.payload);
std.debug.assert(fv.kind == .delta);
// Structural phantom safety (D3): a stored delta's base ALWAYS
// precedes it in the log; a forward/self reference is corruption.
if (fv.delta_of < header_len or fv.delta_of >= entry.offset) return error.Corrupt;
// The reconstructed-target size (the §7.2 USIZE) comes from the
// delta's own header, not the container prefix (that is the raw
// delta length). One small inflate reads it without applying a
// single segment.
const raw_delta = try containerDecode(gpa, fv.payload, max_payload);
defer gpa.free(raw_delta);
const target_size = delta.targetSize(raw_delta) catch return error.Corrupt;
// The base frame's own header carries its hash; reading it also
// checksum-validates that `delta_of` still points at a real frame.
const base = try self.readFrameAt(gpa, fv.delta_of);
gpa.free(base.payload);
var out: Wire = .{ .delta = .{
.container = fv.payload,
.base_hash_buf = undefined,
.base_hash_len = base.hash_len,
.target_size = target_size,
} };
@memcpy(out.delta.base_hash_buf[0..base.hash_len], base.hash[0..base.hash_len]);
return out;
},
// A config frame is never an artifact rid (never interned), so it
// never reaches here; any other kind is rejected on open.
.config, _ => unreachable,
}
}
/// Borrows the hash naming `rid`. Every rid, phantom or not, has one.
pub fn hashOf(self: *const LogStore, rid: Rid) []const u8 {
std.debug.assert(rid >= 1 and rid <= self.entries.items.len);
return self.entries.items[@intCast(rid - 1)].hash;
}
/// Returns caller-owned non-phantom artifact RIDs in the order their
/// frames were persisted. Dense RID order is deliberately not used:
/// `intern` may create a phantom before a later `put` writes its frame.
pub fn ridsInPersistedOrder(self: *const LogStore, gpa: std.mem.Allocator) error{OutOfMemory}![]Rid {
var count: usize = 0;
for (self.entries.items) |entry| {
if (!entry.phantom) count += 1;
}
const rids = try gpa.alloc(Rid, count);
count = 0;
for (self.entries.items, 0..) |entry, i| {
if (entry.phantom) continue;
rids[count] = @intCast(i + 1);
count += 1;
}
std.mem.sort(Rid, rids, self, ridOffsetLessThan);
return rids;
}
fn ridOffsetLessThan(self: *const LogStore, a: Rid, b: Rid) bool {
return self.entries.items[@intCast(a - 1)].offset < self.entries.items[@intCast(b - 1)].offset;
}
pub fn lookup(self: *const LogStore, hash: []const u8) ?Rid {
return self.index.get(hash);
}
pub fn commit(self: *LogStore) CommitError!void {
self.file.sync() catch return error.Storage;
}
/// Appends a new config frame and makes it the live config (§E). Latest
/// wins by scan order, so an edit is one append — no rewrite, no mutable
/// pointer. On a torn append `appendFrame` rolls the file back and
/// `config_offset` is left untouched, so failure leaves the prior config
/// live.
pub fn putConfig(self: *LogStore, cfg: Config) PutError!void {
std.debug.assert(cfg.default_branch.len <= max_config_str);
std.debug.assert(cfg.project_id.len <= max_config_str);
std.debug.assert(cfg.project_code.len <= max_config_str);
std.debug.assert(cfg.login_user.len <= max_config_str);
std.debug.assert(cfg.login_secret_hex.len <= max_config_str);
// sync §6.3 — a stored secret is either absent or the full 40-hex
// derived value; no other width is ever persisted.
std.debug.assert(cfg.login_secret_hex.len == 0 or cfg.login_secret_hex.len == 40);
var buf: [max_config_payload]u8 = undefined;
const payload = encodeConfig(&buf, cfg);
const res = try self.appendFrame(config_sentinel, payload, .config, 0);
std.debug.assert(res.offset + payload.len < self.end); // frame landed before the new end
self.config_offset = res.offset;
}
/// The live config, or null when the log carries none (§E: absent config
/// means the caller — CLI/repostate — owns the default; storage bakes
/// none). Re-reads and re-verifies the frame on every call. Caller owns
/// the returned `OwnedConfig`.
pub fn readConfig(self: *LogStore, gpa: std.mem.Allocator) ContentError!?OwnedConfig {
const off = self.config_offset orelse return null;
const fv = try self.readFrameAt(gpa, off);
errdefer gpa.free(fv.payload);
if (fv.kind != .config) return error.Corrupt;
const parsed = try parseConfig(fv.payload);
return .{ .backing = fv.payload, .config = parsed };
}
/// Structural end of the log (header + every complete frame written so
/// far), for callers that track write progress without duplicating
/// frame-layout arithmetic (e.g. the DST sweep's crash-recovery model).
pub fn size(self: *const LogStore) u64 {
return self.end;
}
const AppendResult = struct { offset: u64, len: u32 };
/// Encodes one frame and appends it in a single `StorageFile.append`
/// call — one call is one atomic torn-write draw point, matching the
/// crash simulator's fault granularity. On failure, truncates back to
/// the prior structural end so a partial write never lingers; if that
/// rollback truncate itself fails the store is poisoned and refuses every
/// later append.
fn appendFrame(self: *LogStore, hash: []const u8, bytes: []const u8, kind: FrameKind, delta_of: u64) PutError!AppendResult {
if (self.poisoned) return error.Storage;
// A read-only store proved every frame's whole-frame CRC at scan time and
// reads skip the redundant re-CRC; appending here would add a frame that
// never gets that check. The append path always opens via `open`.
std.debug.assert(!self.verified_on_open);
const hl: u64 = hash.len;
const pl: u64 = bytes.len;
const frame_len = alignUp8(u64, 26 + hl + pl);
std.debug.assert(frame_len <= max_payload + 64);
const frame = try self.gpa.alloc(u8, @intCast(frame_len));
defer self.gpa.free(frame);
_ = encodeFrame(frame, hash, bytes, @intFromEnum(kind), delta_of);
const offset = self.end;
if (self.file.append(frame)) |_| {
self.end += frame_len;
std.debug.assert(self.end % frame_align == 0);
return .{ .offset = offset, .len = @intCast(pl) };
} else |_| {
// A torn append may have left a prefix; if the rollback truncate
// can't remove it, `end` no longer matches the file end — poison.
self.file.truncate(self.end) catch {
self.poisoned = true;
};
return error.Storage;
}
}
};
/// A bounded plaintext memo for a single derivation sweep: base frame offset to
/// its reconstructed plaintext. Owned by the sweep caller (repoview.load), not
/// by the store — see `LogStore.contentCached`. Explicitly bounded on BOTH a
/// byte budget and an entry count; an insert that would exceed either evicts
/// least-recently-used entries first, and a single item larger than the whole
/// byte budget is simply never cached (the budget never grows). No unbounded
/// allocation and no unbounded memoization — deleting the cache can only change
/// speed, never any answer.
pub const PlaintextCache = struct {
/// Default resident-byte budget: comfortably holds a delta family's hot
/// bases without letting the memo grow without limit.
pub const default_max_bytes: usize = 64 << 20;
/// Default hard cap on resident entries, bounding per-entry metadata even
/// under many tiny items.
pub const default_max_entries: usize = 4096;
const Node = struct { bytes: []u8, last_used: u64 };
map: std.AutoHashMapUnmanaged(u64, Node) = .empty,
bytes_used: usize = 0,
/// Resident plaintext never exceeds this many bytes (fixed for a cache's
/// lifetime; the field form lets a test drive eviction with a small budget).
max_bytes: usize = default_max_bytes,
/// Resident entry count never exceeds this.
max_entries: usize = default_max_entries,
/// Monotonic recency clock; the entry with the smallest stamp is the LRU
/// victim. u64 never wraps within a single sweep's insert/lookup count.
tick: u64 = 0,
pub fn init() PlaintextCache {
return .{};
}
pub fn deinit(self: *PlaintextCache, gpa: std.mem.Allocator) void {
var it = self.map.valueIterator();
while (it.next()) |n| gpa.free(n.bytes);
self.map.deinit(gpa);
self.* = undefined;
}
/// The memoized plaintext for `offset`, or null; bumps its LRU recency.
/// The returned slice is borrowed and valid until the next `put`/`deinit`.
pub fn get(self: *PlaintextCache, offset: u64) ?[]const u8 {
const n = self.map.getPtr(offset) orelse return null;
self.tick += 1;
n.last_used = self.tick;
return n.bytes;
}
/// Memoize a private copy of `src` under `offset`, evicting LRU entries to
/// stay within both bounds. A no-op when `offset` is already resident (base
/// offsets are unique keys) or when `src` alone exceeds the byte budget.
/// Only `error.OutOfMemory` escapes.
pub fn put(self: *PlaintextCache, gpa: std.mem.Allocator, offset: u64, src: []const u8) error{OutOfMemory}!void {
if (self.map.contains(offset)) return;
if (src.len > self.max_bytes) return; // never grow the budget for one item
// Evict until the newcomer fits under both caps (bounded by the
// resident count — each pass removes exactly one entry).
while (self.bytes_used + src.len > self.max_bytes or @as(usize, self.map.count()) >= self.max_entries) {
if (!self.evictOne(gpa)) break; // nothing left to evict
}
if (self.bytes_used + src.len > self.max_bytes) return; // still over: skip
const owned = try gpa.dupe(u8, src);
errdefer gpa.free(owned);
self.tick += 1;
try self.map.put(gpa, offset, .{ .bytes = owned, .last_used = self.tick });
self.bytes_used += owned.len;
}
/// Evict the least-recently-used entry; false when the map is empty.
fn evictOne(self: *PlaintextCache, gpa: std.mem.Allocator) bool {
var victim_key: ?u64 = null;
var victim_tick: u64 = std.math.maxInt(u64);
var victim_len: usize = 0;
var it = self.map.iterator();
while (it.next()) |e| {
if (e.value_ptr.last_used < victim_tick) {
victim_tick = e.value_ptr.last_used;
victim_key = e.key_ptr.*;
victim_len = e.value_ptr.bytes.len;
}
}
const k = victim_key orelse return false;
const n = self.map.getPtr(k).?;
gpa.free(n.bytes);
_ = self.map.remove(k);
std.debug.assert(self.bytes_used >= victim_len);
self.bytes_used -= victim_len;
return true;
}
};
fn writeHeader(file: storage.StorageFile, hash_kind: u8) OpenError!void {
var buf: [header_len]u8 = [_]u8{0} ** header_len;
@memcpy(buf[0..4], magic);
std.mem.writeInt(u16, buf[4..6], version, .little);
buf[6] = hash_kind;
var crc = std.hash.Crc32.init();
crc.update(buf[0..60]);
std.mem.writeInt(u32, buf[60..64], crc.final(), .little);
file.append(&buf) catch return error.Storage;
}
/// Returns the stored `hash_kind` on success. Rejects: bad magic, a stored
/// version other than this reader's, or a header crc mismatch.
fn validateHeader(file: storage.StorageFile) OpenError!u8 {
var buf: [header_len]u8 = undefined;
const n = file.pread(0, &buf) catch return error.Storage;
if (n < header_len) return error.Corrupt;
if (!std.mem.eql(u8, buf[0..4], magic)) return error.Corrupt;
const stored_version = std.mem.readInt(u16, buf[4..6], .little);
if (stored_version != version) return error.Corrupt;
const stored_crc = std.mem.readInt(u32, buf[60..64], .little);
var crc = std.hash.Crc32.init();
crc.update(buf[0..60]);
if (crc.final() != stored_crc) return error.Corrupt;
return buf[6];
}
/// Outcome of reading one frame at a scan offset: either a torn tail (the
/// file ends mid-frame — truncate and stop) or a validated frame.
const ScanOutcome = union(enum) {
torn,
frame: struct { hash: [max_hash_len]u8, hash_len: u8, frame_len: u64, payload_len: u32, kind: FrameKind, delta_of: u64 },
};
/// Fixed prefix window: len(4)|flags(1)|hash_len(1)|prefix_crc32(4). Its
/// size does not depend on `hash_len` — that is what lets `hash_len` be
/// proven correct (or rejected) before it is used to size anything else.
const prefix_len: usize = 10;
/// A frame's fully validated fixed header — everything before the payload.
/// The payload and its whole-frame crc are the caller's concern: the
/// content reader allocates and returns the payload, the open-time scanner
/// streams it for the crc without allocating.
const FrameHeader = struct {
payload_len: u32,
kind: FrameKind,
delta_of: u64,
hash: [max_hash_len]u8,
hash_len: u8,
/// Span of prefix+hash+delta_of+header_crc, i.e. the payload's offset
/// relative to the frame start; the whole-frame crc is seeded over
/// exactly this many bytes of `header_bytes`.
fixed_and_crc_len: usize,
/// The verified header bytes, so the caller seeds the whole-frame crc
/// without re-reading them.
header_bytes: [22 + max_hash_len]u8,
};
/// Either a torn tail (a short read on the prefix or header window) or a
/// validated fixed header.
const HeaderScan = union(enum) {
torn,
header: FrameHeader,
};
/// Reads and checksum-verifies a frame's fixed header at `offset`, shared by
/// the content reader (`readFrameAt`) and the open-time scanner
/// (`scanOneFrame`). Two-stage: first the fixed-size prefix window
/// (hash_len-independent, so a short read there is unambiguously a torn write
/// — nothing about its size can be thrown off by corruption), which proves
/// `hash_len` trustworthy via its own crc; only then is `hash_len` used to
/// size the rest of the header read, at which point the same "short read =
/// torn, checksum fails = corrupt" reasoning applies validly (append() only
/// ever writes one frame per call and a torn write is a clean prefix — never
/// damaged bytes; a full window whose checksum fails can only be a bitflip on
/// already-landed bytes). A short read on either window is `.torn`; the
/// callers decide its disposition (the scanner recovers, the content reader
/// treats it as `error.Corrupt`). Any flag byte outside
/// {raw,zlib,delta,config} is rejected.
fn readFrameHeader(file: storage.StorageFile, offset: u64) error{ Corrupt, Storage }!HeaderScan {
var prefix: [prefix_len]u8 = undefined;
const n0 = file.pread(offset, &prefix) catch return error.Storage;
if (n0 < prefix_len) return .torn;
const payload_len = std.mem.readInt(u32, prefix[0..4], .little);
const flags = prefix[4];
const hash_len = prefix[5];
if (hash_len < min_hash_len or hash_len > max_hash_len) return error.Corrupt;
var pcrc = std.hash.Crc32.init();
pcrc.update(prefix[0..6]);
if (pcrc.final() != std.mem.readInt(u32, prefix[6..][0..4], .little)) return error.Corrupt;
// A prefix-verified flag byte is trustworthy (a torn write is a clean
// truncation, never damaged bytes), so any kind outside
// {raw,zlib,delta,config} is a genuine unknown-kind frame, rejected — not
// a torn tail.
if (flags > @intFromEnum(FrameKind.config)) return error.Corrupt;
const hl: usize = hash_len;
const fixed_and_crc_len: usize = 22 + hl;
var hbuf: [22 + max_hash_len]u8 = undefined;
const n1 = file.pread(offset, hbuf[0..fixed_and_crc_len]) catch return error.Storage;
if (n1 < fixed_and_crc_len) return .torn;
var hcrc = std.hash.Crc32.init();
hcrc.update(hbuf[0 .. 18 + hl]);
if (hcrc.final() != std.mem.readInt(u32, hbuf[18 + hl ..][0..4], .little)) return error.Corrupt;
var fh: FrameHeader = .{
.payload_len = payload_len,
.kind = @enumFromInt(flags),
.delta_of = std.mem.readInt(u64, hbuf[10 + hl ..][0..8], .little),
.hash = undefined,
.hash_len = hash_len,
.fixed_and_crc_len = fixed_and_crc_len,
.header_bytes = undefined,
};
@memcpy(fh.hash[0..hl], hbuf[10..][0..hl]);
@memcpy(fh.header_bytes[0..fixed_and_crc_len], hbuf[0..fixed_and_crc_len]);
return .{ .header = fh };
}
/// Reads and validates exactly one frame at `offset`, for the open-time scan.
/// Delegates the fixed-header validation to `readFrameHeader`; a torn header,
/// a frame that would run past `total`, or a torn payload/trailer all report
/// `.torn` (recoverable tail), while a failed whole-frame crc is
/// `error.Corrupt`. The payload is streamed through the crc in bounded chunks
/// so a large frame never forces a full-payload allocation.
fn scanOneFrame(file: storage.StorageFile, offset: u64, total: u64) OpenError!ScanOutcome {
const fh = switch (try readFrameHeader(file, offset)) {
.torn => return .torn,
.header => |h| h,
};
const frame_len = alignUp8(u64, 26 + @as(u64, fh.hash_len) + fh.payload_len);
if (offset + frame_len > total) return .torn;
var crc = std.hash.Crc32.init();
crc.update(fh.header_bytes[0..fh.fixed_and_crc_len]);
var remaining: u64 = fh.payload_len;
var pos = offset + @as(u64, fh.fixed_and_crc_len);
var chunk: [4096]u8 = undefined;
while (remaining > 0) {
const take: usize = @intCast(@min(remaining, @as(u64, chunk.len)));
const got = file.pread(pos, chunk[0..take]) catch return error.Storage;
if (got < take) return .torn;
crc.update(chunk[0..take]);
pos += take;
remaining -= take;
}
var trailer: [4]u8 = undefined;
const nt = file.pread(pos, &trailer) catch return error.Storage;
if (nt < trailer.len) return .torn;
if (crc.final() != std.mem.readInt(u32, &trailer, .little)) return error.Corrupt;
return .{ .frame = .{ .hash = fh.hash, .hash_len = fh.hash_len, .frame_len = frame_len, .payload_len = fh.payload_len, .kind = fh.kind, .delta_of = fh.delta_of } };
}
/// Rebuilds `self.entries`/`self.index` by scanning frames from
/// `header_len`. With `recover_torn`, a torn tail truncates to the last valid
/// boundary; otherwise it is reported as corruption without mutating storage.
/// A corrupt complete frame always propagates `error.Corrupt`.
fn scan(self: *LogStore, recover_torn: bool) OpenError!void {
const total = self.file.size() catch return error.Storage;
const max_frames = (total - header_len) / min_frame + 1;
var offset: u64 = header_len;
var frames: u64 = 0;
while (offset < total) {
frames += 1;
std.debug.assert(frames <= max_frames);
switch (try scanOneFrame(self.file, offset, total)) {
.torn => {
if (!recover_torn) return error.Corrupt;
self.file.truncate(offset) catch return error.Storage;
self.end = offset;
return;
},
.frame => |f| {
if (f.kind == .config) {
// Config is not interned: it never enters entries/index,
// and "latest wins" is just the last one scan reaches (§E).
if (self.config_offset) |prev| std.debug.assert(offset > prev);
self.config_offset = offset;
} else {
// Delta depth is recovered from the base frame, which — by
// the append-only, strictly-backward `delta_of` invariant —
// was scanned earlier and is already in `entries` (offset
// order). A base whose offset is not found is a dangling
// delta `content()` will reject; depth 0 is a safe placeholder.
const depth: u8 = if (f.kind == .delta)
self.depthForBaseOffset(f.delta_of) +| 1
else
0;
const owned = try self.gpa.dupe(u8, f.hash[0..f.hash_len]);
errdefer self.gpa.free(owned);
try self.entries.append(self.gpa, .{ .hash = owned, .offset = offset, .payload_len = f.payload_len, .kind = f.kind, .phantom = false, .depth = depth });
errdefer _ = self.entries.pop();
const rid: Rid = self.entries.items.len;
try self.index.put(self.gpa, owned, rid);
}
const next = offset + f.frame_len;
std.debug.assert(next > offset);
offset = next;
},
}
}
self.end = offset;
}
/// Encodes one frame into `buf` (which must be at least the padded frame
/// span) and returns the written slice. Shared by the production write
/// path and by tests that hand-craft torn/corrupt fixtures.
///
/// Layout (all little-endian): len(4) | flags(1) | hash_len(1) |
/// prefix_crc32(4) = crc32(bytes[0..6)) | hash(hash_len) | delta_of(8) |
/// header_crc32(4) = crc32(bytes[0..18+hash_len)) | payload(len) |
/// frame_crc32(4) = crc32(bytes[0..22+hash_len+len)). `delta_of` is the
/// base frame's byte offset for a `delta` frame, and 0 otherwise.
fn encodeFrame(buf: []u8, hash: []const u8, payload: []const u8, flags: u8, delta_of: u64) []const u8 {
std.debug.assert(hash.len >= min_hash_len and hash.len <= max_hash_len);
std.debug.assert(payload.len <= max_payload);
const hl: usize = hash.len;
const pl: usize = payload.len;
const hash_len: u8 = @intCast(hl);
const payload_len: u32 = @intCast(pl);
const unpadded: usize = 26 + hl + pl;
const frame_len: usize = @intCast(alignUp8(u64, unpadded));
std.debug.assert(buf.len >= frame_len);
std.mem.writeInt(u32, buf[0..4], payload_len, .little);
buf[4] = flags;
buf[5] = hash_len;
var pcrc = std.hash.Crc32.init();
pcrc.update(buf[0..6]);
std.mem.writeInt(u32, buf[6..][0..4], pcrc.final(), .little);
@memcpy(buf[10..][0..hl], hash);
std.mem.writeInt(u64, buf[10 + hl ..][0..8], delta_of, .little);
var hcrc = std.hash.Crc32.init();
hcrc.update(buf[0 .. 18 + hl]);
std.mem.writeInt(u32, buf[18 + hl ..][0..4], hcrc.final(), .little);
@memcpy(buf[22 + hl ..][0..pl], payload);
var fcrc = std.hash.Crc32.init();
fcrc.update(buf[0 .. 22 + hl + pl]);
std.mem.writeInt(u32, buf[22 + hl + pl ..][0..4], fcrc.final(), .little);
if (frame_len > unpadded) @memset(buf[unpadded..frame_len], 0);
return buf[0..frame_len];
}
fn alignUp8(comptime T: type, n: T) T {
const a: T = frame_align;
return (n + (a - 1)) / a * a;
}
/// Encodes `cfg` into `buf` as `[hash_policy u8][branch_len u16 LE][branch]
/// [pid_len u16 LE][pid][pcode_len u16 LE][pcode][login_len u16 LE][login]
/// [secret_len u16 LE][secret]` and returns the written slice (§E fixed field
/// order — deterministic, not a hash-map dump). Every string field is always
/// written (length zero when empty), so decode consumption stays exact. Fixed
/// bounds, no unbounded copy.
fn encodeConfig(buf: []u8, cfg: Config) []const u8 {
std.debug.assert(buf.len >= max_config_payload);
std.debug.assert(cfg.default_branch.len <= max_config_str);
std.debug.assert(cfg.project_id.len <= max_config_str);
std.debug.assert(cfg.project_code.len <= max_config_str);
std.debug.assert(cfg.login_user.len <= max_config_str);
std.debug.assert(cfg.login_secret_hex.len <= max_config_str);
const bl: usize = cfg.default_branch.len;
const pl: usize = cfg.project_id.len;
const cl: usize = cfg.project_code.len;
const ul: usize = cfg.login_user.len;
const sl: usize = cfg.login_secret_hex.len;
buf[0] = cfg.hash_policy;
std.mem.writeInt(u16, buf[1..3], @intCast(bl), .little);
@memcpy(buf[3..][0..bl], cfg.default_branch);
std.mem.writeInt(u16, buf[3 + bl ..][0..2], @intCast(pl), .little);
@memcpy(buf[5 + bl ..][0..pl], cfg.project_id);
std.mem.writeInt(u16, buf[5 + bl + pl ..][0..2], @intCast(cl), .little);
@memcpy(buf[7 + bl + pl ..][0..cl], cfg.project_code);
std.mem.writeInt(u16, buf[7 + bl + pl + cl ..][0..2], @intCast(ul), .little);
@memcpy(buf[9 + bl + pl + cl ..][0..ul], cfg.login_user);
std.mem.writeInt(u16, buf[9 + bl + pl + cl + ul ..][0..2], @intCast(sl), .little);
@memcpy(buf[11 + bl + pl + cl + ul ..][0..sl], cfg.login_secret_hex);
return buf[0 .. 11 + bl + pl + cl + ul + sl];
}
/// Parses an `encodeConfig` payload. Every LE length read is bounds-checked
/// against the remaining slice before use, each length is capped at
/// `max_config_str`, and total consumption must be exact (trailing bytes are
/// corruption). Borrows `payload`. All wire-derived, validated before use.
fn parseConfig(payload: []const u8) error{Corrupt}!Config {
if (payload.len < 1) return error.Corrupt; // no hash_policy byte
const hash_policy = payload[0];
var pos: usize = 1;
if (payload.len - pos < 2) return error.Corrupt;
const blen: usize = std.mem.readInt(u16, payload[pos..][0..2], .little);
pos += 2;
if (blen > max_config_str) return error.Corrupt;
if (payload.len - pos < blen) return error.Corrupt;
const branch = payload[pos..][0..blen];
pos += blen;
if (payload.len - pos < 2) return error.Corrupt;
const plen: usize = std.mem.readInt(u16, payload[pos..][0..2], .little);
pos += 2;
if (plen > max_config_str) return error.Corrupt;
if (payload.len - pos < plen) return error.Corrupt;
const pid = payload[pos..][0..plen];
pos += plen;
if (payload.len - pos < 2) return error.Corrupt;
const clen: usize = std.mem.readInt(u16, payload[pos..][0..2], .little);
pos += 2;
if (clen > max_config_str) return error.Corrupt;
if (payload.len - pos < clen) return error.Corrupt;
const pcode = payload[pos..][0..clen];
pos += clen;
// sync §6.3 — the login credential fields are an optional trailing block:
// a frame written before they existed ends exactly here, and parses with
// an empty credential (forward-compatible), never as corruption.
if (pos == payload.len) {
return .{ .hash_policy = hash_policy, .default_branch = branch, .project_id = pid, .project_code = pcode };
}
if (payload.len - pos < 2) return error.Corrupt;
const ulen: usize = std.mem.readInt(u16, payload[pos..][0..2], .little);
pos += 2;
if (ulen > max_config_str) return error.Corrupt;
if (payload.len - pos < ulen) return error.Corrupt;
const login = payload[pos..][0..ulen];
pos += ulen;
if (payload.len - pos < 2) return error.Corrupt;
const slen: usize = std.mem.readInt(u16, payload[pos..][0..2], .little);
pos += 2;
if (slen > max_config_str) return error.Corrupt;
if (payload.len - pos < slen) return error.Corrupt;
const secret = payload[pos..][0..slen];
pos += slen;
if (pos != payload.len) return error.Corrupt; // no trailing bytes
return .{
.hash_policy = hash_policy,
.default_branch = branch,
.project_id = pid,
.project_code = pcode,
.login_user = login,
.login_secret_hex = secret,
};
}
/// `Compress.init` asserts its output writer already holds more than 8 bytes
/// of buffer; `Writer.Allocating` starts empty, so pre-size before init.
/// This headroom covers the 4-byte length prefix and 2-byte zlib header
/// written first.
const compress_out_min: usize = 64;
/// sync §4.1 L1192-1197: the fossil zlib container — a 4-byte big-endian
/// uncompressed length, then an RFC1950 zlib stream (2-byte header, DEFLATE
/// body, 4-byte Adler-32 trailer) at the default level. The only compression
/// in the store. Kept private to the storage layer (no layer-inverting import
/// of the protocol module); sync carries its own cited copy.
fn containerEncode(gpa: std.mem.Allocator, bytes: []const u8) error{OutOfMemory}![]u8 {
std.debug.assert(bytes.len <= max_payload); // max_payload < 2^32, fits the length field
var aw = std.Io.Writer.Allocating.init(gpa);
defer aw.deinit();
aw.ensureUnusedCapacity(compress_out_min) catch return error.OutOfMemory;
aw.writer.writeInt(u32, @intCast(bytes.len), .big) catch return error.OutOfMemory;
const window = gpa.alloc(u8, flate.max_window_len) catch return error.OutOfMemory;
defer gpa.free(window);
var c = flate.Compress.init(&aw.writer, window, .zlib, .level_6) catch return error.OutOfMemory;
c.writer.writeAll(bytes) catch return error.OutOfMemory;
c.finish() catch return error.OutOfMemory;
const out = aw.toOwnedSlice() catch return error.OutOfMemory;
std.debug.assert(std.mem.readInt(u32, out[0..4], .big) == bytes.len);
return out;
}
/// Decodes a `containerEncode` container. `max_output` bounds the declared
/// length (a lying header is rejected before any inflate work) and the stream
/// is pumped no further than `declared + 1` bytes, so a length lie cannot
/// drive unbounded allocation and an overrun past `declared` is caught.
/// Malformed input (short header, length mismatch, bad stream) is
/// `error.Corrupt`; decode is compression-level-independent (§4.1 L1204-1206).
fn containerDecode(gpa: std.mem.Allocator, wire: []const u8, max_output: usize) ContentError![]u8 {
if (wire.len < 4) return error.Corrupt;
const declared = std.mem.readInt(u32, wire[0..4], .big);
if (declared > max_output) return error.Corrupt;
var fr = std.Io.Reader.fixed(wire[4..]);
const window = gpa.alloc(u8, flate.max_window_len) catch return error.OutOfMemory;
defer gpa.free(window);
var dc = flate.Decompress.init(&fr, .zlib, window);
var aw = std.Io.Writer.Allocating.init(gpa);
defer aw.deinit();
const cap: usize = @as(usize, declared) + 1;
var total: usize = 0;
// stream() may make progress without emitting bytes (parsing a block
// header), so 0 is not completion — only EndOfStream or reaching `cap`
// ends the pump. The iteration count is still explicitly bounded so a
// stalling stdlib regression surfaces as Corrupt rather than a hang.
const max_iters: usize = wire.len + cap + 64;
var iters: usize = 0;
while (total < cap and iters < max_iters) : (iters += 1) {
const n = dc.reader.stream(&aw.writer, .limited(cap - total)) catch |err| switch (err) {
error.EndOfStream => break,
error.WriteFailed => return error.OutOfMemory,
error.ReadFailed => return error.Corrupt,
};
total += n;
}
if (iters >= max_iters) return error.Corrupt;
if (total != declared) return error.Corrupt; // inflated length must equal the declared length
const out = aw.toOwnedSlice() catch return error.OutOfMemory;
std.debug.assert(out.len == declared);
return out;
}
// ---------------------------------------------------------------------------
// Framing tests (no RFC section behind this file; the oracle is the module
// doc's crash-recovery invariants above).
// ---------------------------------------------------------------------------
fn openTmp(tmp: anytype, io: std.Io, name: []const u8) !storage.FileStorage {
const raw = try tmp.dir.createFile(io, name, .{ .read = true });
return storage.FileStorage.init(io, raw, 0);
}
fn writeRawHeader(file: storage.StorageFile, magic_bytes: []const u8, ver: u16, hk: u8, bad_crc: bool) !void {
std.debug.assert(magic_bytes.len == 4);
var buf: [header_len]u8 = [_]u8{0} ** header_len;
@memcpy(buf[0..4], magic_bytes);
std.mem.writeInt(u16, buf[4..6], ver, .little);
buf[6] = hk;
var crc = std.hash.Crc32.init();
crc.update(buf[0..60]);
var crc_val = crc.final();
if (bad_crc) crc_val ^= 1;
std.mem.writeInt(u32, buf[60..64], crc_val, .little);
try file.append(&buf);
}
test "logstore §C: header round-trips magic/version/hash_kind through open" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var store1 = try LogStore.open(std.testing.allocator, file, 7);
store1.deinit(std.testing.allocator);
var raw: [header_len]u8 = undefined;
const n = try file.pread(0, &raw);
try std.testing.expectEqual(@as(usize, header_len), n);
try std.testing.expectEqualStrings(magic, raw[0..4]);
try std.testing.expectEqual(@as(u16, version), std.mem.readInt(u16, raw[4..6], .little));
try std.testing.expectEqual(@as(u8, 7), raw[6]);
for (raw[7..60]) |b| try std.testing.expectEqual(@as(u8, 0), b);
var crc = std.hash.Crc32.init();
crc.update(raw[0..60]);
try std.testing.expectEqual(crc.final(), std.mem.readInt(u32, raw[60..64], .little));
var store2 = try LogStore.open(std.testing.allocator, file, 0); // hint ignored on reopen
defer store2.deinit(std.testing.allocator);
try std.testing.expectEqual(@as(u8, 7), store2.hash_kind);
}
test "logstore §C: open rejects a corrupt file-header crc" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
try writeRawHeader(file, magic, version, 0, true);
try std.testing.expectError(error.Corrupt, LogStore.open(std.testing.allocator, file, 0));
}
test "logstore §C: open rejects a version newer than this reader" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
try writeRawHeader(file, magic, version + 1, 0, false);
try std.testing.expectError(error.Corrupt, LogStore.open(std.testing.allocator, file, 0));
}
test "logstore §C: the frame header crc covers len/flags/hash_len/hash/delta_of" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator); // header only
var buf: [64]u8 = undefined;
const frame = encodeFrame(&buf, "aaaa", "payload", @intFromEnum(FrameKind.raw), 0);
var corrupted: [64]u8 = undefined;
@memcpy(corrupted[0..frame.len], frame);
corrupted[10] ^= 0xff; // inside the hash bytes, part of the fixed header
try file.append(corrupted[0..frame.len]);
try std.testing.expectError(error.Corrupt, LogStore.open(std.testing.allocator, file, 0));
}
test "logstore §C(inv2): a genuinely torn (prefix-truncated) final frame truncates to exactly the last valid boundary" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var store = try LogStore.open(std.testing.allocator, file, 0);
_ = try store.put("frame-one-hash", "payload-one");
try store.commit();
const boundary = store.size();
store.deinit(std.testing.allocator);
var buf: [96]u8 = undefined;
const frame2 = encodeFrame(&buf, "frame-two-hash", "payload-two", @intFromEnum(FrameKind.raw), 0);
try file.append(frame2[0..10]); // short of even the fixed header+crc window
var reopened = try LogStore.open(std.testing.allocator, file, 0);
defer reopened.deinit(std.testing.allocator);
try std.testing.expectEqual(boundary, reopened.size());
try std.testing.expect(reopened.lookup("frame-two-hash") == null);
}
test "logstore §C(inv2): a torn payload/crc tail truncates exactly" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var store = try LogStore.open(std.testing.allocator, file, 0);
_ = try store.put("frame-a-hash-here", "hello-payload");
try store.commit();
const boundary = store.size();
store.deinit(std.testing.allocator);
var buf: [128]u8 = undefined;
const frame2 = encodeFrame(&buf, "frame-b-hash-value", "a longer second payload for this test", @intFromEnum(FrameKind.raw), 0);
const header_window = 22 + "frame-b-hash-value".len;
try file.append(frame2[0 .. header_window + 3]); // full header+crc landed; payload/crc badly short
var reopened = try LogStore.open(std.testing.allocator, file, 0);
defer reopened.deinit(std.testing.allocator);
try std.testing.expectEqual(boundary, reopened.size());
}
test "logstore §C(inv4): a bitflipped header on a durable non-final frame surfaces error.Corrupt" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
var buf1: [64]u8 = undefined;
const f1 = encodeFrame(&buf1, "frame-one-abc", "payload-one", @intFromEnum(FrameKind.raw), 0);
var corrupted: [64]u8 = undefined;
@memcpy(corrupted[0..f1.len], f1);
corrupted[10] ^= 0xff;
try file.append(corrupted[0..f1.len]);
var buf2: [64]u8 = undefined;
const f2 = encodeFrame(&buf2, "frame-two-def", "payload-two", @intFromEnum(FrameKind.raw), 0);
try file.append(f2);
try std.testing.expectError(error.Corrupt, LogStore.open(std.testing.allocator, file, 0));
}
test "logstore §C(inv4): a bitflipped complete final frame is error.Corrupt" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
var buf: [64]u8 = undefined;
const f = encodeFrame(&buf, "final-frame-hash", "payload-for-final", @intFromEnum(FrameKind.raw), 0);
var corrupted: [64]u8 = undefined;
@memcpy(corrupted[0..f.len], f);
corrupted[6] ^= 0xff;
try file.append(corrupted[0..f.len]); // complete, fully landed, nothing follows
try std.testing.expectError(error.Corrupt, LogStore.open(std.testing.allocator, file, 0));
}
test "logstore §C(inv4): a corrupted payload on a complete frame surfaces error.Corrupt" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
var buf: [96]u8 = undefined;
const f = encodeFrame(&buf, "payload-hash-value", "some payload bytes here", @intFromEnum(FrameKind.raw), 0);
var corrupted: [96]u8 = undefined;
@memcpy(corrupted[0..f.len], f);
const header_window = 22 + "payload-hash-value".len;
corrupted[header_window] ^= 0xff; // inside the payload, not the fixed header
try file.append(corrupted[0..f.len]);
try std.testing.expectError(error.Corrupt, LogStore.open(std.testing.allocator, file, 0));
}
test "logstore §C(inv4): a bitflipped hash_len that would need more bytes than the file has surfaces error.Corrupt, not a torn tail" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
// hash_len=1, payload="" -> frame_len = align8(26+1+0) = 32, fully
// landed, nothing follows. Corrupting hash_len to an in-range value
// (20) makes the naive "read 18+hash_len bytes, short = torn" reading
// demand 38 bytes from a 32-byte frame -- exactly the false-torn gap
// the prefix checksum closes: it fails on this corrupted byte before
// any window-size decision is made from it.
var buf: [64]u8 = undefined;
const f = encodeFrame(&buf, "h", "", @intFromEnum(FrameKind.raw), 0);
var corrupted: [64]u8 = undefined;
@memcpy(corrupted[0..f.len], f);
corrupted[5] = 20;
try file.append(corrupted[0..f.len]);
try std.testing.expectError(error.Corrupt, LogStore.open(std.testing.allocator, file, 0));
}
test "logstore §C: a crc-valid frame with an unknown flag kind (not raw/zlib/delta) is rejected on open" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
// flags=4 is one past `config`: both crcs are computed correctly over it,
// so the frame is byte-intact -- it is simply an encoding this reader does
// not know, which must fail closed rather than be interpreted.
var buf: [64]u8 = undefined;
const f = encodeFrame(&buf, "unknown-flag-hash", "some payload bytes", 4, 0);
try file.append(f);
try std.testing.expectError(error.Corrupt, LogStore.open(std.testing.allocator, file, 0));
}
// ---------------------------------------------------------------------------
// zlib and delta frames (container sync §4.1; verbatim serve sync §7.2;
// delta apply delta §4).
// ---------------------------------------------------------------------------
/// Appends one hand-crafted frame (valid crcs) to `file`, for fixtures that
/// need a payload/flag/delta_of a normal put would never produce.
fn appendCrafted(gpa: std.mem.Allocator, file: storage.StorageFile, hash: []const u8, payload: []const u8, kind: FrameKind, delta_of: u64) !void {
const frame_len: usize = @intCast(alignUp8(u64, 26 + hash.len + payload.len));
const buf = try gpa.alloc(u8, frame_len);
defer gpa.free(buf);
const f = encodeFrame(buf, hash, payload, @intFromEnum(kind), delta_of);
try file.append(f);
}
test "logstore §C: content on a malformed zlib container is error.Corrupt" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
// A crc-valid zlib frame whose payload is not a valid container: two bytes
// is short of even the 4-byte length header, so containerDecode rejects it.
const hash = "malformed-zlib-container-hash-01";
try appendCrafted(std.testing.allocator, file, hash, "\x00\x00", .zlib, 0);
var store = try LogStore.open(std.testing.allocator, file, 0);
defer store.deinit(std.testing.allocator);
const rid = store.lookup(hash).?;
try std.testing.expectError(error.Corrupt, store.content(std.testing.allocator, rid));
}
test "logstore §C/sync §4.1: a zlib container whose declared length exceeds max_payload is rejected without a huge allocation" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
// Declared length 0xFFFFFFFF is far past max_payload; containerDecode must
// reject on the declared value before inflating anything.
const hash = "oversize-declared-length-hash-01";
try appendCrafted(std.testing.allocator, file, hash, "\xff\xff\xff\xff\x78\x9c", .zlib, 0);
var store = try LogStore.open(std.testing.allocator, file, 0);
defer store.deinit(std.testing.allocator);
const rid = store.lookup(hash).?;
try std.testing.expectError(error.Corrupt, store.content(std.testing.allocator, rid));
}
test "logstore §C/delta §4: content on a delta whose inflated payload is not a valid delta is error.Corrupt" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
// A valid raw base, then a crc-valid delta frame whose container inflates
// to bytes that are not a conforming delta -> delta.apply rejects -> Corrupt.
try appendCrafted(std.testing.allocator, file, "garbage-delta-base-hash-00000001", "base content here", .raw, 0);
const container = try containerEncode(std.testing.allocator, "this is not a delta at all");
defer std.testing.allocator.free(container);
try appendCrafted(std.testing.allocator, file, "garbage-delta-hash-value-0000001", container, .delta, header_len);
var store = try LogStore.open(std.testing.allocator, file, 0);
defer store.deinit(std.testing.allocator);
const rid = store.lookup("garbage-delta-hash-value-0000001").?;
try std.testing.expectError(error.Corrupt, store.content(std.testing.allocator, rid));
}
test "logstore §C: content on a delta whose delta_of is out of range or mid-frame is error.Corrupt" {
const cases = [_]struct { name: []const u8, delta_of: u64 }{
.{ .name = "below-header", .delta_of = 0 },
.{ .name = "forward-ref", .delta_of = 1 << 20 },
.{ .name = "mid-base-frame", .delta_of = header_len + 3 },
};
for (cases) |c| {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator);
try appendCrafted(std.testing.allocator, file, "bad-delta-of-base-hash-000000001", "base content bytes", .raw, 0);
const container = try containerEncode(std.testing.allocator, "1\ndelta-ish payload; only delta_of matters here");
defer std.testing.allocator.free(container);
try appendCrafted(std.testing.allocator, file, "bad-delta-of-hash-value-00000001", container, .delta, c.delta_of);
var store = try LogStore.open(std.testing.allocator, file, 0);
defer store.deinit(std.testing.allocator);
const rid = store.lookup("bad-delta-of-hash-value-00000001").?;
try std.testing.expectError(error.Corrupt, store.content(std.testing.allocator, rid));
}
}
// Seeded deterministic fuzz: decode/apply on adversarial wire bytes must
// yield a value or a declared error, never a crash or a hang.
test "logstore §C/sync §4.1 fuzz: a garbage zlib container never crashes content" {
var prng = std.Random.DefaultPrng.init(0x2172B);
const random = prng.random();
var iter: usize = 0;
while (iter < 150) : (iter += 1) {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var store = try LogStore.open(std.testing.allocator, file, 0);
store.deinit(std.testing.allocator); // header only; craft the frame directly
// A crc-valid zlib frame with a random payload must never crash content.
var garbage: [64]u8 = undefined;
const gn = random.uintLessThan(usize, garbage.len + 1);
random.bytes(garbage[0..gn]);
var ghash: [9]u8 = undefined;
ghash[0] = 'g';
std.mem.writeInt(u64, ghash[1..9], iter, .little);
try appendCrafted(std.testing.allocator, file, &ghash, garbage[0..gn], .zlib, 0);
var reopened = try LogStore.open(std.testing.allocator, file, 0);
defer reopened.deinit(std.testing.allocator);
const grid = reopened.lookup(&ghash).?;
if (reopened.content(std.testing.allocator, grid)) |maybe| {
if (maybe) |b| std.testing.allocator.free(b);
} else |err| switch (err) {
error.OutOfMemory, error.Storage, error.Corrupt => {},
}
}
}
test "logstore §C/delta §4 fuzz: a garbage delta payload or delta_of never crashes content" {
var prng = std.Random.DefaultPrng.init(0xD317A);
const random = prng.random();
var iter: usize = 0;
while (iter < 150) : (iter += 1) {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var store = try LogStore.open(std.testing.allocator, file, 0);
store.deinit(std.testing.allocator); // header only; craft the frame directly
// A crc-valid delta frame with a random container payload and a random
// delta_of must never crash content (Corrupt/OOM/value only).
var garbage: [64]u8 = undefined;
const gn = random.uintLessThan(usize, garbage.len + 1);
random.bytes(garbage[0..gn]);
var ghash: [9]u8 = undefined;
ghash[0] = 'x';
std.mem.writeInt(u64, ghash[1..9], iter, .little);
try appendCrafted(std.testing.allocator, file, &ghash, garbage[0..gn], .delta, random.int(u64));
var reopened = try LogStore.open(std.testing.allocator, file, 0);
defer reopened.deinit(std.testing.allocator);
const grid = reopened.lookup(&ghash).?;
if (reopened.content(std.testing.allocator, grid)) |maybe| {
if (maybe) |b| std.testing.allocator.free(b);
} else |err| switch (err) {
error.OutOfMemory, error.Storage, error.Corrupt => {},
}
}
}
test "logstore §C: a config frame is not interned — rids stay content-only and contiguous" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var store = try LogStore.open(std.testing.allocator, file, 0);
defer store.deinit(std.testing.allocator);
const r1 = try store.put("config-interleave-hash-one-0001", "one");
try store.putConfig(.{ .hash_policy = 0, .default_branch = "trunk", .project_id = "pid" });
const r2 = try store.put("config-interleave-hash-two-0001", "two");
// The config frame consumed a byte range but no rid: content rids stay
// dense and contiguous, and the sentinel hash is never an index key.
try std.testing.expectEqual(r1 + 1, r2);
try std.testing.expect(store.lookup(config_sentinel) == null);
}
test "logstore §C: a delta base offset pointing at a config frame is rejected as corrupt" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var seed = try LogStore.open(std.testing.allocator, file, 0);
seed.deinit(std.testing.allocator); // header only
// A config frame at header_len, then a delta whose (valid) container base
// offset points back at it: resolving the base hits the .config arm.
var cbuf: [max_config_payload]u8 = undefined;
const cfg_payload = encodeConfig(&cbuf, .{ .hash_policy = 4, .default_branch = "trunk", .project_id = "pid" });
try appendCrafted(std.testing.allocator, file, config_sentinel, cfg_payload, .config, 0);
const container = try containerEncode(std.testing.allocator, "delta-ish bytes; only the base offset matters here");
defer std.testing.allocator.free(container);
try appendCrafted(std.testing.allocator, file, "delta-over-config-base-hash-0001", container, .delta, header_len);
var store = try LogStore.open(std.testing.allocator, file, 0);
defer store.deinit(std.testing.allocator);
const rid = store.lookup("delta-over-config-base-hash-0001").?;
try std.testing.expectError(error.Corrupt, store.content(std.testing.allocator, rid));
}
test "logstore §E: parseConfig rejects malformed config payloads" {
var over: [3]u8 = undefined;
over[0] = 0; // hash_policy
std.mem.writeInt(u16, over[1..3], @intCast(max_config_str + 1), .little); // branch_len > cap
const cases = [_][]const u8{
&[_]u8{}, // (a) empty: no hash_policy byte
&[_]u8{ 0x07, 0x05 }, // (b) truncated branch_len (1 of 2 bytes)
&over, // (c) branch_len exceeds max_config_str
&[_]u8{ 0x00, 0x05, 0x00, 'a', 'b' }, // (d) branch_len 5 exceeds remaining
&[_]u8{ 0x00, 0x01, 0x00, 'b', 0x02 }, // (e) truncated pid_len after branch
&[_]u8{ 0x00, 0x01, 0x00, 'b', 0x00, 0x00, 0x09 }, // (f) trailing byte after pid
};
for (cases) |c| try std.testing.expectError(error.Corrupt, parseConfig(c));
}
test "logstore §E/§6.3: parseConfig forward-compat-decodes a legacy pre-credential frame" {
// A frame written before the login credential block existed carries only
// the three string fields (branch, project_id, project_code) and ends
// exactly after project_code — encodeConfig can no longer emit this shape
// (it always writes the two trailing length words), so the bytes are hand-
// built. parseConfig's forward-compat arm must accept it with the credential
// fields defaulting empty, never as corruption.
const legacy = [_]u8{
0x04, // hash_policy
0x05, 0x00, 't', 'r', 'u', 'n', 'k', // branch_len=5, "trunk"
0x03, 0x00, 'p', 'i', 'd', // pid_len=3, "pid"
0x05, 0x00, 'c', 'o', 'd', 'e', '9', // pcode_len=5, "code9"
};
const cfg = try parseConfig(&legacy);
try std.testing.expectEqual(@as(u8, 4), cfg.hash_policy);
try std.testing.expectEqualStrings("trunk", cfg.default_branch);
try std.testing.expectEqualStrings("pid", cfg.project_id);
try std.testing.expectEqualStrings("code9", cfg.project_code);
try std.testing.expectEqual(@as(usize, 0), cfg.login_user.len);
try std.testing.expectEqual(@as(usize, 0), cfg.login_secret_hex.len);
}
test "logstore §B: a torn config-frame write reverts to the prior committed config" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const io = std.testing.io;
var fs = try openTmp(&tmp, io, "log.bin");
defer fs.file.close(io);
const file = fs.storageFile();
var store = try LogStore.open(std.testing.allocator, file, 0);
try store.putConfig(.{ .hash_policy = 9, .default_branch = "trunk", .project_id = "keep" });
try store.commit();
store.deinit(std.testing.allocator);
// Append a torn config B frame (prefix only): scan truncates it away, so
// the surviving latest config is still A.
var pbuf: [max_config_payload]u8 = undefined;
const cfgB = encodeConfig(&pbuf, .{ .hash_policy = 1, .default_branch = "x", .project_id = "y" });
var fbuf: [64]u8 = undefined;
const frameB = encodeFrame(&fbuf, config_sentinel, cfgB, @intFromEnum(FrameKind.config), 0);
try file.append(frameB[0..10]); // torn: short of the fixed header+crc window
var reopened = try LogStore.open(std.testing.allocator, file, 0);
defer reopened.deinit(std.testing.allocator);
var oc = (try reopened.readConfig(std.testing.allocator)).?;
defer oc.deinit(std.testing.allocator);
try std.testing.expectEqual(@as(u8, 9), oc.config.hash_policy);
try std.testing.expectEqualStrings("trunk", oc.config.default_branch);
try std.testing.expectEqualStrings("keep", oc.config.project_id);
}
// Seeded deterministic fuzz: parseConfig on adversarial wire bytes yields a
// value or error.Corrupt, never a crash.
test "logstore §E fuzz: parseConfig never crashes on adversarial payloads" {
var prng = std.Random.DefaultPrng.init(0xC04F16);
const random = prng.random();
var iter: usize = 0;
while (iter < 400) : (iter += 1) {
var garbage: [64]u8 = undefined;
const gn = random.uintAtMost(usize, garbage.len);
random.bytes(garbage[0..gn]);
if (parseConfig(garbage[0..gn])) |_| {} else |err| switch (err) {
error.Corrupt => {},
}
}
}