//! `zit serve`: the HTTP face on the stateless sync responder, and the
//! per-request repository context each served round reads and writes.
const std = @import("std");
const ClientHoldings = zit.sync_session.ClientHoldings;
const File = Io.File;
const Io = std.Io;
const LogIndexStore = zit.log_index_store.LogIndexStore;
const RepoShunSet = zit.log_index_store.RepoShunSet;
const Repository = @import("zit").Repository;
const applySessionErasures = @import("session_erasures.zig").applySessionErasures;
const artifact = zit.artifact;
const cli = @import("zit").cli;
const clusterindex = @import("zit").clusterindex;
const d4OpenLog = @import("sync_test_support.zig").d4OpenLog;
const d4SeedEmptyRepo = @import("sync_test_support.zig").d4SeedEmptyRepo;
const decodeWireName = zit.digest_name.decodeWireName;
const diagnostics = @import("../cli/diagnostics.zig");
const digestToWireName = zit.digest_name.digestToWireName;
const digest_len = zit.digest_name.digest_len;
const erasedBytesHeld = @import("session_erasures.zig").erasedBytesHeld;
const erasureNeedsApplied = @import("session_erasures.zig").erasureNeedsApplied;
const help_pages = @import("../cli/help.zig");
const hexToDigest = zit.digest_name.hexToDigest;
const loadClusterIndex = zit.receive.loadClusterIndex;
const logstore = @import("zit").logstore;
const not_a_repo_msg = diagnostics.not_a_repo_msg;
const openLogAdoptingIndex = zit.log_index_store.openLogAdoptingIndex;
const packSeedDeltaStore = @import("sync_test_support.zig").packSeedDeltaStore;
const persistStore = zit.receive.persistStore;
const persistStoreAdopting = zit.receive.persistStoreAdopting;
const reasonOf = diagnostics.reasonOf;
const repeat = @import("zit").repeat;
const repoReadFail = diagnostics.repoReadFail;
const repoSyncIdentity = zit.sync_session.repoSyncIdentity;
const repo_filename = zit.repo_filename;
const repostate = zit.repostate;
const resolveSettingWith = zit.repo_config.resolveSettingWith;
const s77SeedPolicyRepo = @import("sync_test_support.zig").s77SeedPolicyRepo;
const seedShunnedRepo = @import("sync_test_support.zig").seedShunnedRepo;
const send_shun_digests = @import("sync_test_support.zig").send_shun_digests;
const send_shun_names = @import("sync_test_support.zig").send_shun_names;
const serveAppendFrame = @import("sync_test_support.zig").serveAppendFrame;
const serve_help = help_pages.serve_help;
const serve_mod = @import("../net/serve.zig");
const shun_test_digest = @import("sync_test_support.zig").shun_test_digest;
const shun_test_held_digest = @import("sync_test_support.zig").shun_test_held_digest;
const shun_test_held_name = @import("sync_test_support.zig").shun_test_held_name;
const shun_test_name = @import("sync_test_support.zig").shun_test_name;
const stateOom = diagnostics.stateOom;
const storage = @import("zit").storage;
const treeManifestBytes = @import("sync_test_support.zig").treeManifestBytes;
const updateConfig = zit.repo_config.updateConfig;
const zit = @import("zit");
/// `zit serve [--port N]` — put an HTTP face on the stateless sync responder.
/// Opens `.zit` read-only and keeps it open for the server's lifetime; every
/// request reads a fresh content view of it and is answered independently
/// (sync §3.8). `std.http`/socket I/O lives entirely in `serve.zig`; this only
/// wires the repository and the listen address.
pub fn runServe(
gpa: std.mem.Allocator,
io: std.Io,
arena: std.mem.Allocator,
verb_args: []const []const u8,
streams: cli.Streams,
/// Carried solely so the served rounds can resolve this server's own
/// content policy through the shared settings resolver.
amb: cli.Ambient,
) cli.Exit {
const parsed = switch (cli.parseServeArgs(verb_args)) {
.ok => |p| p,
.unknown_option => |tok| return cli.usageError(streams, "serve", .unknown_option, tok),
.extra_argument => |tok| return cli.usageError(streams, "serve", .extra_argument, tok),
.bad_port => |tok| {
streams.err.print("zit serve: invalid --port value '{s}'\n", .{tok}) catch {};
return .usage;
},
.bad_horizon_url => |tok| {
streams.err.print("zit serve: invalid --horizon-url value '{s}': one token, no whitespace or control characters\n", .{tok}) catch {};
return .usage;
},
};
if (parsed.help) {
streams.out.writeAll(serve_help) catch {};
return .ok;
}
const root = (cli.discoverRoot(arena, io) catch return stateOom(streams, "serve")) orelse {
streams.err.writeAll(not_a_repo_msg) catch {};
return .failure;
};
var root_dir = root.dir;
// serve answers from the STORE: its open handle, its swap-detect
// stat and its config reads all follow the resolved store root.
if (cli.storeDirOf(io, root_dir) catch {
root_dir.close(io);
return repoReadFail(streams, "serve");
}) |resolved| {
root_dir.close(io);
root_dir = resolved;
}
const accepted = zit.import_transaction.capture(io, root_dir) catch {
root_dir.close(io);
return repoReadFail(streams, "serve");
};
var file = accepted.file;
defer file.close(io);
const log_st = accepted.accepted_stat;
// Bring-up order is load-bearing (rationale in `serve_mod.listen`'s
// doc): open the listener FIRST — before ANY O(store) work, which here means
// both the config read below and the prime, each a full-log scan. A client
// that connects during either queues in the accept backlog instead of being
// refused, so the readiness window starts at the bind rather than after the
// scans. Announce "listening" only once the bind has actually succeeded (so
// it never lies about a listener that failed to come up); the accept loop
// then arms each connection's deadline on accept. The backlog property this
// rests on is pinned by serve.zig's "listen opens the accept backlog before
// serve" test.
const address = std.Io.net.IpAddress.parse("127.0.0.1", parsed.port) catch {
streams.err.print("zit serve: invalid --port value '{d}'\n", .{parsed.port}) catch {};
return .usage;
};
var listener = serve_mod.listen(io, address) catch {
streams.err.print("zit serve: cannot bind 127.0.0.1:{d}\n", .{parsed.port}) catch {};
return .failure;
};
defer listener.deinit(io);
streams.err.print("zit serve: listening on http://127.0.0.1:{d}/xfer (Ctrl-C to stop)\n", .{parsed.port}) catch {};
streams.err.flush() catch {};
var fs = storage.FileStorage.initReadOnly(io, file, log_st.size);
// Through the log-index sidecar, as the snapshot below opens: this open
// is for one config read, and a whole-log header walk for it was most of
// a fresh server's first-request cost on a large store.
var log = openLogAdoptingIndex(gpa, io, root_dir, fs.storageFile(), .refresh_on_scan) catch |e| {
root_dir.close(io);
switch (e) {
error.OutOfMemory => streams.err.writeAll("zit serve: out of memory\n") catch {},
else => streams.err.print("zit serve: cannot read repository: {s}\n", .{reasonOf(e)}) catch {},
}
return .failure;
};
defer log.deinit(gpa);
defer root_dir.close(io);
// §9.1/§8.2 — emit the repository's stored project code in the clone
// reply's `push` card, so a clone learns the shared project identity. A
// repo predating the stored code, or an unreadable config, falls back to
// the fixed placeholder (informational; servercode never gates a clone).
var maybe_cfg: ?logstore.OwnedConfig = log.readConfig(gpa) catch null;
defer if (maybe_cfg) |*oc| oc.deinit(gpa);
const project_code: []const u8 = if (maybe_cfg) |oc|
(if (oc.config.project_code.len > 0) oc.config.project_code else serve_mod.server_projectcode)
else
serve_mod.server_projectcode;
// §9.1 — a real instance identity in the clone reply's `push` card,
// derived from this checkout's absolute path exactly as init derives the
// project code (stable, distinct per instance, no ambient RNG). The
// placeholder constant remains only as the test fixtures' server identity.
const serve_code = zit.sync.deriveServerCode(&.{root.abs});
const server = zit.sync.Server{
.version = serve_mod.server_version,
.credential = null,
.read_only = parsed.read_only,
.adopt_project = parsed.adopt_project,
.self_servercode = &serve_code,
.project_code = project_code,
.horizon_url = parsed.horizon_url,
};
var ctx = ServeCtx{ .io = io, .root_dir = root_dir, .file = &file, .diag = streams.err, .server = &server, .amb = amb, .fronted = parsed.fronted };
defer ctx.deinit();
const responder = serve_mod.Responder{ .ctx = &ctx, .answerFn = serveAnswer, .maintainFn = ServeCtx.maintain, .fronted = parsed.fronted };
if (ctx.baseSnapshot(gpa)) |_| {} else |_| return repoReadFail(streams, "serve");
serve_mod.serve(io, gpa, &listener, responder, .{}) catch |e| switch (e) {
error.Accept => {
streams.err.writeAll("zit serve: connection accept failed\n") catch {};
return .failure;
},
};
return .ok;
}
/// The per-request context threaded into `serve.Responder`: the open log to read
/// a fresh store from, the server identity to answer with, and the injected IO +
/// repository directory used to make pushed content durable (a push request
/// ingests new artifacts into the per-request store, which must be persisted into
/// the served repository's on-disk log — sync §3.3).
pub const ServeCtx = struct {
io: std.Io,
root_dir: std.Io.Dir,
/// The ambient environment, carried only so `resolveSetting` (the one
/// settings resolver) is reachable per round. Reading the config frame
/// directly here instead would be a second reader, and the two drifting is
/// the bug `signingSettings` documents having shipped once already.
amb: ?cli.Ambient = null,
/// Behind a trusted front. Turns on the per-round membership
/// rule and keeps the repository image warm between connections so that
/// rule reads O(image), not O(store), after a push.
fronted: bool = false,
/// The open read handle on the served `.zit`. `respond` re-reads the CURRENT
/// on-disk log from it (§3.8): a fresh stat fixes the committed end-of-log,
/// so a check-in appended by a separate `zit commit` while `serve` runs is
/// advertised on the next request — no restart.
///
/// The handle pins an INODE, not a path. `zit pack` and `zit shun --force`
/// replace `.zit` by rename, which would leave a held-open handle reading
/// the replaced inode forever (its fstat never moves again — no cache key
/// over the handle can detect the swap). `baseSnapshot` therefore stats
/// the PATH beside the handle each round and REOPENS on an inode change:
/// the swap is noticed at the next round boundary, so a shun that
/// rode a generation rewrite stops being served with no restart, while an
/// in-flight round keeps its consistent pre-swap view. A pointer into
/// `runServe`'s frame so the reopen and the shutdown close agree on one
/// current handle.
file: *File,
/// Where `serveAnswer` names a failed request, or null to stay silent. The
/// tests and `driveHttp` leave it unset; `runServe` points it at stderr.
diag: ?*std.Io.Writer = null,
server: *const zit.sync.Server,
/// The most recent snapshot of the on-disk log, reused across requests. A
/// log-backed INDEX (not a full-container copy): it reads the containers it
/// serves on demand and holds only the index between rounds. Built from
/// the long-lived allocator `serve` threads into every answer, so it outlives
/// the request that built it, and owned here — heap-allocated because it owns
/// the `FileStorage` its log borrows; `dropSnapshot` frees it. Never handed to
/// `respond` directly — see `serveAnswer`.
snapshot: ?*LogIndexStore = null,
/// The served store's structural graph (`structgraph.Graph`), read once
/// and extended by the frames each rebuilt snapshot adds, so a horizon
/// classification for ANY cone is a walk over arrays, never a re-read of
/// the store. Built on the first horizon request, kept across snapshots.
graph: ?zit.structgraph.Graph = null,
/// The allocator the graph (and every snapshot) was built with.
graph_gpa: ?std.mem.Allocator = null,
/// The snapshot's cluster index, rebuilt with it.
clusters: ?clusterindex.Resolved = null,
/// The log size `snapshot` was built from — one half of the cache key that
/// `baseSnapshot` stats per request (see there for why size alone is not it).
snapshot_log_size: u64 = 0,
/// The log's last-modification time (ns) when `snapshot` was built. Together
/// with the size it is the cache key: a write that does not change the length
/// still moves `mtime`. A `std.Io.Timestamp`, unwrapped to its `nanoseconds`
/// here so the key is two scalar comparisons.
snapshot_log_mtime_ns: i96 = 0,
/// How many snapshots this server has built. Not used by the server; it is
/// the observable that makes "snapshot builds do not grow with the round
/// count" a testable property rather than a wall-clock claim.
loads: u64 = 0,
/// The repository the round resolvers read branches, tags, merge bases
/// and seeds from, kept across rounds while the snapshot's log key is
/// unchanged. Opening validates and maps the whole image sidecar, which a
/// multi-round clone of a large store otherwise paid every round. Heap
/// allocated with `round_repo_gpa`: an open `Repository` is not moved.
round_repo: ?*Repository = null,
round_repo_gpa: ?std.mem.Allocator = null,
/// The snapshot key `round_repo` was opened under.
round_repo_log_size: u64 = 0,
round_repo_log_mtime_ns: i96 = 0,
/// How many times `roundRepo` opened the repository; the observable that
/// keeps "opens do not grow with the round count" testable.
repo_opens: u64 = 0,
/// Free the cached snapshot, leaving the context usable: the next
/// `baseSnapshot` rebuilds. Both a caller finishing with the context and the
/// rebuild path itself want exactly this.
/// Teardown: the snapshot and the graph that outlived its rebuilds.
pub fn deinit(self: *ServeCtx) void {
self.dropSnapshot();
self.dropRoundRepo();
if (self.graph) |*g| g.deinit(self.graph_gpa.?);
self.graph = null;
}
fn dropRoundRepo(self: *ServeCtx) void {
if (self.round_repo) |r| {
r.deinit(self.round_repo_gpa.?);
self.round_repo_gpa.?.destroy(r);
}
self.round_repo = null;
self.round_repo_gpa = null;
}
/// The repository for this round, reopened only when the snapshot's log
/// key moved since it was opened (a push, a commit beside `serve`, or a
/// generation swap, which `dropSnapshot` zeroes the key for).
fn roundRepo(self: *ServeCtx, gpa: std.mem.Allocator) !*Repository {
if (self.round_repo) |r| {
if (self.snapshot_log_size != 0 and self.round_repo_log_size == self.snapshot_log_size and
self.round_repo_log_mtime_ns == self.snapshot_log_mtime_ns) return r;
}
self.dropRoundRepo();
const r = try gpa.create(Repository);
errdefer gpa.destroy(r);
try Repository.open(r, gpa, self.io, self.root_dir, .{ .mode = .fast_read });
self.round_repo = r;
self.round_repo_gpa = gpa;
self.round_repo_log_size = self.snapshot_log_size;
self.round_repo_log_mtime_ns = self.snapshot_log_mtime_ns;
self.repo_opens += 1;
return r;
}
fn dropSnapshot(self: *ServeCtx) void {
if (self.clusters) |*c| c.deinit();
self.clusters = null;
if (self.snapshot) |s| s.destroy();
self.snapshot = null;
self.snapshot_log_size = 0;
self.snapshot_log_mtime_ns = 0;
}
/// Drop plaintext the cached snapshot memoised while answering, keeping the
/// retained containers it serves from. Called once per round, after every
/// borrow of the snapshot has ended.
///
/// Inflating is how `content()` answers a wire-backed entry, and the
/// responder's own §7.2 size proofs call `content()` on every artifact they
/// emit. Against a throwaway per-request store that plaintext died with the
/// request; against a store that outlives the request it would accumulate
/// until the server held the whole repository's uncompressed history. The
/// containers stay, so the next round answers identically.
///
/// The memo is given up rather than capped because in an optimized build
/// there is almost nothing to give up: the size proofs are `runtime_safety`
/// only, so a clone round inflates nothing and the memo would stay empty
/// regardless. Measured over four clones of a 3001-artifact repository,
/// ReleaseFast: 12 MB resident and 0.09 s of server CPU with this release,
/// against 26 MB and 0.15 s without it. A safety-checked build does re-prove
/// every emitted artifact each round and so pays to re-inflate; that cost
/// belongs to the proofs, not to the cache.
fn releaseSnapshotPlaintext(self: *ServeCtx) void {
if (self.snapshot) |s| s.releaseTransient();
}
/// §3.8 — the store describing the CURRENT on-disk log, rebuilt only when the
/// log has actually grown. The §3.8 guarantee is that a check-in appended by
/// a separate `zit commit` is advertised on the NEXT request with no restart;
/// that needs a fresh `stat` per request, not a fresh rebuild per request.
/// Rebuilding regardless made every round cost the whole repository, which is
/// what turned a clone of a large store into O(rounds x store) server work.
///
/// A torn tail from an append caught mid-write is rejected by the read-only
/// scanner exactly as before; the previous snapshot is dropped only once a
/// replacement is fully built, so a failed rebuild leaves the cache coherent.
///
/// The rebuild itself is O(store) and must therefore not fall inside a
/// request whose connection carries a deadline. `runServe` primes the cache
/// before it accepts anything. A round that appends to the log does NOT
/// rebuild before it returns — it deliberately leaves the snapshot stale
/// (describing the pre-append log) rather than pay the O(store) rebuild inside
/// its own reply deadline. The append-only stat gate above makes that
/// stale snapshot self-correcting: the size no longer matches, so the next
/// `baseSnapshot` rebuilds. That next call is the accept loop's `maintain`
/// hook (see `ServeCtx.maintain`), run between connections with no connection
/// open — so the deferred rebuild still lands outside every connection
/// deadline, never on an innocent later request. Nothing here can bound the
/// startup build itself; that is bounded by the store, and always was.
///
/// THE CACHE KEY IS NOT THE SIZE ALONE, and since this snapshot began carrying
/// the §3.3 shun table it cannot be. A stale snapshot used to cost stale CONTENT
/// — a peer misses a newly committed artifact and the next round supplies it —
/// which is self-correcting. It now also decides whether the SUPPRESSION table is
/// re-read, and a missed re-read serves an artifact the operator shunned, with
/// nothing failing and nothing logged. "Every writer only appends, so the length
/// always grows" is true of `zit shun --defer` and `zit commit` today, but it is
/// an assumption about all present and future writers rather than a checked
/// property: a generation rewrite landing on the same byte length, or any
/// out-of-band mutation, would keep the old mask forever. So the key is size AND
/// mtime — an in-place rewrite that does not change the length still moves the
/// mtime. Two scalar comparisons against one `stat` this function already
/// performs, and they can only over-invalidate (which costs a rebuild), never
/// under-invalidate on a write that reaches THIS INODE.
///
/// Capture a publication-fenced descriptor before consulting the cache.
/// Its inode detects generation replacement; its fixed bound excludes any
/// later append. Pending imports fail new requests closed while preserving
/// the old snapshot for existing borrows. Build the replacement before
/// closing the descriptor its predecessor owns.
fn baseSnapshot(self: *ServeCtx, gpa: std.mem.Allocator) serve_mod.AnswerError!repostate.ArtifactStore {
const accepted = zit.import_transaction.capture(self.io, self.root_dir) catch return error.ServerStorage;
var adopted = false;
defer if (!adopted) accepted.close(self.io);
const st = accepted.accepted_stat;
const previous = self.file.stat(self.io) catch return error.ServerStorage;
if (self.snapshot) |s| {
if (st.inode == previous.inode and st.size == self.snapshot_log_size and
st.mtime.nanoseconds == self.snapshot_log_mtime_ns) return s.store();
}
// Build the fresh index BEFORE dropping the old one: a failed rebuild
// leaves the previous snapshot (and its size) intact, so the stat gate
// keeps mismatching until a rebuild succeeds and stale content is never
// served in the meantime. `openFromFile` fully frees itself on any error.
const fresh = LogIndexStore.openFromFileIndexed(gpa, self.io, accepted, st.size, self.root_dir) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.Storage, error.Corrupt => return error.ServerStorage,
};
self.dropSnapshot();
self.file.close(self.io);
self.file.* = accepted.file;
adopted = true;
self.snapshot = fresh;
fresh.classify_sidecar = .{ .io = self.io, .dir = self.root_dir, .graph = &self.graph };
self.graph_gpa = gpa;
// Resolve the cluster index over the new snapshot, then drop
// the cluster plaintext it memoised: the index keeps only names and bits.
// The cluster scan reads every artifact once and keeps none: the
// classifier's view, not the memoizing one, so a snapshot build does
// not pin the store's whole plaintext before the first round.
self.clusters = loadClusterIndex(gpa, self.io, self.root_dir, &fresh.log, fresh.classifyStore()) catch null;
fresh.releaseTransient();
self.snapshot_log_size = st.size;
self.snapshot_log_mtime_ns = st.mtime.nanoseconds;
self.loads += 1;
return fresh.store();
}
/// The accept loop's between-connections maintenance hook (see
/// `serve.Responder.maintainFn`). Runs after a connection has closed and
/// before the next accept, so no connection is open to charge its O(store)
/// work to. It re-primes the cache via the same stat-gated `baseSnapshot`:
/// after a pure read round the stat is unchanged and this is one `stat`; after
/// a round that appended (a push) the log grew, so this rebuilds the snapshot
/// the pushing round deliberately left stale rather than pay inside its
/// deadline. A failed rebuild is swallowed for the same reason
/// `baseSnapshot` leaves the cache coherent on failure: `baseSnapshot` drops
/// the old snapshot only after a fresh one is fully built and updates
/// `snapshot_log_size` only on success, so a failed rebuild RETAINS the
/// previous (stale) snapshot with its old size — the stat gate keeps
/// mismatching until a rebuild succeeds, and stale content is never served in
/// the meantime. The next round (or the next `maintain`) retries, still
/// outside any earlier round's budget. Type-erased to match the `maintainFn`
/// seam.
fn maintain(ctx_ptr: *anyopaque, gpa: std.mem.Allocator) void {
const self: *ServeCtx = @ptrCast(@alignCast(ctx_ptr));
// A signed erasure passing its not-before writes nothing, so no stat
// moves: ask the snapshot's clock. On a flip, reclaim the bytes (the
// rename then forces the rebuild below) and drop the snapshot either
// way, so the next round masks what is now erased.
if (self.snapshot) |snap| if (snap.log.refreshErasureClock()) {
self.snapshot_log_size = 0;
};
const before = self.snapshot_log_size;
if (self.baseSnapshot(gpa)) |_| {} else |_| {}
// The reclaim a pushed or flipped erasure calls for runs here, never
// inside a request: the rewrite is O(store), and between connections
// no deadline is running. The rename is noticed by the next
// `baseSnapshot`, which rebuilds over the reclaimed generation.
if (self.snapshot) |snap| if (erasedBytesHeld(&snap.log) or erasureNeedsApplied(&snap.log)) {
_ = applySessionErasures(gpa, self.io, self.root_dir, null, "serve", &snap.log, &.{}, true);
if (self.baseSnapshot(gpa)) |_| {} else |_| {}
};
// A push left the zero-parse image stale, and the next
// protected push would re-derive it inside its own deadline. Derive it
// here instead, between connections, where O(store) is allowed — and
// only when the log actually grew, so a pull-heavy fronted server does
// not pay an image load per connection. Only a fronted server has a
// resolver to warm; a failure is retried by the round itself, which
// derives on demand and fails closed on a fault.
if (self.fronted and self.snapshot_log_size != before) {
var repo: Repository = undefined;
if (Repository.open(&repo, gpa, self.io, self.root_dir, .{ .mode = .fast_read })) |_| {
repo.deinit(gpa);
} else |_| {}
}
}
};
/// The `serve.Responder` seam: snapshot the repository into an in-memory store,
/// answer the framed request over it, and — when the request pushed new content —
/// make that content durable in the served repository's on-disk log (sync §3.3).
///
/// `respond` stays sans-IO: it only `put`s pushed artifacts into the snapshot
/// store it is given. The durable write is this serve-layer's job and reuses the
/// idempotent `persistStore` (a re-push of an already-stored hash appends nothing
/// — content is addressed by hash), the very path clone/pull persist through. A
/// pure gimme/pull request makes nothing new servable, so the overlay stays
/// empty and the log is never reopened; only a genuine push touches disk.
///
/// `respond` is answered over a per-request WRITE OVERLAY of the cached snapshot
/// (`repostate.OverlayStore`), never over the snapshot itself: the responder
/// interns phantoms and upgrades entries as it works, and letting those survive
/// into the next round changes what that round serves. Reads fall through to the
/// snapshot, so reuse costs nothing; writes are confined to the overlay, and the
/// persist pass — which is idempotent over everything already in the log — can
/// only append what the overlay holds.
///
/// The pushed bytes were size-validated by `respond`'s request scan before they
/// entered the store, so `persistStore` only ever writes well-formed content, and
/// a mid-write fault surfaces before `commit`, never as a partial log append.
pub fn serveAnswer(ctx_ptr: *anyopaque, gpa: std.mem.Allocator, request_container: []const u8, cookie: ?[]const u8, front: serve_mod.Front, request_compressed: bool) serve_mod.AnswerError!serve_mod.XferReply {
const ctx: *ServeCtx = @ptrCast(@alignCast(ctx_ptr));
return serveAnswerInner(ctx, gpa, request_container, cookie, front, request_compressed) catch |e| {
// NAME THE FAILURE. `serve.zig` collapses every AnswerError into one
// bare status -- `ServerStorage`, `OutOfMemory` and `ResponseTooLarge`
// all become 500 with no body and no log line -- so an operator (or a
// bench harness) sees "HTTP 500" and has no way to learn which of three
// unrelated faults produced it. This is the server-side half of naming
// the status the client now reports; without both ends a 500 is a dead
// end for anyone diagnosing from the outside.
//
// Single funnel on purpose: every `AnswerError` this responder can
// produce passes through here, so a future cause is reported without a
// second edit. Diagnostics only -- the error is re-raised unchanged and
// the status the peer sees does not move.
if (ctx.diag) |w| {
w.print("zit serve: request failed: {s}\n", .{@errorName(e)}) catch {};
w.flush() catch {};
}
return e;
};
}
fn serveAnswerInner(ctx: *ServeCtx, gpa: std.mem.Allocator, request_container: []const u8, cookie: ?[]const u8, front: serve_mod.Front, request_compressed: bool) serve_mod.AnswerError!serve_mod.XferReply {
const reply = try serveRound(ctx, gpa, request_container, cookie, front, request_compressed);
// Past this point nothing borrows the snapshot: the overlay is gone with
// `serveRound`'s frame and the reply owns its own bytes. Dropping the
// plaintext memo is bounded (it frees only what this round inflated), so it
// is safe inside the deadline.
//
// A round that appended (a push) has left the snapshot stale — it still
// describes the pre-push log. It is NOT rebuilt here: an O(store) rebuild
// inside the reply's connection deadline is exactly the failure this avoids. The
// rebuild is the accept loop's job, via `ServeCtx.maintain`, run after this
// connection closes and before the next accept — outside every deadline. The
// append-only stat gate in `baseSnapshot` makes the stale snapshot self-
// correcting: the next `baseSnapshot` (in `maintain` or the next round) sees
// the grown size and rebuilds, so no `appended` signal needs to be threaded
// out of the round.
//
// A post-scan read fault this round mapped a held artifact to null. The §8.2
// clone pager skips such a rid and still reports the sequence complete
// (NEXT 0), silently finishing a clone MISSING an artifact — a failure the
// copy-based prime could not produce (a fault surfaced at prime, and a
// retained-but-uninflatable container was still served verbatim). Read the
// flag BEFORE releasing the round's memos (which clears it), then surface it
// as a storage error so the client retries; the next round re-reads.
const faulted = if (ctx.snapshot) |s| s.read_fault else false;
ctx.releaseSnapshotPlaintext();
if (faulted) {
gpa.free(reply.body);
if (reply.diverted) |d| gpa.free(d);
return error.ServerStorage;
}
return reply;
}
/// One round over a per-request write overlay. Split out of `serveAnswer` so the
/// overlay — which borrows the cached snapshot — is provably destroyed before
/// `serveAnswer` touches that snapshot's storage. A round that pushes new content
/// persists it durably here; the snapshot it read from is left describing the
/// pre-push log, and `baseSnapshot`'s append-only stat gate rebuilds it on the
/// next call (in the accept loop's `maintain`, never inside this round's
/// deadline), so this round signals nothing back to its caller.
fn serveRound(
ctx: *ServeCtx,
gpa: std.mem.Allocator,
request_container: []const u8,
cookie: ?[]const u8,
front: serve_mod.Front,
request_compressed: bool,
) serve_mod.AnswerError!serve_mod.XferReply {
var overlay = repostate.OverlayStore.init(gpa, try ctx.baseSnapshot(gpa));
defer overlay.deinit();
// sync §3.3 L553-556 / §8.8 L1839-1841 — answer this round with THIS
// snapshot's shun table. `ctx.server` is the caller's long-lived config and
// stays const; the per-round copy carries the fields that are properties of
// the snapshot rather than of the server, so the reply's phantom scan never
// begs for an artifact this repository has shunned (a client `igot` for a
// shunned hash still interns its phantom — §3.3 r24(1) L537-540 — it is just
// never requested).
// `ctx.baseSnapshot` above published it — the rebuild path assigns
// `self.snapshot`, the cached path requires it non-null — so the null arm is
// unreachable today. It is a CHECKED error rather than a fail-open `.none`
// because "the filter is not skipped" must hold in a release build: a future
// ctx that primes a store without publishing the snapshot, or an early-out
// added above, must fail the round rather than silently serve with no shun
// table and re-beg every shunned hash with nothing failing.
//
// submanifests §8.1/§7.2 — the same per-round freshness arms the send gate.
// The long-lived `ctx.server` is a build identity (version, servercode,
// project code) and outlives every snapshot; the seen-submanifest indicator,
// the §8.1 emission setting, and the two settings this server only REPORTS
// are facts about the CURRENT log and are re-read whenever the snapshot is.
// Copying per round is what keeps them from drifting: a push that stores this
// repository's first tree arms the gate for the next round rather than for
// the next process, and a `zit submanifest enable`/`retune` against a served
// repository is obeyed by the next round rather than the next process. These
// read the snapshot unconditionally for the same reason the shun table does —
// serving a stale default is the failure, not a fallback.
var round_server = ctx.server.*;
// sync §3.2/§6.4 — the round's time for the reply's timestamp comment;
// the sans-IO server has no clock of its own.
var reply_time_buf: [19]u8 = undefined;
const now_s: i64 = @intCast(@divFloor(std.Io.Timestamp.now(ctx.io, .real).nanoseconds, std.time.ns_per_s));
round_server.reply_time = cli.formatWriterTimestamp(now_s, &reply_time_buf);
const snapshot = ctx.snapshot orelse return error.ServerStorage;
// The shun table widened by this store's thinned versions, re-read per
// round like the cone below: the round neither begs a pushing peer for a
// version `purge artifacts` removed nor stores a copy it sends. Only the
// admission set widens; the `/shun` rows a peer requests stay the table.
var thinned_set = ThinnedShunSet.load(gpa, ctx.io, ctx.root_dir, snapshot.shun.shunSet()) catch
return error.ServerStorage;
defer thinned_set.deinit(gpa);
round_server.shun = thinned_set.shunSet();
// §9.3 r28 — and the row view, for a `reqconfig /shun`.
round_server.shun_rows = snapshot.shun_rows;
round_server.setting_rows = snapshot.setting_rows;
// Sparse-cone RFC section 6.2 -- cone-scoped requests answer filtered.
round_server.cone_classifier = snapshot.coneClassifier();
// Horizon draft section 6.2.6 -- the log position this round serves from.
round_server.horizon_cursor = snapshot.rids.len;
// Bounded announcement: the clusters carry what they name.
if (ctx.clusters) |*c| {
round_server.clustered = &c.clustered;
round_server.cluster_names = c.cluster_names;
}
// This server's own content policy, re-read per round like every
// other setting here, so `zit settings binary-glob ...` against a served
// repository is obeyed by the next round rather than the next process.
//
// Resolved from the SERVER's settings, never from the artifacts arriving in
// the push: a push carrying its own policy would otherwise arrive bearing
// permission to land. The versioned tier is still consulted, and that is
// deliberate -- it reads the server's own working tree, which a push does
// not touch, so adopting a project's policy stays an act the operator takes
// by updating, exactly as `zit trust` is for before-commit consent.
var policy_arena = std.heap.ArenaAllocator.init(gpa);
defer policy_arena.deinit();
if (ctx.amb) |amb| {
// The repository tier comes from the snapshot's per-build
// config read, NOT from `resolveSetting`, whose repository read opens
// the store and re-scans every frame header. That scan per setting
// per round is what made a 1.17M-artifact clone take half an hour.
// The snapshot's (size, mtime) key preserves the per-round freshness
// contract: a settings write grows the log and rebuilds the copy.
const pa = policy_arena.allocator();
const repo_bin: ?[]const u8 = if (snapshot.policy_binary_glob.len != 0) snapshot.policy_binary_glob else null;
const repo_crlf: ?[]const u8 = if (snapshot.policy_crlf_glob.len != 0) snapshot.policy_crlf_glob else null;
const bin = resolveSettingWith(ctx.io, pa, ctx.root_dir, .{ .environ = amb.environ }, .binary_glob, repo_bin) catch
zit.settings.Resolved{ .value = "", .source = .default };
const crlf = resolveSettingWith(ctx.io, pa, ctx.root_dir, .{ .environ = amb.environ }, .crlf_glob, repo_crlf) catch
zit.settings.Resolved{ .value = "", .source = .default };
round_server.push_policy = .{ .binary_glob = bin.value, .crlf_glob = crlf.value };
}
// Sparse-cone RFC section 5.3 -- a sparse origin refuses clones it does
// not cover. Read per round like every other snapshot-freshness fact: an
// `update --cone` against the served tree is obeyed by the next round.
var origin_cone = zit.repocache.readStoreCone(gpa, ctx.io, ctx.root_dir);
defer if (origin_cone) |*c| c.deinit(gpa);
round_server.origin_cone = if (origin_cone) |*c| c else null;
// sync §7.7 L1463-1467 — the other half of the same admission predicate, from
// the same snapshot, so `ingest` never pairs this round's shun table with a
// stale policy.
round_server.hash_policy = snapshot.hash_policy;
round_server.seen_submanifest = snapshot.seen_submanifest;
round_server.submanifests_enabled = snapshot.submanifests_enabled;
round_server.submanifest_k = snapshot.submanifest_k;
round_server.submanifest_auto_retune = snapshot.submanifest_auto_retune;
round_server.git_email_domain = snapshot.git_email_domain;
if (snapshot.project_code.code()) |code| round_server.project_code = code;
// The front's membership rule for THIS push, and the resolver it
// needs. Both set together: a rule with no resolver fails closed in
// `pushProtectVerdict`, which is the right answer to a misconfiguration but
// not a state this code should be able to produce. The resolver opens the
// repository lazily -- a round that pushes nothing protected never pays --
// and the view it opens reads the on-disk log, which every earlier round
// already persisted, so a parent pushed last round resolves; a parent in
// this round is resolved in-round by the rule itself.
var resolver = RoundBranchResolver{ .ctx = ctx, .gpa = gpa };
defer resolver.deinit();
// Horizon draft section 5.2 -- every served repository can mint seeds for a
// structural request; the resolver opens the repository lazily, so a round
// that asks for none pays nothing.
round_server.seed_minter = resolver.seedMinter();
// The resolver serves every round now, not only a protected one: the
// seed-derived cancel check and merge-base answers need it, and it opens
// the repository only when a round actually asks.
round_server.branch_of = resolver.resolver();
if (front.protect) |globs| if (globs.len != 0) {
round_server.push_policy.protect_globs = globs;
};
// A divert means nothing without a rule to divert from, so the front's
// login is read only under one.
var ledger: ?RefusalLedger = null;
defer if (ledger) |*l| l.deinit();
if (front.divert_login) |login| if (round_server.push_policy.protect_globs.len != 0) {
const now_ms: u64 = @intCast(@divFloor(std.Io.Timestamp.now(ctx.io, .real).nanoseconds, std.time.ns_per_ms));
ledger = try RefusalLedger.load(gpa, ctx.io, ctx.root_dir, login, now_ms);
round_server.divert = .{ .login = login, .now_ms = now_ms, .ledger = ledger.?.ledger() };
};
var reply = try serve_mod.handleXfer(gpa, &round_server, overlay.store(), request_container, cookie, request_compressed);
errdefer gpa.free(reply.body);
defer {
zit.sync.freeErasures(gpa, reply.erasures);
gpa.free(reply.erasures);
reply.erasures = &.{};
}
if (ledger) |*l| {
l.save();
reply.diverted = try l.header(gpa);
}
errdefer if (reply.diverted) |d| gpa.free(d);
// sync §9.3 r33 — an AUTHORIZED pushed config card's settings, applied to
// the served repository here because this is where the config lives; the
// responder is sans-IO and only reports the decision. Unreachable today by
// construction: `runServe` configures no credential, so `Server.hasAdmin` is
// false for every requester and every push is rejected (the e2e pins that).
// It is wired anyway because the alternative — a server that can AUTHORIZE a
// push and then silently drop it — is the failure mode worth ruling out.
if (reply.config_apply.any()) {
updateConfig(gpa, ctx.io, ctx.root_dir, .{
.enable_submanifests = reply.config_apply.enable,
.submanifest_k = reply.config_apply.k,
.submanifest_auto_retune = reply.config_apply.auto_retune,
.git_email_domain = if (reply.config_apply.git_email_domain) |*d| d.slice() else null,
}) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.StoreBusy => return error.ServerBusy,
error.Storage, error.Corrupt => return error.ServerStorage,
};
}
// Only what the round ADDED is persisted, and the walk starts past the
// snapshot: the base rids already have a durable form, and an upgrade the
// round retained for one of them (a delta target it reconstructed while
// serving) is advisory. Walking from rid 1 read every holding once to
// early-return it -- O(store) after every round that retained anything,
// 300 s on a 1.25M-entry store, after every structural clone and every
// push -- and re-wrote each reconstructed form as a new frame, so the store
// grew by tens of megabytes per clone served.
if (overlay.added.store().heldCount() > 0) {
// submanifests §7.1 — the durable half of the push-side duty; the
// reply-visible half is `sync.ingest`, which phantomizes into the very
// store the §3.2 walk reads. The gap COUNT is discarded on purpose: a
// stateless server (§3.8/§8.9) has no operator to report to, and §7.1
// asks for a phantom, not a diagnostic.
const stored = persistStoreAdopting(gpa, ctx.io, ctx.root_dir, overlay.store(), null, @intCast(overlay.base_count), reply.adopt_project.code()) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.StoreBusy => return error.ServerBusy,
error.Storage, error.Corrupt => return error.ServerStorage,
};
// sync §8.5 L1688-1689 — another first push adopted the store between
// this round's read and its write: the reply that accepted this push
// is replaced by the refusal it now earns.
if (stored == null) {
var card_buf: [2 * zit.sync.wrong_project_text.len + 16]u8 = undefined;
const card = zit.sync.writeSignalCard(.err, zit.sync.wrong_project_text, card_buf[0 .. card_buf.len - 1]);
card_buf[card.len] = '\n';
const refusal = zit.container.encode(gpa, card_buf[0 .. card.len + 1], .default) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.InputTooLarge => unreachable,
};
gpa.free(reply.body);
reply.body = refusal;
reply.content_type = serve_mod.xfer_media_type;
if (reply.diverted) |d| gpa.free(d);
reply.diverted = null;
return reply;
}
}
// Pushed signed erasures the responder verified against this
// repository's pinned key, recorded after the round's content. Their
// bytes are reclaimed by `maintain`, between connections.
if (reply.erasures.len != 0) _ = applySessionErasures(gpa, ctx.io, ctx.root_dir, null, "serve", null, reply.erasures, false);
return reply;
}
/// The served repository's memory of divert refusals (`sync.DivertLedger`),
/// one line per refusal: `MS LOGIN HASH`, the login fossil-encoded. Loaded
/// for one request's login, written back only when the round added to it,
/// with lines past `refusal_ttl_ms` dropped on the way.
const RefusalLedger = struct {
gpa: std.mem.Allocator,
io: std.Io,
dir: std.Io.Dir,
now_ms: u64,
/// The request's login, encoded as it is stored.
login: []u8,
/// Every unexpired line, every login's, ready to write back.
lines: std.ArrayListUnmanaged(u8) = .empty,
/// This login's refused check-ins.
mine: std.StringHashMapUnmanaged(void) = .empty,
added: bool = false,
moves: std.ArrayListUnmanaged(zit.sync.DivertMove) = .empty,
arena: std.heap.ArenaAllocator,
/// How long a refusal counts as the pusher having been told.
const refusal_ttl_ms: u64 = 7 * 24 * 60 * 60 * 1000;
/// How far ahead of now a line may be stamped and still count: a clock
/// stepped back must not make a refusal last forever.
const refusal_skew_ms: u64 = 24 * 60 * 60 * 1000;
/// The most lines kept; the oldest go first. A pusher refused this often
/// in a week is warned again, which is the only cost.
const refusal_lines_max: usize = 10_000;
fn load(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, login: []const u8, now_ms: u64) error{OutOfMemory}!RefusalLedger {
var self: RefusalLedger = .{ .gpa = gpa, .io = io, .dir = dir, .now_ms = now_ms, .login = undefined, .arena = std.heap.ArenaAllocator.init(gpa) };
errdefer self.arena.deinit();
const a = self.arena.allocator();
const enc = try a.alloc(u8, 2 * login.len);
self.login = @constCast(zit.artifact.encodeEscapes(login, enc));
const blob = (try zit.repocache.loadMember(gpa, io, dir, zit.repocache.refusals_member)) orelse return self;
defer gpa.free(blob);
// Newest lines are at the end; keep at most the last `refusal_lines_max`.
var total: usize = std.mem.count(u8, blob, "\n");
var it = std.mem.splitScalar(u8, blob, '\n');
while (it.next()) |line| {
if (total > refusal_lines_max) {
total -= 1;
continue;
}
var f = std.mem.splitScalar(u8, line, ' ');
const ms = std.fmt.parseInt(u64, f.next() orelse continue, 10) catch continue;
const who = f.next() orelse continue;
const hash = f.next() orelse continue;
if (f.next() != null) continue;
if (now_ms -| ms > refusal_ttl_ms or ms -| now_ms > refusal_skew_ms) continue;
try self.lines.appendSlice(a, line);
try self.lines.append(a, '\n');
if (std.mem.eql(u8, who, self.login)) try self.mine.put(a, try a.dupe(u8, hash), {});
}
return self;
}
fn deinit(self: *RefusalLedger) void {
self.arena.deinit();
self.* = undefined;
}
fn ledger(self: *RefusalLedger) zit.sync.DivertLedger {
return .{ .ctx = self, .refusedFn = refused, .recordFn = record, .divertedFn = diverted };
}
fn refused(ctx: *anyopaque, hash: []const u8) bool {
const self: *RefusalLedger = @ptrCast(@alignCast(ctx));
return self.mine.contains(hash);
}
fn record(ctx: *anyopaque, hash: []const u8) error{OutOfMemory}!void {
const self: *RefusalLedger = @ptrCast(@alignCast(ctx));
const a = self.arena.allocator();
try self.lines.print(a, "{d} {s} {s}\n", .{ self.now_ms, self.login, hash });
try self.mine.put(a, try a.dupe(u8, hash), {});
self.added = true;
}
fn diverted(ctx: *anyopaque, mv: zit.sync.DivertMove) error{OutOfMemory}!void {
const self: *RefusalLedger = @ptrCast(@alignCast(ctx));
const a = self.arena.allocator();
try self.moves.append(a, .{ .hash = try a.dupe(u8, mv.hash), .branch = try a.dupe(u8, mv.branch), .protected = try a.dupe(u8, mv.protected) });
}
/// Write back what this round added. Advisory: a lost write costs the
/// pusher one more refusal.
fn save(self: *RefusalLedger) void {
if (self.added) zit.repocache.storeRefusals(self.io, self.dir, self.lines.items);
}
/// The `x-zit-diverted` values for this round's moves, one per line
/// (`serve` sends one header per line), or null. Each field is
/// fossil-encoded, as on the sync wire, so a branch name carrying a space,
/// a comma or a newline can neither split a field nor reach the front as
/// a header of its own.
fn header(self: *RefusalLedger, gpa: std.mem.Allocator) error{OutOfMemory}!?[]u8 {
if (self.moves.items.len == 0) return null;
var out: std.ArrayListUnmanaged(u8) = .empty;
errdefer out.deinit(gpa);
for (self.moves.items, 0..) |mv, i| {
if (i != 0) try out.append(gpa, '\n');
for ([_][]const u8{ mv.hash, mv.branch, mv.protected }, 0..) |field, k| {
if (k != 0) try out.append(gpa, ' ');
const enc = try gpa.alloc(u8, 2 * field.len);
defer gpa.free(enc);
try out.appendSlice(gpa, zit.artifact.encodeEscapes(field, enc));
}
}
return try out.toOwnedSlice(gpa);
}
};
test "serve: the x-zit-diverted value is one fossil-encoded line per move, so no branch name can split it" {
const gpa = std.testing.allocator;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var ledger = try RefusalLedger.load(gpa, std.testing.io, tmp.dir, "jan", 1000);
defer ledger.deinit();
const l = ledger.ledger();
try l.diverted(.{ .hash = "aa", .branch = "attempt/jan/aa", .protected = "release, x\nx-evil: 1" });
try l.diverted(.{ .hash = "bb", .branch = "attempt/jan/bb", .protected = "trunk" });
const value = (try ledger.header(gpa)).?;
defer gpa.free(value);
try std.testing.expectEqualStrings("aa attempt/jan/aa release,\\sx\\nx-evil:\\s1\nbb attempt/jan/bb trunk", value);
}
test "serve: a refusal record expires after a week, or when stamped too far ahead" {
const gpa = std.testing.allocator;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const day: u64 = 24 * 60 * 60 * 1000;
const now: u64 = 100 * day;
{
var ledger = try RefusalLedger.load(gpa, std.testing.io, tmp.dir, "jan", now);
defer ledger.deinit();
try ledger.ledger().record("fresh");
ledger.save();
}
// Rewrite with a stale line and a future one around the fresh one.
const blob = try std.fmt.allocPrint(gpa, "{d} jan stale\n{d} jan fresh\n{d} jan future\n", .{ now - 8 * day, now, now + 2 * day });
defer gpa.free(blob);
zit.repocache.storeRefusals(std.testing.io, tmp.dir, blob);
var ledger = try RefusalLedger.load(gpa, std.testing.io, tmp.dir, "jan", now);
defer ledger.deinit();
const l = ledger.ledger();
try std.testing.expect(l.refused("fresh"));
try std.testing.expect(!l.refused("stale"));
try std.testing.expect(!l.refused("future"));
}
/// `sync.BranchResolver` over the served repository's own view,
/// opened on first use and only for the round. `.fast_read` takes the
/// zero-parse image when it is fresh (`ServeCtx.maintain` keeps it so) and
/// derives when it is not, so the answer is crosslink's own in either case --
/// which is the point: "which branch does this check-in resolve to" has one
/// authority, and this is it, not a re-implementation over raw tags.
/// Horizon draft section 5.2.2 -- a seed's D card in whole seconds: the
/// latest tag event it summarizes, rounded UP, so the seed is never earlier
/// than an event with a sub-second time, and every origin of one repository
/// writes the same D (and so mints the same seed name) for the same state.
fn seedSeconds(latest_ms: u64) u64 {
return std.math.divCeil(u64, latest_ms, 1000) catch unreachable;
}
test "horizon §5.2.2: a seed is dated at its latest tag event rounded up to a whole second" {
try std.testing.expectEqual(@as(u64, 0), seedSeconds(0));
try std.testing.expectEqual(@as(u64, 2), seedSeconds(1001));
try std.testing.expectEqual(@as(u64, 2), seedSeconds(1999));
try std.testing.expectEqual(@as(u64, 2), seedSeconds(2000));
}
const RoundBranchResolver = struct {
ctx: *ServeCtx,
gpa: std.mem.Allocator,
/// Borrowed from the serve context, which owns it across rounds.
repo: *Repository = undefined,
opened: bool = false,
failed: bool = false,
/// Horizon draft section 5.2 -- the seed minted this round, memoized so a
/// reply that asks twice (igot scan and clone walk both advertise) hashes
/// once. Owned; freed with the resolver.
seed_bytes: ?[]u8 = null,
seed_hash: [64]u8 = undefined,
seed_hash_len: u8 = 0,
/// What the memoized seed was minted for: a digest of C and the entries.
seed_for: [32]u8 = undefined,
fn resolver(self: *RoundBranchResolver) zit.sync.BranchResolver {
return .{ .ctx = self, .branchOfFn = branchOf, .mainBranchFn = mainBranch, .tagsOfFn = tagsOf, .mergeBaseFn = mergeBase, .resolveHorizonFn = resolveHorizon };
}
/// Horizon draft section 6.2.4 -- Fossil's pivot of `primary` against
/// `secondaries` over this repository's view, as a hash borrowed from it;
/// null when they share no ancestor. A check-in this view does not hold
/// is `Unavailable`: "no common ancestor" would be a claim about history
/// it cannot see.
fn mergeBase(ctx_ptr: *anyopaque, gpa: std.mem.Allocator, primary: []const u8, secondaries: []const []const u8) error{ Unavailable, OutOfMemory }!?[]const u8 {
const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
const repo = try self.open();
if (secondaries.len > zit.sync.max_mergebase_secondaries) return error.Unavailable;
var rids: [zit.sync.max_mergebase_secondaries]repostate.Rid = undefined;
for (secondaries, rids[0..secondaries.len]) |name, *rid| rid.* = try heldCheckin(repo, name);
const base = (try repo.pivotOf(gpa, try heldCheckin(repo, primary), rids[0..secondaries.len])) orelse return null;
return repo.hashOf(base);
}
/// Horizon draft section 6.2.7 -- resolved from this origin's own
/// derivation, as `zit info NAME` would, then DEPTH primary parents back.
fn resolveHorizon(ctx_ptr: *anyopaque, _: std.mem.Allocator, name: []const u8, depth: u32) error{ Unavailable, OutOfMemory }!?zit.sync.HorizonResolved {
const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
const repo = try self.open();
const pick = repo.view.state.horizonCheckin(name, depth) catch |e| switch (e) {
error.NotFound => return null,
error.OutOfMemory => return error.OutOfMemory,
};
return .{ .hash = repo.hashOf(pick.rid), .steps = pick.steps };
}
fn heldCheckin(repo: *Repository, name: []const u8) error{Unavailable}!repostate.Rid {
const rid = repo.lookup(name) orelse return error.Unavailable;
if (!repo.view.state.hasEvent(rid)) return error.Unavailable;
return rid;
}
fn seedMinter(self: *RoundBranchResolver) zit.sync.SeedMinter {
return .{ .context = self, .mintFn = mintSeed };
}
fn deinit(self: *RoundBranchResolver) void {
if (self.seed_bytes) |b| self.gpa.free(b);
self.* = undefined;
}
/// Horizon draft section 5.2 -- the seed for C: the tag rows in force at C,
/// and at each check-in of K whose primary parent lies below the horizon
/// (section 5.2.1), in this repository's own derivation, composed as one
/// control artifact signed by the serving login. Null when C is not a held
/// check-in or the repository cannot be opened; the reply then carries no
/// seed and advertises content (section 6.3).
fn mintSeed(ctx_ptr: *anyopaque, gpa: std.mem.Allocator, c_hash: []const u8, rule: zit.cone.HorizonRule, entries: []const []const u8) ?zit.sync.Seed {
const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
var key: [32]u8 = undefined;
var hasher = std.crypto.hash.sha2.Sha256.init(.{});
hasher.update(c_hash);
hasher.update(rule.name());
for (entries) |e| {
hasher.update(" ");
hasher.update(e);
}
hasher.final(&key);
if (self.seed_bytes != null and std.mem.eql(u8, &self.seed_for, &key)) {
return .{ .hash = self.seed_hash[0..self.seed_hash_len], .bytes = self.seed_bytes.? };
}
const repo = self.open() catch return null;
const rid = repo.lookup(c_hash) orelse return null;
if (!repo.view.state.hasEvent(rid)) return null;
var targets: std.ArrayListUnmanaged(zit.sync.SeedTarget) = .empty;
defer {
for (targets.items) |t| gpa.free(t.rows);
targets.deinit(gpa);
}
// Horizon draft section 5.2.2 -- dated at the latest tag event in the
// repository, cancels included, not at minting: two mints over
// unchanged state then produce the same bytes and name, so a client's
// offered name matches and no seed crosses the wire; and no change to
// tag state moves D earlier, so a clone's D floor never refuses a
// re-seed. A shun can remove the newest tag rows, so D is also never
// earlier than the latest D this origin has minted. Entries with no
// tag rows in force mint no seed at all (`composeSeed` refuses), and
// the request is served at the content level.
const floor_ms = zit.repocache.readSeedFloor(gpa, self.ctx.io, self.ctx.root_dir);
var latest_ms: u64 = @max(floor_ms, repo.view.state.latestTagEvent());
for ([_][]const []const u8{ &.{c_hash}, entries }) |names| for (names) |name| {
const r = repo.lookup(name) orelse continue;
if (!repo.view.state.hasEvent(r)) continue;
const rows = repo.view.state.tagsOf(gpa, r) catch return null;
targets.append(gpa, .{ .hash = name, .rows = rows }) catch {
gpa.free(rows);
return null;
};
for (rows) |row| latest_ms = @max(latest_ms, row.mtime);
};
var ts_buf: [19]u8 = undefined;
const ts = cli.formatWriterTimestamp(@intCast(seedSeconds(latest_ms)), &ts_buf);
const bytes = zit.sync.composeSeed(gpa, targets.items, .{ .hash = c_hash, .rule = rule }, ts, zit.sync.seed_user) catch return null;
if (latest_ms > floor_ms) zit.repocache.raiseSeedFloor(gpa, self.ctx.io, self.ctx.root_dir, latest_ms);
if (self.seed_bytes) |old| self.gpa.free(old);
self.seed_bytes = bytes;
const name = artifact.artifactName(.sha3_256, bytes, &self.seed_hash);
self.seed_hash_len = @intCast(name.len);
self.seed_for = key;
return .{ .hash = self.seed_hash[0..self.seed_hash_len], .bytes = bytes };
}
/// Open once; a failure is sticky for the round so the rule fails closed
/// on every question rather than retrying a broken read per artifact.
fn open(self: *RoundBranchResolver) error{Unavailable}!*Repository {
if (self.failed) return error.Unavailable;
if (!self.opened) {
self.repo = self.ctx.roundRepo(self.gpa) catch {
self.failed = true;
return error.Unavailable;
};
self.opened = true;
}
return self.repo;
}
fn branchOf(ctx_ptr: *anyopaque, hash: []const u8) error{Unavailable}!?[]const u8 {
const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
const repo = try self.open();
const rid = repo.lookup(hash) orelse return null;
// `branchOf` is defined on check-ins; a P card naming a blob (or a
// phantom) resolves to nothing rather than tripping its precondition.
if (!repo.view.state.hasEvent(rid)) return null;
return repo.branchOf(rid);
}
fn mainBranch(ctx_ptr: *anyopaque) error{Unavailable}![]const u8 {
const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
const repo = try self.open();
return repo.view.main_branch;
}
fn tagsOf(ctx_ptr: *anyopaque, gpa: std.mem.Allocator, hash: []const u8) error{ Unavailable, OutOfMemory }!?[]repostate.RepoState.TagEntry {
const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
const repo = try self.open();
const rid = repo.lookup(hash) orelse return null;
if (!repo.view.state.hasEvent(rid)) return null;
return try repo.view.state.tagsOf(gpa, rid);
}
};
/// Snapshot every stored artifact from the persisted log into `ms`, skipping
/// config frames (not artifacts). A content-bearing frame becomes a held entry;
/// a content-absent frame becomes a phantom — exactly the held/phantom split
/// `respond` walks (sync §3.2/§3.3).
///
/// The log keys frames by the RAW binary digest, but the sync wire names an
/// artifact by that digest's lowercase hex (sync §3.3 — a `file`/`igot`/`gimme`
/// HASH is 40/64 hex characters). The store the responder walks must therefore
/// hold the hex name, or `respond` would emit non-hex bytes that break the
/// peer's card tokenizer. Every hash crossing this boundary is hex-encoded once,
/// here — the single place binary-log identity becomes wire identity.
fn loadContentStore(
gpa: std.mem.Allocator,
log: *logstore.LogStore,
ms: *repostate.MemStore,
) serve_mod.AnswerError!void {
const rids = log.ridsInPersistedOrder(gpa) catch return error.OutOfMemory;
defer gpa.free(rids);
for (rids) |rid| {
if (log.kindOf(rid) == .config) continue;
var name_buf: [2 * digest_len]u8 = undefined;
const name = digestToWireName(log.hashOf(rid), &name_buf);
// sync §4.1/§7.2 — copy the stored container into the snapshot verbatim
// so the clone serves it without inflating here and re-compressing at
// serve. `wire()` is null only for a `.raw` frame or a phantom; those
// fall back to the plaintext path below. A `.zlib` frame carries the
// full form; a `.delta` frame carries the stored delta container plus
// its basis name and reconstructed size (the §7.2 USIZE, delta §3.2).
var maybe_wire = log.wire(gpa, rid) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.Storage, error.Corrupt => return error.ServerStorage,
};
if (maybe_wire) |*w| {
defer w.deinit(gpa);
const recorded: bool = switch (w.*) {
.full => |container| blk: {
_ = ms.putWire(name, container) catch return error.OutOfMemory;
break :blk true;
},
.delta => |d| blk: {
// sync §3.3 L553-556 — the delta form is usable only while its
// basis is. `zit shun --defer` records the row without
// rewriting the generation, so a SURVIVING frame here can be a
// delta rooted on a shunned one; that basis reads null through
// this loop's own masked doors and interns as a PHANTOM, so
// recording the delta would leave an entry the store calls held
// (`wire != null`) whose `content()` can never resolve. §3.2's
// igot walk would then announce a name no `gimme` can ever be
// answered with, and the push would spin the round with nothing
// to send. Fall through to the plaintext path instead: the
// artifact itself is NOT shunned, so `log.content` reads it
// through the frame chain by BYTE OFFSET — which the name-level
// mask does not reach — and it is snapshotted as a held full
// form. Exactly `LogIndexStore.wireImpl`'s masked-basis guard,
// stated for the client's own holdings snapshot.
const base = d.baseHash();
if (logstore.isCompleteDigest(base.len) and log.isShunned(base)) break :blk false;
// The basis frame precedes this one in the log (delta_of <
// offset), so it was already inserted at an earlier rid; its
// wire name is the hex of the base's binary digest.
var src_name_buf: [2 * digest_len]u8 = undefined;
const src_name = digestToWireName(base, &src_name_buf);
_ = ms.putWireDelta(name, d.container, src_name, d.target_size) catch return error.OutOfMemory;
break :blk true;
},
};
if (recorded) continue;
}
const maybe = log.content(gpa, rid) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.Storage, error.Corrupt => return error.ServerStorage,
};
if (maybe) |bytes| {
defer gpa.free(bytes);
_ = ms.store().put(name, bytes) catch return error.OutOfMemory;
} else {
_ = ms.store().intern(name) catch return error.OutOfMemory;
}
}
}
/// A shun set widened by the thinned list beside the served store.
const ThinnedShunSet = struct {
base: zit.sync.ShunSet,
thinned: zit.thinned.Set = .{},
fn load(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, base: zit.sync.ShunSet) zit.thinned.Error!ThinnedShunSet {
return .{ .base = base, .thinned = try zit.thinned.load(gpa, io, dir) };
}
fn deinit(self: *ThinnedShunSet, gpa: std.mem.Allocator) void {
self.thinned.deinit(gpa);
}
fn contains(context: *anyopaque, name: []const u8) bool {
const self: *const ThinnedShunSet = @ptrCast(@alignCast(context));
return self.base.contains(name) or self.thinned.contains(name);
}
fn shunSet(self: *ThinnedShunSet) zit.sync.ShunSet {
return .{ .context = @ptrCast(self), .vtable = &.{ .contains = contains } };
}
};
test "serve §3.3: a pushed file card is persisted durably into the served repository's log" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
// A fresh, empty on-disk repository (header only) — the "server" a peer pushes
// new content into. Built through the real LogStore, not seeded from fossil.
const hash_kind: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
{
var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, 0);
var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hash_kind);
defer seed.deinit(gpa);
try seed.commit();
}
// A pushed full-content file card for a 64-hex (SHA3-256 width) artifact the
// server lacks (sync §7.1: `file HASH SIZE\n` + payload; §4.1 zlib container).
// The name is the artifact's real SHA3-256 (computed by our own hasher, not
// fossil) so the server's §7.7 commit-hook recompute accepts it.
const push_body = "pushed artifact bytes\n"; // 22 bytes
var name_buf: [64]u8 = undefined;
const push_hash = zit.artifact.artifactName(.sha3_256, push_body, &name_buf);
const request_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\npush sc pc\nfile {s} {d}\n{s}", .{ push_hash, push_body.len, push_body });
defer gpa.free(request_plain);
const request = try zit.container.encode(gpa, request_plain, .default);
defer gpa.free(request);
var digest_buf: [digest_len]u8 = undefined;
const push_digest = decodeWireName(push_hash, &digest_buf).?;
const server = zit.sync.Server{ .version = serve_mod.server_version };
// Answer the push twice through the real `serve.Responder` seam over a SINGLE
// open handle (§3.8): the second answer re-reads the current on-disk log from
// the same handle and sees the first push's frame, so it is an idempotent
// re-push (content is addressed by hash — no dup frame). A stale startup
// snapshot would instead re-append the artifact; this handle is never reopened.
{
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
for (0..2) |_| {
const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
gpa.free(reply.body);
}
}
// THE PROOF: re-open the log from disk in a fresh handle; the pushed artifact
// is present with its exact content — durably stored, not discarded — and
// appears exactly once (the idempotent re-push added no second frame).
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
const st = try file.stat(io);
var fs = storage.FileStorage.init(io, file, st.size);
var log = try logstore.LogStore.openReadOnly(gpa, fs.storageFile());
defer log.deinit(gpa);
const rid = log.lookup(push_digest) orelse return error.PushedArtifactMissing;
const stored = (try log.content(gpa, rid)).?;
defer gpa.free(stored);
try std.testing.expectEqualStrings(push_body, stored);
const rids = try log.ridsInPersistedOrder(gpa);
defer gpa.free(rids);
var artifacts: usize = 0;
for (rids) |r| {
if (log.kindOf(r) != .config) artifacts += 1;
}
try std.testing.expectEqual(@as(usize, 1), artifacts);
}
test "sync §7.2/§4.1: persistStore stores received full and delta wire forms verbatim; a re-serve preserves the delta container byte-for-byte" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try d4SeedEmptyRepo(gpa, io, tmp.dir);
// Model a clone reply in §8.2 RID order: a full base cfile then a delta
// cfile against it. Names are the real SHA3-256 so the §7.7 hook accepts.
var ms = repostate.MemStore.init(gpa);
defer ms.deinit();
const s = ms.store();
const base = "the base artifact with a long shared run so the delta stays a compact copy payload distinct in size from the reconstructed target";
const target = base ++ " plus a small trailing mutation";
var bn: [64]u8 = undefined;
var tn: [64]u8 = undefined;
const base_name = zit.artifact.artifactName(.sha3_256, base, &bn);
const target_name = zit.artifact.artifactName(.sha3_256, target, &tn);
const base_container = try zit.container.encode(gpa, base, .default);
defer gpa.free(base_container);
const base_rid = try s.put(base_name, base);
try s.retain(base_rid, .{ .full = base_container });
const raw = try zit.delta.create(gpa, base, target);
defer gpa.free(raw);
const delta_container = try zit.container.encode(gpa, raw, .default);
defer gpa.free(delta_container);
const ts = try zit.delta.targetSize(raw);
const delta_rid = try s.put(target_name, target);
try s.retain(delta_rid, .{ .delta = .{ .src = base_name, .container = delta_container, .target_size = ts } });
const written = try persistStore(gpa, io, tmp.dir, ms.store(), null, 0);
try std.testing.expectEqual(@as(usize, 2), written.written);
var fs: storage.FileStorage = undefined;
var log = try d4OpenLog(gpa, io, tmp.dir, &fs);
defer fs.file.close(io);
defer log.deinit(gpa);
// The target persisted as a `.delta` frame that reconstructs to the original.
var tdig: [digest_len]u8 = undefined;
const target_digest = decodeWireName(target_name, &tdig).?;
const trid = log.lookup(target_digest).?;
try std.testing.expectEqual(logstore.FrameKind.delta, log.kindOf(trid));
const got = (try log.content(gpa, trid)).?;
defer gpa.free(got);
try std.testing.expectEqualStrings(target, got);
// Clone-of-clone: a re-serve snapshot emits the SAME delta container bytes
// (§7.2 retransmitted verbatim) — the compactness survives the second hop.
var serve_ms = repostate.MemStore.init(gpa);
defer serve_ms.deinit();
try loadContentStore(gpa, &log, &serve_ms);
const serve_rid = serve_ms.store().lookup(target_name).?;
const wf = serve_ms.store().wire(serve_rid).?;
try std.testing.expect(wf.delta != null);
try std.testing.expectEqualSlices(u8, delta_container, wf.container);
try std.testing.expectEqual(@as(u64, target.len), wf.delta.?.target_size);
}
test "submanifests §7.1/§8.1: the S-reference gap survives a RESTART, rebuilt from the durable indicator" {
// §7.1's phantom is an interned entry with no frame, "exactly as an absent
// delta source creates a source phantom" — and `LogStore.intern` states the
// consequence outright: "Phantoms never reach disk." So a restart loses
// them, and the only thing that can make them correct across one is a
// REBUILD from the durable content-bearing frames.
//
// This test is that invariant for a sweep over the whole store (start_after
// 0, as a clone or a push ingest persists): run 1 mints the gap, the process
// ends, run 2 re-derives the identical gap over a store loaded from `.zit`
// alone. Remove the rebuild (`rescan_persisted`) and run 2 reports ZERO gaps
// — a repository that quietly declares an unenumerable check-in converged.
// Sync and pull persist only what arrived; their half is the gap index
// (`subManifestGaps`) and the e2e "keeps reporting a sub-manifest gap".
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try d4SeedEmptyRepo(gpa, io, tmp.dir);
const leaf_a = "F a.txt " ++ (repeat("1", 64)) ++ "\n";
const leaf_b = "F b.txt " ++ (repeat("2", 64)) ++ "\n";
var an: [64]u8 = undefined;
var bn: [64]u8 = undefined;
const name_a = zit.artifact.artifactName(.sha3_256, leaf_a, &an);
const name_b = zit.artifact.artifactName(.sha3_256, leaf_b, &bn);
const tree = try treeManifestBytes(gpa, &.{ name_a, name_b });
defer gpa.free(tree);
var tn: [64]u8 = undefined;
const tree_name = zit.artifact.artifactName(.sha3_256, tree, &tn);
// RUN 1 — the tree lands; neither sub-manifest is held.
{
var ms = repostate.MemStore.init(gpa);
defer ms.deinit();
_ = try ms.store().put(tree_name, tree);
const first = try persistStore(gpa, io, tmp.dir, ms.store(), null, 0);
try std.testing.expectEqual(@as(usize, 1), first.written);
try std.testing.expectEqual(@as(usize, 2), first.submanifest_gaps);
}
// RESTART — nothing survives but the bytes in `.zit`.
var ms2 = repostate.MemStore.init(gpa);
defer ms2.deinit();
{
var fs: storage.FileStorage = undefined;
var log = try d4OpenLog(gpa, io, tmp.dir, &fs);
defer fs.file.close(io);
defer log.deinit(gpa);
// §8.1 — the indicator IS durable: "record a local seen-submanifest
// indicator". It is the one byte the rebuild rests on.
var oc = (try log.readConfig(gpa)) orelse return error.NoConfig;
defer oc.deinit(gpa);
try std.testing.expect(oc.config.seen_submanifest);
// …and the phantoms are NOT durable, asserted rather than assumed —
// this is the premise the whole rebuild exists to answer.
var adig: [digest_len]u8 = undefined;
try std.testing.expect(log.lookup(decodeWireName(name_a, &adig).?) == null);
// The snapshot a fresh process starts every verb from.
try loadContentStore(gpa, &log, &ms2);
}
// Only the tree came back: the store a second run works from holds no trace
// of the gap.
try std.testing.expectEqual(@as(usize, 1), ms2.store().count());
// RUN 2 — the gap is re-derived, identically, from the durable frames.
const second = try persistStore(gpa, io, tmp.dir, ms2.store(), null, 0);
try std.testing.expectEqual(@as(usize, 1), second.written);
try std.testing.expectEqual(@as(usize, 2), second.submanifest_gaps);
}
test "sync §7.2/§7.4/§3.3: a dangling reverse-delta cfile persists as a verbatim .delta frame that re-serves byte-identically" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try d4SeedEmptyRepo(gpa, io, tmp.dir);
// Fossil's clone stream: a reverse delta (the OLDER revision stored as a
// delta of the NEWER one) arrives BEFORE its basis, so it is dangling. The
// client retains the §4.1 container through the pending queue and, when the
// basis lands, persists it as a compact `.delta` — not a full re-compression.
const newer = "artifact NEWER: a long shared body kept verbatim so the reverse delta reconstructing the older revision stays a compact copy op";
const older = "artifact NEWER: a long shared body kept verbatim so the reverse delta reconstructing the older revision stays a compact copy op minus tail";
var nn: [64]u8 = undefined;
var on: [64]u8 = undefined;
const newer_name = zit.artifact.artifactName(.sha3_256, newer, &nn);
const older_name = zit.artifact.artifactName(.sha3_256, older, &on);
const newer_container = try zit.container.encode(gpa, newer, .default);
defer gpa.free(newer_container);
const raw = try zit.delta.create(gpa, newer, older); // OLDER = delta ∘ NEWER
defer gpa.free(raw);
const delta_container = try zit.container.encode(gpa, raw, .default);
defer gpa.free(delta_container);
var ms = repostate.MemStore.init(gpa);
defer ms.deinit();
var client = zit.sync.Client{ .operation = .clone, .state = .clone_round0 };
defer client.deinit(gpa);
var body: std.ArrayList(u8) = .empty;
defer body.deinit(gpa);
try body.appendSlice(gpa, "clone_seqno 0\npush 1111111111111111 aa87ea41b0bb05ba528f7a3bdba700d7e23d6318\n");
// Reverse (dangling) order: the delta cfile precedes its basis cfile.
const dh = try std.fmt.allocPrint(gpa, "cfile {s} {s} {d} {d}\n", .{ older_name, newer_name, older.len, delta_container.len });
defer gpa.free(dh);
try body.appendSlice(gpa, dh);
try body.appendSlice(gpa, delta_container);
try body.append(gpa, '\n');
const bh = try std.fmt.allocPrint(gpa, "cfile {s} {d} {d}\n", .{ newer_name, newer.len, newer_container.len });
defer gpa.free(bh);
try body.appendSlice(gpa, bh);
try body.appendSlice(gpa, newer_container);
try body.append(gpa, '\n');
_ = try client.consumeReply(gpa, ms.store(), body.items);
const written = try persistStore(gpa, io, tmp.dir, ms.store(), null, 0);
try std.testing.expectEqual(@as(usize, 2), written.written);
var fs: storage.FileStorage = undefined;
var log = try d4OpenLog(gpa, io, tmp.dir, &fs);
defer fs.file.close(io);
defer log.deinit(gpa);
// §3.3 — the older revision persisted as a `.delta`, not a full re-compression,
// and reconstructs the original bytes (delta ∘ basis).
var od: [digest_len]u8 = undefined;
const older_rid = log.lookup(decodeWireName(older_name, &od).?).?;
try std.testing.expectEqual(logstore.FrameKind.delta, log.kindOf(older_rid));
const got = (try log.content(gpa, older_rid)).?;
defer gpa.free(got);
try std.testing.expectEqualStrings(older, got);
// §7.2 — a clone-of-clone re-serve re-emits the SAME delta container byte-for-byte.
var serve_ms = repostate.MemStore.init(gpa);
defer serve_ms.deinit();
try loadContentStore(gpa, &log, &serve_ms);
const srid = serve_ms.store().lookup(older_name).?;
const wf = serve_ms.store().wire(srid).?;
try std.testing.expect(wf.delta != null);
try std.testing.expectEqualSlices(u8, delta_container, wf.container);
try std.testing.expectEqualStrings(newer_name, wf.delta.?.src_hash);
}
/// A test-only `storage.StorageFile` that wraps another and tallies the bytes
/// every `pread` actually returned — the instrument for "how many times does a
/// prime read the log?". Every other vtable method delegates verbatim, so a log
/// opened over it behaves identically while its read traffic is measured.
const CountingStorage = struct {
inner: storage.StorageFile,
read_bytes: usize = 0,
fn storageFile(self: *CountingStorage) storage.StorageFile {
return .{ .context = self, .vtable = &vtable };
}
const vtable = storage.StorageFile.VTable{
.append = appendImpl,
.pread = preadImpl,
.sync = syncImpl,
.size = sizeImpl,
.truncate = truncateImpl,
.refresh_end = refreshEndImpl,
};
/// One writer by construction, so there is no other writer to exclude.
fn refreshEndImpl(_: *anyopaque) storage.StorageError!void {}
fn appendImpl(ctx: *anyopaque, bytes: []const u8) storage.StorageError!void {
const self: *CountingStorage = @ptrCast(@alignCast(ctx));
return self.inner.append(bytes);
}
fn preadImpl(ctx: *anyopaque, offset: u64, buf: []u8) storage.StorageError!usize {
const self: *CountingStorage = @ptrCast(@alignCast(ctx));
const n = try self.inner.pread(offset, buf);
self.read_bytes += n;
return n;
}
fn syncImpl(ctx: *anyopaque) storage.StorageError!void {
const self: *CountingStorage = @ptrCast(@alignCast(ctx));
return self.inner.sync();
}
fn sizeImpl(ctx: *anyopaque) storage.StorageError!u64 {
const self: *CountingStorage = @ptrCast(@alignCast(ctx));
return self.inner.size();
}
fn truncateImpl(ctx: *anyopaque, len: u64) storage.StorageError!void {
const self: *CountingStorage = @ptrCast(@alignCast(ctx));
return self.inner.truncate(len);
}
};
/// Seed a `.zit` under `dir` holding a full+delta+manifest+config mix (via
/// `packSeedDeltaStore`) and return its committed byte size — the fixture the
/// serve-prime read-traffic and index-equivalence tests both build over.
fn seedServeRepo(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) !u64 {
const hash_kind: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
var f = try dir.createFile(io, repo_filename, .{ .read = true });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, 0);
var log = try logstore.LogStore.open(gpa, fs.storageFile(), hash_kind);
defer log.deinit(gpa);
var tip: [64]u8 = undefined;
try packSeedDeltaStore(gpa, &log, &tip);
return log.size();
}
test "serve prime reads the served log at most once (no second full-container copy)" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const file_size = try seedServeRepo(gpa, io, tmp.dir);
var handle = try tmp.dir.openFile(io, repo_filename, .{});
defer handle.close(io);
var fs = storage.FileStorage.init(io, handle, file_size);
var counting = CountingStorage{ .inner = fs.storageFile() };
// Build the serve base snapshot over the counting storage and measure how
// many bytes priming read. `openReadOnly`'s scan already whole-frame-CRC'd
// every byte once (the warm-start CRC concern); an index prime adds NOTHING on top, so
// total prime reads stay at roughly one pass over the log. The copy prime
// (`loadContentStore`) read every container a SECOND time — this bound fails
// for it, which is exactly the cost the log-offset index removes.
var index = try LogIndexStore.open(gpa, counting.storageFile());
defer index.destroy();
try std.testing.expect(counting.read_bytes <= file_size + file_size / 2);
}
test "log-backed index answers count/hashOf/held/content/wire identically to the MemStore snapshot" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const file_size = try seedServeRepo(gpa, io, tmp.dir);
// Reference: the whole-container MemStore snapshot `loadContentStore` builds.
var ref_handle = try tmp.dir.openFile(io, repo_filename, .{});
defer ref_handle.close(io);
var ref_fs = storage.FileStorage.init(io, ref_handle, file_size);
var ref_log = try logstore.LogStore.openReadOnly(gpa, ref_fs.storageFile());
defer ref_log.deinit(gpa);
var ref = repostate.MemStore.init(gpa);
defer ref.deinit();
try loadContentStore(gpa, &ref_log, &ref);
const rs = ref.store();
// Subject: the log-backed index over the same file.
var idx_handle = try tmp.dir.openFile(io, repo_filename, .{});
defer idx_handle.close(io);
var index = try LogIndexStore.openFromFile(gpa, io, idx_handle, file_size);
defer index.destroy();
const is = index.store();
try std.testing.expectEqual(rs.count(), is.count());
try std.testing.expect(rs.count() > 0);
var rid: repostate.Rid = 1;
while (rid <= rs.count()) : (rid += 1) {
// Identity, held-ness, and lookup round-trip.
try std.testing.expectEqualStrings(rs.hashOf(rid), is.hashOf(rid));
try std.testing.expectEqual(rs.held(rid), is.held(rid));
try std.testing.expectEqual(@as(?repostate.Rid, rid), is.lookup(rs.hashOf(rid)));
// Plaintext byte-for-byte.
const rc = rs.content(rid);
const ic = is.content(rid);
try std.testing.expectEqual(rc == null, ic == null);
if (rc) |rb| try std.testing.expectEqualSlices(u8, rb, ic.?);
// Wire form: container bytes, and the delta arm's DELTASRC + target size.
const rw = rs.wire(rid);
const iw = is.wire(rid);
try std.testing.expectEqual(rw == null, iw == null);
if (rw) |rwf| {
try std.testing.expectEqualSlices(u8, rwf.container, iw.?.container);
try std.testing.expectEqual(rwf.delta == null, iw.?.delta == null);
if (rwf.delta) |rd| {
try std.testing.expectEqualStrings(rd.src_hash, iw.?.delta.?.src_hash);
try std.testing.expectEqual(rd.target_size, iw.?.delta.?.target_size);
}
}
}
}
test "appendix honours intern/put/retain for hashes the log does not carry" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const file_size = try seedServeRepo(gpa, io, tmp.dir);
var handle = try tmp.dir.openFile(io, repo_filename, .{});
defer handle.close(io);
var index = try LogIndexStore.openFromFile(gpa, io, handle, file_size);
defer index.destroy();
const s = index.store();
// The serve base is contractually read-only — every write lands in the
// per-request OverlayStore (ticket constraint 3), so these appendix arms never
// fire in production. They exist so the store honours the whole ArtifactStore
// interface instead of trapping on a write; exercise them directly here so that
// completeness is not dead-untested surface.
const persisted = s.count();
try std.testing.expect(persisted > 0);
// A hash the log cannot hold (all-0xAB digest, hex-named as the wire does).
var d1: [digest_len]u8 = undefined;
@memset(&d1, 0xAB);
var h1_buf: [2 * digest_len]u8 = undefined;
const h1 = digestToWireName(&d1, &h1_buf);
try std.testing.expectEqual(@as(?repostate.Rid, null), s.lookup(h1));
// intern mints an appendix phantom ABOVE the persisted rids: not held (no
// content yet), count grows by one, identity round-trips, and it is idempotent.
const r1 = try s.intern(h1);
try std.testing.expect(r1 > persisted);
try std.testing.expectEqual(r1, try s.intern(h1));
try std.testing.expectEqual(@as(?repostate.Rid, r1), s.lookup(h1));
try std.testing.expectEqualStrings(h1, s.hashOf(r1));
try std.testing.expect(!s.held(r1));
try std.testing.expectEqual(@as(?[]const u8, null), s.content(r1));
try std.testing.expectEqual(persisted + 1, s.count());
// put upgrades that phantom in place: held flips true, content reads back, and
// the persisted count is unchanged (an off-log hash never touches the index).
const body = "off-log body bytes";
try std.testing.expectEqual(r1, try s.put(h1, body));
try std.testing.expect(s.held(r1));
try std.testing.expectEqualSlices(u8, body, s.content(r1).?);
try std.testing.expectEqual(persisted + 1, s.count());
// retain on a PERSISTED rid is the advisory no-op (sync §7.2 first-form-wins;
// the log IS the retained form): it returns without error and ignores ingest.
try s.retain(1, .{ .full = "ignored — a persisted rid keeps its log form" });
// None of the appendix traffic left persisted-round memos resident.
try std.testing.expectEqual(@as(usize, 0), index.residentBytes());
}
test "index materialises only the container a round reads and releases it between rounds" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const file_size = try seedServeRepo(gpa, io, tmp.dir);
var handle = try tmp.dir.openFile(io, repo_filename, .{});
defer handle.close(io);
var index = try LogIndexStore.openFromFile(gpa, io, handle, file_size);
defer index.destroy();
const s = index.store();
// Right after the prime the index holds ZERO container/plaintext bytes — the
// whole point: it did not copy the store into RAM.
try std.testing.expectEqual(@as(usize, 0), index.residentBytes());
// Find one wire-bearing rid (a zlib/delta frame).
var target: ?repostate.Rid = null;
var rid: repostate.Rid = 1;
while (rid <= s.count()) : (rid += 1) {
if (s.wire(rid) != null) {
target = rid;
break;
}
}
try std.testing.expect(target != null);
// Reading it materialised only its container; drop the round's memos.
try std.testing.expect(index.residentBytes() > 0);
index.releaseTransient();
try std.testing.expectEqual(@as(usize, 0), index.residentBytes());
// A single round's residency is EXACTLY the one container it emitted — not
// the whole store's containers (which the old snapshot held resident).
const one = s.wire(target.?).?;
try std.testing.expectEqual(one.container.len, index.residentBytes());
}
/// A test-only `storage.StorageFile` that reads faithfully until `fail_reads` is
/// flipped, then fails every `pread` — the instrument for a fault that strikes
/// AFTER `openReadOnly` has scanned and whole-frame-CRC'd the log, exactly the
/// post-scan bitrot / transient EIO the on-demand serve reads must not swallow
/// silently. Every other method delegates verbatim.
const FaultAfterScanStorage = struct {
inner: storage.StorageFile,
fail_reads: bool = false,
fn storageFile(self: *FaultAfterScanStorage) storage.StorageFile {
return .{ .context = self, .vtable = &vtable };
}
const vtable = storage.StorageFile.VTable{
.append = appendImpl,
.pread = preadImpl,
.sync = syncImpl,
.size = sizeImpl,
.truncate = truncateImpl,
.refresh_end = refreshEndImpl,
};
/// One writer by construction, so there is no other writer to exclude.
fn refreshEndImpl(_: *anyopaque) storage.StorageError!void {}
fn appendImpl(ctx: *anyopaque, bytes: []const u8) storage.StorageError!void {
const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
return self.inner.append(bytes);
}
fn preadImpl(ctx: *anyopaque, offset: u64, buf: []u8) storage.StorageError!usize {
const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
if (self.fail_reads) return error.Io;
return self.inner.pread(offset, buf);
}
fn syncImpl(ctx: *anyopaque) storage.StorageError!void {
const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
return self.inner.sync();
}
fn sizeImpl(ctx: *anyopaque) storage.StorageError!u64 {
const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
return self.inner.size();
}
fn truncateImpl(ctx: *anyopaque, len: u64) storage.StorageError!void {
const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
return self.inner.truncate(len);
}
};
test "a post-scan read fault on a held rid is recorded, not silently swallowed" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const file_size = try seedServeRepo(gpa, io, tmp.dir);
var handle = try tmp.dir.openFile(io, repo_filename, .{});
defer handle.close(io);
var fs = storage.FileStorage.init(io, handle, file_size);
var faulting = FaultAfterScanStorage{ .inner = fs.storageFile() };
// Open succeeds: the scan CRCs the whole log BEFORE any fault is armed.
var index = try LogIndexStore.open(gpa, faulting.storageFile());
defer index.destroy();
const s = index.store();
// From here every on-demand container/plaintext read faults (post-scan EIO).
faulting.fail_reads = true;
// Walk the store as the §8.2 clone pager does: a held rid whose wire() AND
// content() both return null is one the pager silently skips while still
// reporting the sequence complete — a clone finishing MISSING an artifact.
var silently_omitted = false;
var rid: repostate.Rid = 1;
while (rid <= s.count()) : (rid += 1) {
if (!s.held(rid)) continue;
if (s.wire(rid) == null and s.content(rid) == null) silently_omitted = true;
}
// The fault genuinely makes a held rid unemittable (the bug's precondition)...
try std.testing.expect(silently_omitted);
// ...and the store RECORDED it, so the serve layer can convert the round to an
// error instead of completing a broken clone. A copy-based prime could not
// reach this state: a read fault surfaced at prime, not silently at serve.
try std.testing.expect(index.read_fault);
}
test "serveAnswer converts a recorded read fault into a storage error (no silent short clone)" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var hex_buf: [2 * digest_len]u8 = undefined;
try serveSeedRepo(gpa, io, tmp.dir, 4, &hex_buf);
const server = zit.sync.Server{
.version = serve_mod.server_version,
.self_servercode = serve_mod.server_servercode,
.project_code = serve_mod.server_projectcode,
};
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const clone_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\nclone 3 1\n", .{});
defer gpa.free(clone_plain);
const clone_req = try zit.container.encode(gpa, clone_plain, .default);
defer gpa.free(clone_req);
// A healthy round builds the cached snapshot and completes normally.
const ok = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
gpa.free(ok.body);
// Simulate a post-scan read fault having struck THIS round — the test above
// proves the store records exactly this. serveAnswer MUST refuse to hand back
// a reply built while an artifact read faulted: otherwise the §8.2 pager's
// silent skip ships a clone missing an artifact and reports it complete.
ctx.snapshot.?.read_fault = true;
try std.testing.expectError(error.ServerStorage, serveAnswer(&ctx, gpa, clone_req, null, .{}, true));
// The flag is cleared with the round's memos, so an immediately retried round
// over the now-healthy snapshot succeeds again (a transient fault self-heals).
const recovered = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
gpa.free(recovered.body);
}
// ---------------------------------------------------------------------------
// `zit serve` must answer one sync round in time bounded by the
// REQUEST, not by the served store. Two per-request costs made a clone
// O(rounds x store): counting held artifacts by forcing a full inflate of every
// artifact, and rebuilding the entire in-memory snapshot from the log on every
// request. The guards below pin both as SCALING properties measured with work
// counters (plaintext bytes materialised, snapshot builds performed) — never
// wall-clock thresholds, which flake and prove nothing about the mechanism.
// ---------------------------------------------------------------------------
/// Seed `ms` with `n` distinct wire-backed artifacts exactly as
/// `loadContentStore` does for a served repository: one §4.1 full container per
/// artifact, with NO plaintext materialised. `ms.plaintextBytesHeld()` is 0 on
/// return, so any later non-zero reading is inflation this store did not ask for.
fn serveSeedWireStore(gpa: std.mem.Allocator, ms: *repostate.MemStore, n: usize) !void {
var i: usize = 0;
while (i < n) : (i += 1) {
var body_buf: [64]u8 = undefined;
const body = try std.fmt.bufPrint(&body_buf, "issue nine artifact {d}\n", .{i});
var name_buf: [64]u8 = undefined;
const name = zit.artifact.artifactName(.sha3_256, body, &name_buf);
const container = try zit.container.encode(gpa, body, .default);
defer gpa.free(container);
_ = try ms.putWire(name, container);
}
std.debug.assert(ms.plaintextBytesHeld() == 0);
}
test "serve: the held-artifact count serve uses never materialises plaintext (constant in store size)" {
const gpa = std.testing.allocator;
// Two store sizes: the work this count performs must not grow with n. The
// count VALUE alone would pass before and after the fix — it is the
// materialised-plaintext reading that observes the defect, so that is what
// is asserted, at both sizes, as the scaling statement.
for ([_]usize{ 8, 64 }) |n| {
var ms = repostate.MemStore.init(gpa);
defer ms.deinit();
try serveSeedWireStore(gpa, &ms, n);
try std.testing.expectEqual(n, ms.store().heldCount());
try std.testing.expectEqual(@as(usize, 0), ms.plaintextBytesHeld());
}
}
test "serve: a held artifact whose container does not inflate is still counted as servable" {
const gpa = std.testing.allocator;
var ms = repostate.MemStore.init(gpa);
defer ms.deinit();
// §4.1 shape (4-byte length prefix) with a payload that is not a valid zlib
// stream: `held()==true`, `content()==null` — the case `held()`'s contract at
// repostate.zig names. `respond` retransmits it verbatim and `persistStore`
// counts it, so serve's own count must agree with them.
const bogus = "\x00\x00\x00\x0anot-zlib-bytes";
_ = try ms.putWire(repeat("f", 64), bogus);
try std.testing.expectEqual(@as(usize, 1), ms.store().heldCount());
try std.testing.expect(ms.store().held(1));
try std.testing.expect(ms.store().content(1) == null);
}
/// A §4.1-framed read-only request naming `hash` in a `gimme` card.
fn serveGimmeRequest(gpa: std.mem.Allocator, card: []const u8, hash: []const u8) ![]u8 {
const plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\n{s} {s}\n", .{ card, hash });
defer gpa.free(plain);
return zit.container.encode(gpa, plain, .default);
}
test "serve publication fence retains the old snapshot and refuses new pending requests" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try serveAppendFrame(gpa, io, tmp.dir, repeat("a", digest_len), "old content\n");
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.dropSnapshot();
const old = try ctx.baseSnapshot(gpa);
const old_size = ctx.snapshot.?.fs.end;
try tmp.dir.createDir(io, zit.import_transaction.pending_name, .default_dir);
try serveAppendFrame(gpa, io, tmp.dir, repeat("b", digest_len), "prepared content\n");
try std.testing.expectError(error.ServerStorage, ctx.baseSnapshot(gpa));
try std.testing.expectEqual(@as(usize, 1), old.count());
try std.testing.expectEqual(old_size, ctx.snapshot.?.fs.end);
try ctx.snapshot.?.fs.storageFile().refreshEnd();
try std.testing.expectEqual(old_size, ctx.snapshot.?.fs.end);
try tmp.dir.deleteTree(io, zit.import_transaction.pending_name);
const fresh = try ctx.baseSnapshot(gpa);
try std.testing.expectEqual(@as(usize, 2), fresh.count());
}
test "serve: repeated rounds over an unchanged log build the snapshot once (constant in round count)" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const digest_a = repeat("a", digest_len);
try serveAppendFrame(gpa, io, tmp.dir, digest_a, "content a\n");
var hex_buf: [2 * digest_len]u8 = undefined;
const hex_a = digestToWireName(digest_a, &hex_buf);
const request = try serveGimmeRequest(gpa, "pull sc pc\ngimme", hex_a);
defer gpa.free(request);
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
// Eight rounds, log unchanged: the snapshot is a function of the log, not of
// the request, so the number of builds must not grow with the round count.
for (0..8) |_| {
const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
gpa.free(reply.body);
}
try std.testing.expectEqual(@as(u64, 1), ctx.loads);
}
test "serve: rounds over an unchanged log open the repository once, and a grown log reopens it" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try serveAppendFrame(gpa, io, tmp.dir, repeat("a", digest_len), "content a\n");
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
// Opening validates and maps the whole image sidecar, so a multi-round
// clone that reopened per round paid O(image) every round.
_ = try ctx.baseSnapshot(gpa);
const first = try ctx.roundRepo(gpa);
_ = try ctx.baseSnapshot(gpa);
const second = try ctx.roundRepo(gpa);
try std.testing.expect(first == second);
try std.testing.expectEqual(@as(u64, 1), ctx.repo_opens);
try serveAppendFrame(gpa, io, tmp.dir, repeat("b", digest_len), "content b\n");
_ = try ctx.baseSnapshot(gpa);
_ = try ctx.roundRepo(gpa);
try std.testing.expectEqual(@as(u64, 2), ctx.repo_opens);
}
test "serve: a responder's phantom interning cannot leak into the next round" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const digest_a = repeat("a", digest_len);
try serveAppendFrame(gpa, io, tmp.dir, digest_a, "content a\n");
var hex_buf: [2 * digest_len]u8 = undefined;
const hex_a = digestToWireName(digest_a, &hex_buf);
// §3.3 — an `igot` for a hash the server lacks makes `respond` intern a
// phantom into whatever store it answers over. That mutation must not
// survive into the reused snapshot.
const unknown_hex = repeat("c", (2 * digest_len));
const igot_req = try serveGimmeRequest(gpa, "pull sc pc\nigot", unknown_hex);
defer gpa.free(igot_req);
const gimme_req = try serveGimmeRequest(gpa, "pull sc pc\ngimme", hex_a);
defer gpa.free(gimme_req);
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
// NOTE ON THIS GUARD'S ROLE: it is green against the pre-fix code (which
// rebuilds per request and so cannot leak) — the round-count guard above is
// the red one. This guard exists because the obvious WRONG way to satisfy
// that guard — answer directly over one shared mutable snapshot — passes it
// and truncates real clones, since the phantoms and memoisations `respond`
// writes change what later rounds serve. Without this assertion that
// implementation ships.
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const r1 = try serveAnswer(&ctx, gpa, igot_req, null, .{}, true);
gpa.free(r1.body);
const snap = ctx.snapshot.?.store();
try std.testing.expectEqual(@as(usize, 1), snap.count()); // the one on-disk artifact, nothing more
try std.testing.expect(snap.lookup(unknown_hex) == null); // the phantom did not land here
const r2 = try serveAnswer(&ctx, gpa, gimme_req, null, .{}, true);
defer gpa.free(r2.body);
try std.testing.expectEqual(@as(u64, 1), ctx.loads); // still one build: the log never changed
// The reply is byte-identical to the one a server with no prior round produces.
var fresh_file = try tmp.dir.openFile(io, repo_filename, .{});
defer fresh_file.close(io);
var fresh_ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &fresh_file, .server = &server };
defer fresh_ctx.deinit();
const expected = try serveAnswer(&fresh_ctx, gpa, gimme_req, null, .{}, true);
defer gpa.free(expected.body);
try std.testing.expectEqualSlices(u8, expected.body, r2.body);
}
test "serve §3.8: a reused snapshot still sees a concurrent commit's append" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const digest_a = repeat("a", digest_len);
const digest_b = repeat("b", digest_len);
try serveAppendFrame(gpa, io, tmp.dir, digest_a, "content a\n");
var hex_a_buf: [2 * digest_len]u8 = undefined;
var hex_b_buf: [2 * digest_len]u8 = undefined;
const hex_a = digestToWireName(digest_a, &hex_a_buf);
const hex_b = digestToWireName(digest_b, &hex_b_buf);
const req_a = try serveGimmeRequest(gpa, "pull sc pc\ngimme", hex_a);
defer gpa.free(req_a);
const req_b = try serveGimmeRequest(gpa, "pull sc pc\ngimme", hex_b);
defer gpa.free(req_b);
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const r1 = try serveAnswer(&ctx, gpa, req_a, null, .{}, true);
gpa.free(r1.body);
try std.testing.expectEqual(@as(usize, 1), ctx.snapshot.?.store().count());
// A SEPARATE writer appends while the serve handle stays open.
try serveAppendFrame(gpa, io, tmp.dir, digest_b, "content b\n");
const r2 = try serveAnswer(&ctx, gpa, req_b, null, .{}, true);
gpa.free(r2.body);
// The log grew, so the snapshot was rebuilt and the new artifact is servable:
// a cache that never invalidates would still report one artifact and one load.
try std.testing.expectEqual(@as(u64, 2), ctx.loads);
try std.testing.expectEqual(@as(usize, 2), ctx.snapshot.?.store().count());
try std.testing.expect(ctx.snapshot.?.store().lookup(hex_b) != null);
}
/// Seed `dir`'s `.zit` with `n` distinct compressible artifacts, returning the
/// wire (hex) name of the first. Compressible so the log retains a §4.1
/// container per frame — the shape a served repository actually has, and the
/// only shape in which "answering a round does not inflate the store" has
/// anything to say.
fn serveSeedRepo(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, n: usize, first_hex: *[2 * digest_len]u8) !void {
const hash_kind: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
var f = dir.openFile(io, repo_filename, .{ .mode = .read_write }) catch
try dir.createFile(io, repo_filename, .{ .read = true });
defer f.close(io);
const st = try f.stat(io);
var fs = storage.FileStorage.init(io, f, st.size);
var log = try logstore.LogStore.open(gpa, fs.storageFile(), hash_kind);
defer log.deinit(gpa);
var i: usize = 0;
while (i < n) : (i += 1) {
var body: [512]u8 = undefined;
@memset(&body, 'a' + @as(u8, @intCast(i % 26)));
var digest: [digest_len]u8 = undefined;
@memset(&digest, 0);
std.mem.writeInt(u64, digest[0..8], i + 1, .big);
_ = try log.putZlib(&digest, &body);
if (i == 0) _ = digestToWireName(&digest, first_hex);
}
try log.commit();
}
test "serve: answering a round inflates only what the round emits (constant in store size)" {
const gpa = std.testing.allocator;
const io = std.testing.io;
// The same read round against two store sizes. The reply is identical, so
// the plaintext the server inflates to produce it must be identical too: any
// dependence on n is the server paying for artifacts the round never names.
// This is the assertion the whole change exists to make true — the pre-fix
// held-count walked `content()` over every rid, and so did inflate the store.
var inflated: [2]usize = undefined;
for ([_]usize{ 4, 40 }, 0..) |n, k| {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var hex_buf: [2 * digest_len]u8 = undefined;
try serveSeedRepo(gpa, io, tmp.dir, n, &hex_buf);
const request = try serveGimmeRequest(gpa, "pull sc pc\ngimme", &hex_buf);
defer gpa.free(request);
const server = zit.sync.Server{
.version = serve_mod.server_version,
.self_servercode = serve_mod.server_servercode,
.project_code = serve_mod.server_projectcode,
};
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
for (0..3) |_| {
const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
gpa.free(reply.body);
// Nothing the round materialised is still resident: the cached index
// reads containers on demand and frees them between rounds, never
// holding the repository's uncompressed history (or its containers).
try std.testing.expectEqual(@as(usize, 0), ctx.snapshot.?.residentBytes());
}
const emitted = ctx.snapshot.?.materialized_bytes;
// A CLONE round is the worst case for residency: it emits every artifact
// and proves each one's declared size against the plaintext, so it
// legitimately inflates the whole store. What must not survive it is the
// plaintext — a snapshot that outlives the round would otherwise end up
// holding the entire repository uncompressed, for the process's life.
const clone_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\nclone 3 1\n", .{});
defer gpa.free(clone_plain);
const clone_req = try zit.container.encode(gpa, clone_plain, .default);
defer gpa.free(clone_req);
const clone_reply = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
gpa.free(clone_reply.body);
try std.testing.expectEqual(@as(usize, 0), ctx.snapshot.?.residentBytes());
try std.testing.expect(ctx.snapshot.?.materialized_bytes >= emitted);
try std.testing.expectEqual(@as(usize, n), ctx.snapshot.?.store().count());
inflated[k] = emitted;
}
try std.testing.expectEqual(inflated[0], inflated[1]);
// ... and the constant is the round's own emission, not the store's: a
// 40-artifact store holds 20480 bytes of plaintext, so an equality that
// happened to hold at "everything" would still be caught here.
try std.testing.expect(inflated[1] < 4 * 512);
}
test "serve: the pushing round does not rebuild inside its deadline; maintain rebuilds between connections" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const hash_kind: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
{
var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, 0);
var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hash_kind);
defer seed.deinit(gpa);
try seed.commit();
}
const push_body = "pushed artifact bytes\n";
var name_buf: [64]u8 = undefined;
const push_hash = zit.artifact.artifactName(.sha3_256, push_body, &name_buf);
const plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\npush sc pc\nfile {s} {d}\n{s}", .{ push_hash, push_body.len, push_body });
defer gpa.free(plain);
const push_req = try zit.container.encode(gpa, plain, .default);
defer gpa.free(push_req);
const read_req = try serveGimmeRequest(gpa, "pull sc pc\ngimme", push_hash);
defer gpa.free(read_req);
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const r0 = try serveAnswer(&ctx, gpa, read_req, null, .{}, true);
gpa.free(r0.body);
try std.testing.expectEqual(@as(u64, 1), ctx.loads);
// The push makes the snapshot stale, but answering it must NOT pay the
// O(store) rebuild: the reply is written inside a connection deadline, and
// The failure is exactly the whole-repository rebuild landing inside that
// budget. The rebuild is deferred to `maintain`, which the accept loop runs
// after the connection closes — outside every deadline. So the pushing round
// leaves `loads` untouched.
const r1 = try serveAnswer(&ctx, gpa, push_req, null, .{}, true);
gpa.free(r1.body);
try std.testing.expectEqual(@as(u64, 1), ctx.loads); // no rebuild inside the round
// The snapshot is momentarily stale — it predates the push — yet the push is
// already durable on disk: `persistStore` ran inside the round.
try std.testing.expect(ctx.snapshot != null);
try std.testing.expect(ctx.snapshot.?.store().lookup(push_hash) == null);
// The accept loop's post-connection maintenance hook does the O(store)
// rebuild, between connections, with no connection open to charge it to.
ServeCtx.maintain(&ctx, gpa);
try std.testing.expectEqual(@as(u64, 2), ctx.loads);
try std.testing.expect(ctx.snapshot.?.store().lookup(push_hash) != null);
// The rebuilt snapshot describes the grown log exactly (the append-only stat
// gate that `baseSnapshot` already carries).
const st = try file.stat(io);
try std.testing.expectEqual(st.size, ctx.snapshot_log_size);
// A later read round is stat-gated to no rebuild, and still serves the push.
const r2 = try serveAnswer(&ctx, gpa, read_req, null, .{}, true);
defer gpa.free(r2.body);
try std.testing.expectEqual(@as(u64, 2), ctx.loads);
}
const shun_test_letter_name = repeat("ab", digest_len);
test "sync §3.3 L553-556: a repository shun row is a durable wire-name hit, keyed exactly" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedShunnedRepo(gpa, io, tmp.dir);
var holdings = try ClientHoldings.open(gpa, io, tmp.dir);
defer holdings.deinit(io);
const shun = &holdings.index.shun;
const set = holdings.admission().shun;
// The complete name is the key: a hit.
try std.testing.expect(set.contains(shun_test_name));
// The held artifact is not shunned.
try std.testing.expect(!set.contains(shun_test_held_name));
// A 12-hex PREFIX of the shunned name is a DIFFERENT key, not a hit. The
// lookup never truncates, pads, or prefix-matches — a prefix must not be
// able to masquerade as a shun-table hit. Nor may an incomplete name reach
// `LogStore.isShunned`, whose caller contract (src/store/logstore.zig L1746-1757)
// binds this boundary: the width check is a CHECKED rejection, not an
// assert, because an assert is nothing in ReleaseFast and these names come
// off the wire.
//
// These OUT-OF-DOMAIN widths are probed against `containsWireName` directly,
// not through `zit.sync.ShunSet.contains`: the release-checked rule lives
// here, in the implementation that owns it, while the wrapper asserts the
// §3.2 width its own key domain promises. Going through the wrapper would
// pin the assert instead of the rejection these lines mean to pin.
try std.testing.expect(!RepoShunSet.containsWireName(shun, shun_test_name[0..12]));
try std.testing.expect(!RepoShunSet.containsWireName(shun, shun_test_name[0 .. 2 * digest_len - 1])); // odd length
try std.testing.expect(!RepoShunSet.containsWireName(shun, "")); // empty
try std.testing.expect(!RepoShunSet.containsWireName(shun, repeat("ab", 48))); // 96 hex — not one of the two forms
// Correct WIDTH, not hex: in the wrapper's key domain, so probed through it.
try std.testing.expect(!set.contains(repeat("z", (2 * digest_len)))); // not hex
// An UPPERCASE spelling of the shunned name decodes to the same digest and
// so answers TRUE. artifact-format §3.3 L370-377 makes the token invalid but
// lets an implementation accept it at name validation and fail it at
// verification; over-suppressing a name that can never verify is the safe
// direction. Pinned so the fail-closed direction is a decision, not an
// accident of `hexToBytes` accepting case.
try std.testing.expect(set.contains(shun_test_letter_name));
var upper: [2 * digest_len]u8 = undefined;
for (shun_test_letter_name, 0..) |c, i| upper[i] = std.ascii.toUpper(c);
try std.testing.expect(!std.mem.eql(u8, &upper, shun_test_letter_name)); // the case really differs
try std.testing.expect(set.contains(&upper));
}
test "sync §3.3 L553-556: an OOM inside the shun-set load leaves no borrowed key in the owned-key map" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedShunnedRepo(gpa, io, tmp.dir);
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
const st = try file.stat(io);
var fs = storage.FileStorage.init(io, file, st.size);
var log = try logstore.LogStore.openReadOnly(gpa, fs.storageFile());
defer log.deinit(gpa);
try std.testing.expect(log.shunList().len >= 2);
// `load` dupes each row's digest because `shunList` borrows the STORE's own
// bytes, and the dupe must PRECEDE the insert: insert-then-replace leaves the
// borrowed slice live as a key on the one error path, after which `deinit`
// frees the store's digest and `log.deinit` frees it again. A manual sweep
// (not `checkAllAllocationFailures`) because the obligation is about which
// POINTER survives the unwind, not just about leaking: the store is
// allocated from the UNWRAPPED allocator, so a key that is not `load`'s own
// dupe is freed through the wrap and the double free lands on
// `testing.allocator`, which catches it. `fail_index` indexes `load`'s
// allocations alone for the same reason.
var i: usize = 0;
while (i < 64) : (i += 1) {
var fa = std.testing.FailingAllocator.init(gpa, .{ .fail_index = i });
var shun = RepoShunSet.init(fa.allocator());
defer shun.deinit();
if (shun.load(&log)) |_| {
// The fail point lay at or past the last allocation: no failure was
// forced, so every allocation site is now covered and the set is
// whole.
try std.testing.expect(shun.digests.count() >= 2);
break;
} else |e| {
try std.testing.expectEqual(error.OutOfMemory, e);
}
} else return error.SweepNeverCompleted;
}
/// Does the decoded reply body carry `gimme NAME` as a whole card line?
fn replyHasGimme(gpa: std.mem.Allocator, reply_container: []const u8, name: []const u8) !bool {
const body = try zit.container.decode(gpa, reply_container, @intCast(logstore.max_payload));
defer gpa.free(body);
var it = std.mem.splitScalar(u8, body, '\n');
while (it.next()) |line| {
if (line.len == 6 + name.len and
std.mem.startsWith(u8, line, "gimme ") and
std.mem.eql(u8, line[6..], name)) return true;
}
return false;
}
test "sync §3.3 L553-556 / §8.8 L1839-1841: a served reply never gimme's a shunned phantom, and a shun row written between rounds is honoured by the next" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
// A repo holding one artifact and NO shun row yet.
const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
{
var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, 0);
var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
defer seed.deinit(gpa);
_ = try seed.put(shun_test_held_digest, "held content\n");
try seed.commit();
}
// A pushing client's `igot` for a hash this repo lacks: §3.3 r24(1)
// L511-514 makes the server a receiver, so `respond` interns the phantom
// and would beg for it.
const igot_req = try serveGimmeRequest(gpa, "pull sc pc\npush sc pc\nigot", shun_test_name);
defer gpa.free(igot_req);
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
// Round 1, no shun row: the reply asks for it. This is the behaviour the
// filter must change, so the test is red on an unfiltered server.
{
const r = try serveAnswer(&ctx, gpa, igot_req, null, .{}, true);
defer gpa.free(r.body);
try std.testing.expect(try replyHasGimme(gpa, r.body, shun_test_name));
}
// The operator shuns it BETWEEN rounds — an append to the same log.
{
var f = try tmp.dir.openFile(io, repo_filename, .{ .mode = .read_write });
defer f.close(io);
const st = try f.stat(io);
var fs = storage.FileStorage.init(io, f, st.size);
var log = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
defer log.deinit(gpa);
try log.putShun(shun_test_digest, "operator request", 1);
try log.commit();
}
// Round 2 honours it with no restart: the append grew the log, so
// `baseSnapshot`'s stat gate rebuilds the index — and the rebuild re-loads
// the shun table (`LogIndexStore.shun`). That is the freshness mechanism this
// set rides; nothing here is memoised past a build.
{
const r = try serveAnswer(&ctx, gpa, igot_req, null, .{}, true);
defer gpa.free(r.body);
try std.testing.expect(!try replyHasGimme(gpa, r.body, shun_test_name));
// The unshunned holding is still advertised: only the shunned name went quiet.
const body = try zit.container.decode(gpa, r.body, @intCast(logstore.max_payload));
defer gpa.free(body);
try std.testing.expect(std.mem.indexOf(u8, body, "igot " ++ shun_test_held_name) != null);
}
try std.testing.expectEqual(@as(u64, 2), ctx.loads); // one build per log state, not per round
}
/// The FIRST, a MIDDLE and the LAST of the five are shunned, so an off-by-one or
/// a misindexed mask cannot pass: the survivors are interleaved among them.
fn sendShunIsShunned(i: usize) bool {
return i % 2 == 0;
}
/// Seed `dir`'s repository holding all five `send_shun_digests` in order, with a
/// live config frame BEFORE the first and another BETWEEN the second and third,
/// and shun rows naming the first, middle and last.
///
/// The interleaving is what an off-by-one cannot survive: shunning the FIRST, a
/// MIDDLE and the LAST slot means a mask built by any walk other than the
/// enumeration's own loop names one artifact and suppresses another, and the
/// alignment test below reads that straight off the log. The config frames are
/// here for a WEAKER reason than they look: they never enter
/// `ridsInPersistedOrder` at all (a config frame is not interned — `LogStore.scan`
/// only records its offset), so they exercise the `.config` guards' *presence*, not
/// a live skip; they do not by themselves make a second walk misalign.
fn seedSendShunRepo(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) !void {
const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
var f = try dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, 0);
var log = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
defer log.deinit(gpa);
try log.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "" });
_ = try log.put(send_shun_digests[0], "content zero\n");
_ = try log.put(send_shun_digests[1], "content one\n");
try log.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "cccc" });
_ = try log.put(send_shun_digests[2], "content two\n");
_ = try log.put(send_shun_digests[3], "content three\n");
_ = try log.put(send_shun_digests[4], "content four\n");
for (send_shun_digests, 0..) |d, i| {
if (sendShunIsShunned(i)) try log.putShun(d, "operator request", 1);
}
try log.commit();
}
/// How many of `index`'s slots a lookup of their own name finds: the
/// unmasked ones.
fn resolvableNames(index: *LogIndexStore) usize {
var found: usize = 0;
for (0..index.rids.len) |a| {
if (index.nameRid(index.nameAt(a))) |rid| {
std.debug.assert(rid == a + 1);
found += 1;
}
}
return found;
}
test "sync §9.5 L2170-2174: a shunned holding is masked out of the adapter enumeration and its name is absent from by_name" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedSendShunRepo(gpa, io, tmp.dir);
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
const st = try file.stat(io);
var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
defer index.destroy();
const s = index.store();
// §8.2 L1551-1553 — the rid space is the LOG's, not the survivors': all five
// artifact frames still hold their slot (config frames were never in it).
try std.testing.expectEqual(@as(usize, 5), index.rids.len);
try std.testing.expectEqual(@as(usize, 5), s.count());
for (send_shun_names, 0..) |name, i| {
const rid: repostate.Rid = @intCast(i + 1);
if (sendShunIsShunned(i)) {
// Not resolvable by name: the §3.2 gimme arm keys on `lookup`, so
// this IS §3.3 L569-572's "If absent, silently skip".
try std.testing.expect(index.nameRid(name) == null);
try std.testing.expect(s.lookup(name) == null);
// Not announced (§3.2's igot walk gates on `held`), and nothing to
// send in either form.
try std.testing.expect(!s.held(rid));
try std.testing.expect(s.content(rid) == null);
try std.testing.expect(s.wire(rid) == null);
} else {
try std.testing.expectEqual(@as(?repostate.Rid, rid), s.lookup(name));
try std.testing.expect(s.held(rid));
try std.testing.expect(s.content(rid) != null);
}
}
// A masked frame is a policy gap, never a read fault: the round must not be
// converted to `error.ServerStorage` by `serveAnswer`.
try std.testing.expect(!index.read_fault);
}
/// Does the decoded reply body carry `VERB NAME` as a whole card line?
fn replyHasCardFor(body: []const u8, verb: []const u8, name: []const u8) bool {
var it = std.mem.splitScalar(u8, body, '\n');
while (it.next()) |line| {
if (line.len != verb.len + 1 + name.len) continue;
if (!std.mem.startsWith(u8, line, verb)) continue;
if (line[verb.len] != ' ') continue;
if (std.mem.eql(u8, line[verb.len + 1 ..], name)) return true;
}
return false;
}
test "sync §9.5 L2170-2174: a served round igot-announces the survivors and never a masked holding" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedSendShunRepo(gpa, io, tmp.dir);
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
// A round that makes the server run its §3.2 inventory walk over every rid.
// The announced hash is one this repo does not hold, so nothing else about
// the request steers which holdings the walk reaches. The pull names the
// served project (sync §8.5).
var pc_buf: [zit.sync.max_projectcode_len]u8 = undefined;
const identity = try repoSyncIdentity(gpa, io, tmp.dir, "test-fixture-repo", &pc_buf);
const pull_igot = try std.fmt.allocPrint(gpa, "pull sc {s}\nigot", .{identity.project_code});
defer gpa.free(pull_igot);
const req = try serveGimmeRequest(gpa, pull_igot, shun_test_name);
defer gpa.free(req);
const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
defer gpa.free(reply.body);
const body = try zit.container.decode(gpa, reply.body, @intCast(logstore.max_payload));
defer gpa.free(body);
for (send_shun_names, 0..) |name, i| {
if (sendShunIsShunned(i)) {
// §9.5 L2170-2174 — not among "every eligible holding": the walk's
// `held()` gate answers false, so no igot names it.
try std.testing.expect(!replyHasCardFor(body, "igot", name));
// Nor does it fall out of the walk as a PHANTOM to beg for. The
// enumeration now hands the walk a non-held rid, and it is `Server.shun`
// — the §3.3 L553-556 arm this repository's own table feeds through
// `serveRound` — that keeps the reply quiet. That check is not dead
// after this slice; the mask is what makes it load-bearing.
try std.testing.expect(!replyHasCardFor(body, "gimme", name));
} else {
try std.testing.expect(replyHasCardFor(body, "igot", name));
}
}
// A masked holding is not an error condition on any card.
try std.testing.expect(std.mem.indexOf(u8, body, "error") == null);
}
test "sync §9.5 L2170-2174: the masked enumeration stays aligned — adapter rid r names rids[r-1] with shunned first, middle and last" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedSendShunRepo(gpa, io, tmp.dir);
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
const st = try file.stat(io);
var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
defer index.destroy();
const s = index.store();
// `rids`, `names`, `masked`, `content_memo` and `wire_memo` are PARALLEL
// arrays and `by_name` maps a wire name to that same index. Filtering or
// masking one out of step with the others makes adapter rid r name a
// DIFFERENT artifact's bytes — silent corruption on the wire, not an error.
// Pin the whole alignment against the log itself, entry by entry.
var shunned_seen: usize = 0;
for (index.rids, 0..) |lr, a| {
var buf: [2 * digest_len]u8 = undefined;
const expect_name = digestToWireName(index.log.hashOf(lr), &buf);
const rid: repostate.Rid = @intCast(a + 1);
try std.testing.expectEqualStrings(expect_name, index.nameAt(a));
try std.testing.expectEqualStrings(expect_name, s.hashOf(rid));
try std.testing.expectEqualStrings(send_shun_names[a], expect_name);
// The mask indexes the SAME slot as `rids[a]` — the invariant a mask
// built over any second walk over the log breaks (verified: a mask
// written one slot out of step turns this expectation red).
try std.testing.expectEqual(index.shun.digests.contains(index.log.hashOf(lr)), index.masked[a]);
if (index.masked[a]) {
shunned_seen += 1;
try std.testing.expect(index.nameRid(expect_name) == null);
} else {
try std.testing.expectEqual(@as(?repostate.Rid, rid), index.nameRid(expect_name));
}
}
// The fixture really does interleave: three shunned, two survivors.
try std.testing.expectEqual(@as(usize, 3), shunned_seen);
try std.testing.expectEqual(@as(usize, 2), resolvableNames(index));
}
test "sync §9.5 L2170-2174 / §7.7 L1472-1475: a write against a masked wire name does not unmask it — no second identity, still not held, still not servable" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedSendShunRepo(gpa, io, tmp.dir);
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
const st = try file.stat(io);
var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
defer index.destroy();
const s = index.store();
// The masked name is absent from `by_name`, so every write door below misses the
// dedup key the survivors hit and would otherwise fall through to the appendix —
// minting a SECOND, HELD entry for a name §9.5 says this server does not send,
// and putting it back on the §3.2 walk. The mask outranks the write instead.
const masked_name = send_shun_names[0];
try std.testing.expect(index.masked[0]);
const before = s.count();
try std.testing.expectEqual(@as(repostate.Rid, 1), try s.intern(masked_name));
try std.testing.expectEqual(@as(repostate.Rid, 1), try s.put(masked_name, "content zero\n"));
// Even bytes that DISAGREE with the frame: the mask is not a content check, and
// this path must not read (nor assert on) a masked frame's plaintext.
try std.testing.expectEqual(@as(repostate.Rid, 1), try s.put(masked_name, "different bytes\n"));
try s.retain(1, .{ .full = "not a real container" });
// Nothing was created and nothing was unmasked.
try std.testing.expectEqual(before, s.count());
try std.testing.expectEqual(@as(usize, 2), resolvableNames(index));
try std.testing.expect(!s.held(1));
try std.testing.expect(s.content(1) == null);
try std.testing.expect(s.wire(1) == null);
// §3.3 L569-572 still applies to an inbound `gimme` for it: absent, silently
// skipped, no second rid for the walk to trip over.
try std.testing.expect(s.lookup(masked_name) == null);
try std.testing.expect(!index.read_fault);
// NEGATIVE SPACE: the appendix arm is intact for a name the log genuinely does
// not carry — the guard above narrows the masked case only.
const absent_name = repeat("99", digest_len);
const appendix_rid = try s.intern(absent_name);
try std.testing.expectEqual(@as(repostate.Rid, 6), appendix_rid);
try std.testing.expectEqual(before + 1, s.count());
try std.testing.expect(!s.held(appendix_rid));
}
test "sync §7.7 L1479-1485 / §9.5 L2170-2174: the adapter owns its content mask — the frame's plaintext is still on disk and still readable through the maintenance door" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedSendShunRepo(gpa, io, tmp.dir);
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
const st = try file.stat(io);
var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
defer index.destroy();
const s = index.store();
// §9.5's filter is a POLICY answer about what this server SENDS, not a deletion:
// the frame, its bytes and its checksums are untouched on disk. §7.7 L1479-1485
// depends on exactly that — "For an admitted target whose DELTASRC name is in
// the repository shun table, the receiver does not apply admission independently
// to that source: content still held locally MAY serve as the delta basis" — so
// "still held locally" is a property this slice must not have quietly destroyed.
// `LogStore.contentUnmasked` is the maintenance door that reads under no mask
// (`pack.zig`'s reader), and it is the only way to distinguish "the bytes are
// gone" from "the send side refuses to hand them out".
try std.testing.expect(index.masked[0]);
const on_disk = try index.log.contentUnmasked(gpa, index.rids[0], null);
defer if (on_disk) |b| gpa.free(b);
try std.testing.expectEqualStrings("content zero\n", on_disk.?);
// ...and the store still refuses, in both forms, without calling it a fault.
try std.testing.expect(s.content(1) == null);
try std.testing.expect(s.wire(1) == null);
try std.testing.expect(!index.read_fault);
// Nothing was materialised on the way: a refusal is answered from the mask, so
// a masked frame is never inflated into the round's memo (which is also what
// keeps a shunned artifact's plaintext out of a server's memory).
try std.testing.expectEqual(@as(usize, 0), index.materialized_bytes);
try std.testing.expectEqual(@as(usize, 0), index.residentBytes());
// NEGATIVE SPACE: the maintenance door is not a blanket unmask of the store —
// a SURVIVOR reads identically through both, so the asymmetry above is the
// mask's doing and not an artefact of which reader was called.
const survivor = try index.log.contentUnmasked(gpa, index.rids[1], null);
defer if (survivor) |b| gpa.free(b);
try std.testing.expectEqualStrings(survivor.?, s.content(2).?);
}
test "sync §9.5 L2170-2174 / §7.7 L1472-1475: a served round's writes land in the round-local overlay — the base enumeration's write doors are never reached" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
// `seedSendShunRepo`'s digests are synthetic, so no peer could legitimately push
// one back — the responder hashes the payload and would reject the name long
// before reaching any store door. This fixture names its two artifacts by their
// REAL content address, so the push below is one a real peer could send.
const shunned_body = "shunned artifact bytes\n";
const survivor_body = "surviving artifact bytes\n";
var shunned_buf: [64]u8 = undefined;
var survivor_buf: [64]u8 = undefined;
const shunned_name = zit.artifact.artifactName(.sha3_256, shunned_body, &shunned_buf);
const survivor_name = zit.artifact.artifactName(.sha3_256, survivor_body, &survivor_buf);
var shunned_dbuf: [digest_len]u8 = undefined;
var survivor_dbuf: [digest_len]u8 = undefined;
const shunned_digest = hexToDigest(shunned_name, &shunned_dbuf) orelse return error.BadTestName;
const survivor_digest = hexToDigest(survivor_name, &survivor_dbuf) orelse return error.BadTestName;
const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
{
var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, 0);
var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
defer seed.deinit(gpa);
try seed.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "" });
_ = try seed.put(shunned_digest, shunned_body);
_ = try seed.put(survivor_digest, survivor_body);
try seed.putShun(shunned_digest, "operator request", 1);
try seed.commit();
}
const server = zit.sync.Server{
.version = serve_mod.server_version,
.self_servercode = serve_mod.server_servercode,
.project_code = serve_mod.server_projectcode,
};
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
// A peer pushes the very name this repository has shunned.
const push_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\npush sc pc\nfile {s} {d}\n{s}", .{ shunned_name, shunned_body.len, shunned_body });
defer gpa.free(push_plain);
const push_req = try zit.container.encode(gpa, push_plain, .default);
defer gpa.free(push_req);
{
const reply = try serveAnswer(&ctx, gpa, push_req, null, .{}, true);
defer gpa.free(reply.body);
// THE PROPERTY. `putImpl`/`internImpl` deliberately NARROW the store contract
// for a masked name — they answer a rid whose `content` is null and whose
// `held` is false — and the vtable's `error{OutOfMemory}` cannot signal that.
// What keeps the narrowing safe is that a served round never reaches those
// doors at all: `respond` writes into a per-request `repostate.OverlayStore`
// that is discarded at round end. `appendix` is where any write that DID
// reach this base would land, so its emptiness is that claim, measured.
const base = ctx.snapshot.?;
try std.testing.expectEqual(@as(usize, 0), base.appendix.store().count());
try std.testing.expectEqual(@as(usize, 2), base.store().count());
// ...and the push did not unmask the name it carried.
try std.testing.expect(base.masked[0]);
try std.testing.expect(base.store().lookup(shunned_name) == null);
try std.testing.expect(!base.store().held(1));
try std.testing.expect(base.store().content(1) == null);
try std.testing.expect(!base.read_fault);
// The survivor is untouched by any of it.
try std.testing.expectEqual(@as(?repostate.Rid, 2), base.store().lookup(survivor_name));
}
// NEGATIVE SPACE: it is not the MASK that keeps the base's doors shut, it is the
// overlay. A push of a name this repository has never seen — the case that has a
// real appendix arm waiting for it — must land in the round-local store just the
// same. (This round's `baseSnapshot` rebuilds over the grown log first, so the
// snapshot read below is the one this round actually served from.)
const fresh_body = "a name this repository has never held\n";
var fresh_buf: [64]u8 = undefined;
const fresh_name = zit.artifact.artifactName(.sha3_256, fresh_body, &fresh_buf);
const fresh_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\npush sc pc\nfile {s} {d}\n{s}", .{ fresh_name, fresh_body.len, fresh_body });
defer gpa.free(fresh_plain);
const fresh_req = try zit.container.encode(gpa, fresh_plain, .default);
defer gpa.free(fresh_req);
const reply2 = try serveAnswer(&ctx, gpa, fresh_req, null, .{}, true);
defer gpa.free(reply2.body);
try std.testing.expectEqual(@as(usize, 0), ctx.snapshot.?.appendix.store().count());
}
/// The `clone_seqno NEXT` cursor a clone reply carries (§8.2 L1573-1576: "An
/// accepting clone reply emits zero or more clone cfile cards in RID order … then
/// clone_seqno NEXT, push SERVERCODE PROJECTCODE, and final comment. … NEXT zero
/// signals exhaustion."), read off the decoded body.
fn cloneSeqnoOf(body: []const u8) !u64 {
var it = std.mem.splitScalar(u8, body, '\n');
while (it.next()) |line| {
if (!std.mem.startsWith(u8, line, "clone_seqno ")) continue;
return std.fmt.parseInt(u64, line["clone_seqno ".len..], 10) catch return error.BadCloneSeqno;
}
return error.NoCloneSeqno;
}
/// Does the decoded reply body carry a `cfile` card for `name`? Keyed on the card
/// prefix plus the separating space, so a name that is a prefix of another cannot
/// answer for it.
fn replyHasCfile(gpa: std.mem.Allocator, body: []const u8, name: []const u8) !bool {
const needle = try std.fmt.allocPrint(gpa, "cfile {s} ", .{name});
defer gpa.free(needle);
return std.mem.indexOf(u8, body, needle) != null;
}
// WHAT THIS TEST PINS, and what it does NOT. The masked frames' absence from the
// clone stream is NOT this slice's doing: the pager gates on `store.wire()` then
// `store.content()`, and `LogStore.wire`/`content` already answered null for a
// shunned entry through their own rid-keyed read mask before the enumeration was
// masked at all — so this test passes with `LogIndexStore`'s exclusion removed
// (confirmed by mutation). What it does pin, and what nothing else pins, is that
// the mask keeps the pager's persisted-order cursor CONTIGUOUS over the survivors:
// each survivor arrives exactly once across paged batches and the sequence
// terminates at NEXT 0. A mask written out of step with `rids` turns it red.
test "sync §8.2 L1551-1553 / §9.5 L2170-2174: the clone pager walks the survivors contiguously across paged batches and terminates at NEXT 0" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedSendShunRepo(gpa, io, tmp.dir);
// A one-artifact batch cap forces the pager to page, so the persisted-order
// cursor is exercised at every masked frame rather than swallowed by a single
// full-store batch.
const server = zit.sync.Server{
.version = serve_mod.server_version,
.self_servercode = serve_mod.server_servercode,
.project_code = serve_mod.server_projectcode,
.clone_batch_max = 1,
};
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
var delivered = @as([5]usize, @splat(0));
var seqno: u64 = 1;
var rounds: usize = 0;
while (rounds < 16) : (rounds += 1) {
const plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\nclone 3 {d}\n", .{seqno});
defer gpa.free(plain);
const req = try zit.container.encode(gpa, plain, .default);
defer gpa.free(req);
const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
defer gpa.free(reply.body);
// §8.1 L1529-1531 / §4.1 L885-887 — a clone reply is the RAW card/cfile stream under
// `application/x-fossil-uncompressed`, never a zlib container.
try std.testing.expectEqualStrings("application/x-fossil-uncompressed", reply.content_type);
const body = reply.body;
for (send_shun_names, 0..) |name, i| {
if (try replyHasCfile(gpa, body, name)) delivered[i] += 1;
}
const next = try cloneSeqnoOf(body);
if (next == 0) break;
// A LOOP GUARD, not a protocol requirement: §8.2 L1577-1579 says the
// opposite — "The client records a digit-only NEXT and does not validate
// that a positive value advances from the supplied SEQNO". A pager that
// returned a non-advancing cursor would spin this test to its round cap
// instead of failing on the thing it is here to measure, so the guard
// states the pager's own contract, with no normative claim behind it.
try std.testing.expect(next > seqno);
seqno = next;
} else return error.CloneNeverExhausted;
// THE PROOF: every survivor arrived EXACTLY ONCE across the paged batches, and
// the sequence reached NEXT 0. The zero counts for the masked slots are carried
// by the log's own read mask (see the note above the test), not by this slice;
// the "exactly once" and the termination are the mask's contribution — a slot
// masked out of step with `rids` drops or duplicates a survivor here.
for (delivered, 0..) |n, i| {
const want: usize = if (sendShunIsShunned(i)) 0 else 1;
try std.testing.expectEqual(want, n);
}
}
test "sync §9.5 L2170-2174: a shun row written between clone rounds is honoured by the next round WITHOUT renumbering the survivors" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
// A repo holding all five artifacts and NO shun row yet.
const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
{
var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, 0);
var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
defer seed.deinit(gpa);
try seed.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "" });
for (send_shun_digests, 0..) |d, i| {
var body_buf: [32]u8 = undefined;
_ = try seed.put(d, try std.fmt.bufPrint(&body_buf, "distinct content {d}\n", .{i}));
}
try seed.commit();
}
const server = zit.sync.Server{
.version = serve_mod.server_version,
.self_servercode = serve_mod.server_servercode,
.project_code = serve_mod.server_projectcode,
};
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const clone_plain = "pragma client-version 20000\nclone 3 1\n";
const clone_req = try zit.container.encode(gpa, clone_plain, .default);
defer gpa.free(clone_req);
// Round 1, no shun row: every artifact is served, and artifact 3 sits at
// adapter rid 3. This is the behaviour the mask must change, so the test is
// red on an unfiltered server.
{
const reply = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
defer gpa.free(reply.body);
const body = reply.body; // §8.1 L1529-1531 / §4.1 L885-887 — uncompressed clone stream
for (send_shun_names) |name| try std.testing.expect(try replyHasCfile(gpa, body, name));
try std.testing.expectEqual(@as(?repostate.Rid, 3), ctx.snapshot.?.store().lookup(send_shun_names[2]));
try std.testing.expectEqual(@as(?repostate.Rid, 5), ctx.snapshot.?.store().lookup(send_shun_names[4]));
}
// The operator shuns the MIDDLE artifact between rounds — an append, which is
// exactly what trips `baseSnapshot`'s append-only stat gate and rebuilds.
{
var f = try tmp.dir.openFile(io, repo_filename, .{ .mode = .read_write });
defer f.close(io);
const st = try f.stat(io);
var fs = storage.FileStorage.init(io, f, st.size);
var log = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
defer log.deinit(gpa);
try log.putShun(send_shun_digests[1], "operator request", 1);
try log.commit();
}
// Round 2 honours it with no restart — AND the survivors above it keep their
// adapter rids. A dense filter would shift artifact 3 to rid 2 and artifact 5
// to rid 4, so a client resuming this clone at cursor 3 would step over
// artifact 3 entirely and still be told NEXT 0 (§8.2 L1551-1553 licenses the
// gap; it does not license the shift).
{
const reply = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
defer gpa.free(reply.body);
const body = reply.body; // §8.1 L1529-1531 / §4.1 L885-887 — uncompressed clone stream
try std.testing.expect(!try replyHasCfile(gpa, body, send_shun_names[1]));
for (send_shun_names, 0..) |name, i| {
if (i == 1) continue;
try std.testing.expect(try replyHasCfile(gpa, body, name));
}
try std.testing.expectEqual(@as(usize, 5), ctx.snapshot.?.store().count());
try std.testing.expectEqual(@as(?repostate.Rid, 3), ctx.snapshot.?.store().lookup(send_shun_names[2]));
try std.testing.expectEqual(@as(?repostate.Rid, 5), ctx.snapshot.?.store().lookup(send_shun_names[4]));
// THE MASK ITSELF, at THIS layer. The absent `cfile` above does not prove it:
// `LogStore.wire`/`content` answer null for a shunned entry through their own
// read mask, so the clone stream would omit the frame even with the
// enumeration unmasked. The rebuilt index is where a shun table read once at
// startup instead of per generation shows up, so assert on it directly.
try std.testing.expect(ctx.snapshot.?.masked[1]);
try std.testing.expect(ctx.snapshot.?.store().lookup(send_shun_names[1]) == null);
try std.testing.expect(!ctx.snapshot.?.store().held(2));
}
try std.testing.expectEqual(@as(u64, 2), ctx.loads); // one build per log state
}
test "serve §3.8 / sync §9.5 L2170-2174: the snapshot cache key is not the size alone — a same-length write to the log invalidates it" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try seedSendShunRepo(gpa, io, tmp.dir);
const server = zit.sync.Server{ .version = serve_mod.server_version };
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const req = try serveGimmeRequest(gpa, "pull sc pc\nigot", shun_test_name);
defer gpa.free(req);
// Two read rounds over an untouched log: built once, then stat-gated. This is
// the property the mtime term must NOT cost — a read round still does not
// rebuild, so the cache is still a cache.
for (0..2) |_| {
const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
gpa.free(reply.body);
}
try std.testing.expectEqual(@as(u64, 1), ctx.loads);
const before = try file.stat(io);
// A write that leaves the log BYTE-IDENTICAL and exactly as long: the last byte
// is lifted off and put straight back. Nothing a `zit` writer does today looks
// like this — they all append — but "every writer only appends" is an assumption
// about all present and future writers, not a checked property, and since this
// snapshot began carrying the §3.3 shun table a missed rebuild no longer costs
// stale CONTENT (self-correcting) but a stale SUPPRESSION TABLE: an artifact the
// operator shunned served on, with nothing failing and nothing logged.
{
var f = try tmp.dir.openFile(io, repo_filename, .{ .mode = .read_write });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, before.size);
var last: [1]u8 = undefined;
try std.testing.expectEqual(@as(usize, 1), try fs.storageFile().pread(before.size - 1, &last));
try fs.storageFile().truncate(before.size - 1);
var reopened = storage.FileStorage.init(io, f, before.size - 1);
try reopened.storageFile().append(&last);
try reopened.storageFile().sync();
}
// THE PREMISE, asserted rather than assumed: the log really is the same length
// and the filesystem really did move the modification time. A filesystem that
// could not express this scenario fails here, loudly, instead of letting the
// conclusion below pass vacuously.
const after = try file.stat(io);
try std.testing.expectEqual(before.size, after.size);
try std.testing.expect(after.mtime.nanoseconds != before.mtime.nanoseconds);
// THE CONCLUSION: the size-only gate would have returned the stale snapshot and
// its stale shun table. The size+mtime key rebuilds.
{
const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
gpa.free(reply.body);
}
try std.testing.expectEqual(@as(u64, 2), ctx.loads);
try std.testing.expectEqual(after.mtime.nanoseconds, ctx.snapshot_log_mtime_ns);
// ...and having rebuilt, it settles again: the key is stable, not a rebuild on
// every round.
{
const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
gpa.free(reply.body);
}
try std.testing.expectEqual(@as(u64, 2), ctx.loads);
}
test "sync §7.2 L1265-1266 / §9.5 L2170-2174: a surviving delta whose basis is masked is served in FULL form, never as a dangling DELTASRC" {
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
// `zit shun --defer` records the row without rewriting the generation, so a
// SURVIVING frame in the current generation can still be a delta rooted on
// the shunned one. Handing that delta's wire form out would emit a `cfile`
// whose DELTASRC is never sent: the peer stores a permanently dangling delta
// and gimme's a basis it will be silently skipped on — CORRUPT, not absent.
const base_plain = "the quick brown fox jumps over the lazy dog, and then again once more";
const child_plain = "the quick brown fox jumps over the lazy dog, and then twice more, at last";
const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
{
var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
defer f.close(io);
var fs = storage.FileStorage.init(io, f, 0);
var log = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
defer log.deinit(gpa);
try log.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "" });
const base_rid = try log.put(send_shun_digests[0], base_plain);
const d = try zit.delta.create(gpa, base_plain, child_plain);
defer gpa.free(d);
_ = try log.putDelta(send_shun_digests[1], base_rid, d);
try log.putShun(send_shun_digests[0], "operator request", 1);
try log.commit();
}
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
const st = try file.stat(io);
{
var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
defer index.destroy();
const s = index.store();
// The premise: the child really is a delta frame rooted on the masked one.
try std.testing.expectEqual(logstore.FrameKind.delta, index.log.kindOf(index.rids[1]));
// The masked basis is a §8.2 gap...
try std.testing.expect(!s.held(1));
try std.testing.expect(s.wire(1) == null);
// ...so the child's DELTA wire form is withheld — the responder falls back
// to compressing `content()` on the fly (§7.2), which reconstructs against
// the raw log and is unaffected by the name-level mask.
try std.testing.expect(s.held(2));
try std.testing.expect(s.wire(2) == null);
try std.testing.expectEqualStrings(child_plain, s.content(2).?);
// Withholding a wire form for policy is not a read fault.
try std.testing.expect(!index.read_fault);
}
// End to end through a clone round: the child arrives, the basis does not, and
// the shunned NAME appears nowhere in the reply — no DELTASRC to dangle on.
const server = zit.sync.Server{
.version = serve_mod.server_version,
.self_servercode = serve_mod.server_servercode,
.project_code = serve_mod.server_projectcode,
};
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const clone_req = try zit.container.encode(gpa, "pragma client-version 20000\nclone 3 1\n", .default);
defer gpa.free(clone_req);
const reply = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
defer gpa.free(reply.body);
const body = reply.body; // §8.1 L1529-1531 / §4.1 L885-887 — uncompressed clone stream
try std.testing.expect(try replyHasCfile(gpa, body, send_shun_names[1]));
try std.testing.expect(std.mem.indexOf(u8, body, send_shun_names[0]) == null);
}
/// True when `dir`'s repository resolves `name` — read back off disk, after the
/// served round has persisted, so this answers "did it LAND", not "was it
/// staged".
fn s77RepoHolds(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, name: []const u8) !bool {
var file = try dir.openFile(io, repo_filename, .{});
defer file.close(io);
const st = try file.stat(io);
var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
defer index.destroy();
return index.store().lookup(name) != null;
}
test "sync §7.7 L1463-1467: the SERVED round's admission predicate is read from the repository's stored hash-policy, not defaulted" {
const gpa = std.testing.allocator;
const io = std.testing.io;
const content = "a SHA1-named artifact a peer pushes at us\n";
var nbuf: [64]u8 = undefined;
const sha1_name = zit.artifact.artifactName(.sha1, content, &nbuf);
try std.testing.expectEqual(@as(usize, 40), sha1_name.len);
const plain = try std.fmt.allocPrint(
gpa,
"pragma client-version 20000\npush {s} {s}\nfile {s} {d}\n{s}",
.{ serve_mod.server_servercode, serve_mod.server_projectcode, sha1_name, content.len, content },
);
defer gpa.free(plain);
const request = try zit.container.encode(gpa, plain, .default);
defer gpa.free(request);
const server = zit.sync.Server{
.version = serve_mod.server_version,
.self_servercode = serve_mod.server_servercode,
.project_code = serve_mod.server_projectcode,
};
// CONTROL: the same repository under `sha3` stores the pushed SHA1 name. If
// this half ever stops holding, the shun-sha1 half below proves nothing.
{
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try s77SeedPolicyRepo(gpa, io, tmp.dir, .sha3);
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
gpa.free(reply.body);
try std.testing.expect(try s77RepoHolds(gpa, io, tmp.dir, sha1_name));
}
// THE PROOF: the identical round against a repository whose stored config
// names shun-sha1 discards it — with no error card (L1437-1440) — and the
// ONLY difference between the two runs is that stored byte. A `serveRound`
// that defaulted the policy instead of reading the snapshot would store here.
{
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
try s77SeedPolicyRepo(gpa, io, tmp.dir, .shun_sha1);
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
defer gpa.free(reply.body);
const plain_reply = try zit.container.decode(gpa, reply.body, 1 << 20);
defer gpa.free(plain_reply);
try std.testing.expect(std.mem.indexOf(u8, plain_reply, "error ") == null);
try std.testing.expect(!try s77RepoHolds(gpa, io, tmp.dir, sha1_name));
}
}
test "submanifests §8.1/§7.2: a repository that HOLDS a leaf arms its serve-side gate against a pre-S peer" {
// The PRODUCTION wiring of the §7.2 gate, end to end through the durable
// store: `persistStore` records §8.1's seen-submanifest indicator for a
// stored SUBMANIFEST (which carries no S card at all, §4.4), the serve
// snapshot re-reads it, and `serveRound` arms the gate with it. Every link
// is load-bearing:
//
// * drop the `transferGatedArtifact` line in `phantomizeSubManifestRefs`
// and the indicator stays false — a leaf is not "S-bearing" literally;
// * drop `round_server.seen_submanifest = …` in `serveRound` and the gate
// is unarmed, because §8.1's emission setting is false on every zit;
// * drop `or self.seen_submanifest` from `Server.submanifestGateArmed`
// and it is unarmed for the same reason.
//
// Each of the three leaves the leaf in the reply to a fossil-2.28 peer,
// which §8 says can only hold it as "unreadable ... opaque content".
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var hex_buf: [2 * digest_len]u8 = undefined;
try serveSeedRepo(gpa, io, tmp.dir, 1, &hex_buf);
// §4.3: an F run with no D card is type SUBMANIFEST. The flat check-in
// manifest beside it is everything that predates this draft.
const leaf = "F a.txt " ++ (repeat("3", 64)) ++ "\n";
const flat = "C m\nD 2026-07-27T12:00:00.000\nF a.txt " ++ (repeat("2", 64)) ++ "\nU u\n";
var leaf_name: [2 * digest_len]u8 = undefined;
var flat_name: [2 * digest_len]u8 = undefined;
_ = zit.artifact.artifactName(.sha3_256, leaf, &leaf_name);
_ = zit.artifact.artifactName(.sha3_256, flat, &flat_name);
var ms = repostate.MemStore.init(gpa);
defer ms.deinit();
_ = try ms.store().put(&leaf_name, leaf);
_ = try ms.store().put(&flat_name, flat);
_ = try persistStore(gpa, io, tmp.dir, ms.store(), null, 0);
// §8.1 — the indicator is DURABLE and covers §7.2's type shape, not only
// its S-card shape. Read back through the same function the CLI uses.
var pc_buf: [zit.sync.max_projectcode_len]u8 = undefined;
const identity = try repoSyncIdentity(gpa, io, tmp.dir, "test-fixture-repo", &pc_buf);
try std.testing.expect(identity.seen_submanifest);
// …and the emission setting is the OTHER, independent half of the arming
// disjunction: this repository holds a gated artifact it received, and has
// never been told to emit one. A single flag could not tell the two apart.
try std.testing.expect(!identity.enable_submanifests);
// …and the served reply refuses the leaf to a peer announcing fossil 2.28,
// while still handing it the artifact it can read.
const server = zit.sync.Server{
.version = serve_mod.server_version,
.self_servercode = serve_mod.server_servercode,
.project_code = serve_mod.server_projectcode,
};
try std.testing.expect(!server.submanifests_enabled); // §8.1's default, stated
var file = try tmp.dir.openFile(io, repo_filename, .{});
defer file.close(io);
var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
defer ctx.deinit();
const plain = try std.fmt.allocPrint(
gpa,
"pragma client-version 22800\npull sc {s}\ngimme {s}\ngimme {s}\n",
.{ server.project_code, &leaf_name, &flat_name },
);
defer gpa.free(plain);
const request = try zit.container.encode(gpa, plain, .default);
defer gpa.free(request);
const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
defer gpa.free(reply.body);
const body = try zit.container.decode(gpa, reply.body, zit.sync.reply_body_cap);
defer gpa.free(body);
// Built through the same writer the server uses (§11.1's escape encoding
// applies to the text), so the expectation cannot drift from the emission.
var card_buf: [2 * zit.sync.submanifest_peer_error_text.len + 16]u8 = undefined;
const refusal = zit.sync.writeSignalCard(.err, zit.sync.submanifest_peer_error_text, &card_buf);
try std.testing.expect(std.mem.indexOf(u8, body, refusal) != null);
try std.testing.expect(std.mem.indexOf(u8, body, &leaf_name) == null);
try std.testing.expect(std.mem.indexOf(u8, body, &flat_name) != null);
}