//! A sync client session's state: the repository's sync identity, the
//! log-backed holdings the client announces, what it admits and drops,
//! the cursor and cone it resumes from, and what a pull run returns. No
//! CLI and no transport: the verbs drive it, a front end can too.
const std = @import("std");
const File = std.Io.File;
const LogIndexStore = @import("log_index_store.zig").LogIndexStore;
const SparseClassification = @import("../sparse.zig").SparseClassification;
const artifact = @import("../artifact.zig");
const cone_mod = @import("../cone.zig");
const logstore = @import("../logstore.zig");
const openLogAdoptingIndex = @import("log_index_store.zig").openLogAdoptingIndex;
const repocache = @import("../repocache.zig");
const repostate = @import("../repostate.zig");
const sparse = @import("../sparse.zig");
const storage = @import("../storage.zig");
const store_open = @import("store_open.zig");
const structgraph = @import("../structgraph.zig");
const sync = @import("../sync.zig");
const thinned = @import("../thinned.zig");
const repeat = @import("../repeat.zig").repeat;
const repo_filename = @import("../repository.zig").repo_filename;
/// §9.1 — a fixed placeholder repository identity emitted in the client's
/// pull/push operation cards. Neither a fresh clone nor a pulled repository
/// carries a persistent SERVERCODE/PROJECTCODE of its own yet (real per-repo
/// sync identity is future work). A server refuses a push or pull naming
/// another project (sync §8.5 L1688-1689); `serve` and the client verbs both
/// fall back to this placeholder for a repository with no stored code, so two
/// such repositories still agree. Shared by clone and pull.
pub const sync_servercode = "0000000000000000";
pub const sync_projectcode = "0000000000000000";
/// §10.1 — the release integer the sync client announces as `pragma
/// client-version`. A fixed build identity, matching `serve`'s own version
/// constant style.
pub const sync_client_version: u32 = 22700;
/// §10.1 r11/r12 — the DATED client-version pragma every zit run announces.
///
/// The DATE and TIME are not decoration: §10.1 r11/r12 make the server's
/// `server-version` reply conditional on them ("at least five tokens total"),
/// and that reply is the only way this client learns the peer's release
/// integer. An undated pragma leaves `Client.peer.version` at 0 for the whole
/// session, so every decision that reads it — §6.5's choice of login channel
/// among them — answers for a peer that announced nothing. Fossil sends the
/// dated form too (§A.4). (Sub-manifest support is not learned this way:
/// submanifests §7.2's gate reads the `send-submanifests` pragma, which a zit
/// server sends whether or not the request was dated.)
pub const sync_client_version_info: sync.VersionInfo = .{
.version = sync_client_version,
.datetime = .{ .date = 20260715, .time = 0 },
};
/// An explicit bound on CONSECUTIVE ROUNDS THAT MOVE NO BYTES (TigerStyle:
/// every loop is bounded). See `sync_driver.runSync` for why the bound counts
/// stalls rather than rounds: a total-round cap multiplies out against the
/// per-round batch size into an accidental ceiling on repository size, which a
/// large healthy repository trips while converging perfectly.
///
/// This value bounds only unproductive looping, so it is a statement about how
/// long a peer may accomplish nothing — not about how much there is to
/// transfer. §3.7's longest by-design stall is the unversioned three-round
/// grace window ((d)(2)); config exchange (f) and private-content discovery (c)
/// are each shorter. 16 clears every one of them several times over while still
/// failing a stuck peer in well under a second of round trips.
pub const max_stalled_sync_rounds: usize = 16;
/// A bounded copy of a peer error-card text, taken before the aborted sync
/// client goes out of scope so the CLI can quote the refusal.
pub const PeerErrorCopy = struct {
buf: [sync.peer_error_cap]u8 = undefined,
len: usize = 0,
pub fn set(self: *PeerErrorCopy, source: ?[]const u8) void {
const text_in = source orelse return;
std.debug.assert(text_in.len <= self.buf.len);
@memcpy(self.buf[0..text_in.len], text_in);
self.len = text_in.len;
}
pub fn text(self: *const PeerErrorCopy) ?[]const u8 {
if (self.len == 0) return null;
return self.buf[0..self.len];
}
};
/// The `/shun` rows a pull or sync latched off the peer, copied out of the
/// client before it is torn down, for `applySessionErasures`.
pub const ErasureLatch = struct {
rows: std.ArrayList(sync.OwnedShunRow) = .empty,
pub fn take(self: *ErasureLatch, gpa: std.mem.Allocator, latched: []const sync.OwnedShunRow) error{OutOfMemory}!void {
try self.rows.ensureUnusedCapacity(gpa, latched.len);
for (latched) |row| {
const hash = try gpa.dupe(u8, row.hash);
errdefer gpa.free(hash);
const reason = try gpa.dupe(u8, row.reason);
self.rows.appendAssumeCapacity(.{ .hash = hash, .epoch = row.epoch, .reason = reason });
}
}
pub fn deinit(self: *ErasureLatch, gpa: std.mem.Allocator) void {
sync.freeErasures(gpa, self.rows.items);
self.rows.deinit(gpa);
}
};
/// The causes `resolveRemoteUrl` can surface: a store read failure, OOM, or the
/// repository having no URL to use (`NoRemote` — neither an explicit arg nor a
/// saved remote). Closed set so the caller switches exhaustively.
const RemoteResolveError = error{ OutOfMemory, Storage, NoRemote };
/// sync §4/§6 — resolve the peer URL for a sync-family verb: an explicit `arg`
/// (non-empty) wins; otherwise the saved remote (`config.remote_url`) is used;
/// a repository with neither is a usage error (`NoRemote`). The saved URL is
/// copied into `buf` so it outlives the read-only config frame. `buf` need only
/// live until `transport.Transport.open` (which dupes the URL). An out-of-spec
/// stored URL longer than the config-field cap is treated as none.
pub fn resolveRemoteUrl(
gpa: std.mem.Allocator,
io: std.Io,
dir: std.Io.Dir,
arg: []const u8,
buf: *[logstore.max_config_str]u8,
) RemoteResolveError![]const u8 {
if (arg.len > 0) return arg;
var file = store_open.openStoreRead(io, dir) catch return error.Storage;
defer file.close(io);
const st = file.stat(io) catch return error.Storage;
var fs = storage.FileStorage.init(io, file, st.size);
var log = openLogAdoptingIndex(gpa, io, dir, fs.storageFile(), .refresh_on_scan) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
else => return error.Storage,
};
defer log.deinit(gpa);
return savedRemoteIn(gpa, &log, buf);
}
/// `resolveRemoteUrl`'s saved-remote half, over a log the caller holds open.
pub fn savedRemoteIn(gpa: std.mem.Allocator, log: *logstore.LogStore, buf: *[logstore.max_config_str]u8) RemoteResolveError![]const u8 {
var oc = (log.readConfig(gpa) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
else => return error.Storage,
}) orelse return error.NoRemote;
defer oc.deinit(gpa);
const saved = oc.config.remote_url;
if (saved.len == 0 or saved.len > buf.len) return error.NoRemote;
@memcpy(buf[0..saved.len], saved);
return buf[0..saved.len];
}
/// Sparse-cone RFC section 6.3 -- the post-run classification a cone-scoped
/// pull persists by, computed where the run's verdict is still being read.
pub const PostClassify = struct {
cone: *const cone_mod.Cone,
out: *?SparseClassification,
/// False for a commit's structural fetch: the elided nodes are what it
/// came for, so an absent one is still unmet.
settle_nodes: bool,
/// The holdings whose `.zit-cache` sidecar the classification extends,
/// so a pull classifies what arrived rather than the whole store again.
/// Null classifies the run's store in full.
cached: ?struct { io: std.Io, root_dir: std.Io.Dir, holdings: *ClientHoldings } = null,
};
/// Horizon draft section 4.2 -- reclassify `cls` over what the run received
/// and report whether that made some phantom wanted that `cls` had elided
/// (or that did not exist when `cls` was computed). `cls` is replaced in
/// place, so the run's elided set, which points at it, reads the new one.
pub fn reclassifyPull(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
holdings: *ClientHoldings,
cone: *const cone_mod.Cone,
cls: *SparseClassification,
) error{OutOfMemory}!bool {
const store = holdings.store();
const before = store.count();
var wanted = try std.DynamicBitSetUnmanaged.initEmpty(gpa, before + 1);
defer wanted.deinit(gpa);
var rid: repostate.Rid = 1;
while (rid <= before) : (rid += 1) {
if (!store.held(rid) and !cls.elided(rid)) wanted.set(rid);
}
var next = try sparse.classifyCached(gpa, io, root_dir, &holdings.index.log, holdings.index.classifyStore(), cone, .{ .boundary_transit = true }, .parse);
cls.deinit(gpa);
cls.* = next;
next = undefined;
// News is a phantom the classification now KEEPS -- a blob an arrived
// check-in of K names -- that it did not want before. A phantom that is
// merely unreferenced now (a boundary parent the origin has yet to
// label, a name only old manifests cite) is not: the origin decides it.
rid = 1;
while (rid <= store.count()) : (rid += 1) {
if (store.held(rid)) continue;
if (!(rid < cls.keep.capacity() and cls.keep.isSet(rid))) continue;
if (rid > before or !wanted.isSet(rid)) return true;
}
return false;
}
pub const PullOutcome = struct {
rounds: usize,
unresolved: usize,
deferred_trees: usize = 0,
uv_skipped: u64 = 0,
cluster_gaps: usize = 0,
/// Horizon draft section 6.2.3 -- the seed the origin sent this run, moved
/// out of the client; the caller persists it beside the store cone.
seed: ?[]u8 = null,
/// Horizon draft section 6.2.6 -- the origin's cursor from this run's
/// replies, null when it sent none.
peer_cursor: ?u64 = null,
/// Horizon draft section 6.2.4 -- the origin's merge-base answer, when the
/// run asked: the base's hash, or an empty slice for "no common ancestor".
/// Null when the origin did not answer.
mergebase_answered: bool = false,
mergebase_buf: [64]u8 = undefined,
mergebase_len: u8 = 0,
cone_mode: ConeMode = .none,
/// Horizon draft section 6.2.5 -- the level the origin said it served;
/// null against a horizon-ignorant peer.
horizon_served: ?sync.HorizonLevel = null,
horizon_url: HorizonUrl = .{},
/// Fold a re-run of the same pull into this one: totals add, the verdicts
/// are the later run's, and what the origin said last is what holds.
pub fn absorb(self: *PullOutcome, gpa: std.mem.Allocator, more: PullOutcome) void {
self.rounds += more.rounds;
self.uv_skipped += more.uv_skipped;
self.unresolved = more.unresolved;
self.deferred_trees = more.deferred_trees;
self.cluster_gaps = more.cluster_gaps;
self.cone_mode = more.cone_mode;
if (more.seed) |b| {
if (self.seed) |old| gpa.free(old);
self.seed = b;
}
if (more.peer_cursor) |cur| self.peer_cursor = cur;
if (more.horizon_served) |level| {
self.horizon_served = level;
self.horizon_url = more.horizon_url;
}
if (more.mergebase_answered) {
self.mergebase_answered = true;
self.mergebase_buf = more.mergebase_buf;
self.mergebase_len = more.mergebase_len;
}
}
};
/// Sparse-cone RFC section 6.3 -- whether each cone-scoped reply said
/// `pragma cone-served`. Unacknowledged replies were filtered locally; the
/// result is correct either way, only the bandwidth differs.
pub const ConeMode = enum {
none,
served,
filtered,
mixed,
pub fn phrase(self: ConeMode) []const u8 {
return switch (self) {
.none, .served => "applied by the peer",
.filtered => "filtered locally; the peer did not acknowledge the cone",
.mixed => "partly filtered locally; the peer acknowledged the cone in some replies",
};
}
};
pub fn coneMode(client: *const sync.Client) ConeMode {
if (client.cone_members.len == 0) return .none;
if (client.cone_replies_unacknowledged == 0) return .served;
return if (client.cone_replies_served == 0) .filtered else .mixed;
}
pub const RepoElidedSet = struct {
classification: *const SparseClassification,
store: repostate.ArtifactStore,
/// False for a commit's structural fetch, which exists to obtain the
/// elided sub-manifest nodes a commit needs (RFC section 5.3).
nodes: bool = true,
fn contains(context: *anyopaque, name: []const u8) bool {
const self: *const RepoElidedSet = @ptrCast(@alignCast(context));
if (self.nodes and self.classification.elidedNode(name)) return true;
const rid = self.store.lookup(name) orelse return false;
return self.classification.elided(rid);
}
pub fn shunSet(self: *RepoElidedSet) sync.ShunSet {
return .{ .context = @ptrCast(self), .vtable = &.{ .contains = contains } };
}
};
/// sync §3.3 L553-556 / §7.7 L1469-1472 — the two repository-local inputs to the
/// receive-side filters, as ONE value. They are halves of one question (§7.7's
/// combined target predicate reads both; §3.3's phantom scan reads the table),
/// they are always read off the same open, and a client wired with one but not
/// the other silently applies half a filter with nothing failing. Travelling as
/// a pair is what makes that unrepresentable: `syncClient` takes this struct, so
/// there is exactly one place either field is handed to a `Client`.
///
/// `shun` borrows the caller's `RepoShunSet`, which must outlive the run.
pub const RepoAdmission = struct {
shun: sync.ShunSet,
hash_policy: artifact.HashPolicy,
/// RFC section 5.2 rule 3 -- `.none` for every dense store.
elided: sync.ShunSet = .none,
/// RFC section 6.1 -- the store cone's raw members, borrowed from the
/// run-lifetime cone; empty for a dense store. The client encodes them
/// as `pragma cone MEMBER` cards so a cone-aware peer filters replies.
cone_members: []const []const u8 = &.{},
/// The store cone's exclusion members (`pragma cone-not MEMBER`).
cone_not_members: []const []const u8 = &.{},
/// The store cone's parents property: its inclusions travel as
/// `pragma cone-parents MEMBER` (sparse-cone RFC section 6.1).
cone_parents: bool = false,
/// Horizon draft section 6.1 -- the store cone's temporal member, borrowed
/// from the run-lifetime cone; null for a store without one.
horizon: ?cone_mod.Horizon = null,
/// Horizon draft section 6.2.3 -- the name of the seed this store holds,
/// offered so the origin re-sends only on change. Borrowed; null offers `-`.
seed_held: ?[]const u8 = null,
/// Horizon draft section 6.2.6 -- the origin position the last exchange
/// with this remote reached, and the first local rid not yet announced to
/// it (see `SyncCursor`).
horizon_cursor: ?u64 = null,
announce_from: repostate.Rid = 1,
/// Horizon draft section 6.2.4 -- a merge-base query to carry on the first
/// request of the run. Borrowed.
mergebase_query: ?sync.MergeBaseQuery = null,
/// Signed erasures a push or sync carries to the peer. Borrowed.
push_erasures: []const sync.ShunRow = &.{},
/// Where a pull or sync copies the `/shun` rows it asked the peer for on
/// its first round; null asks for none.
erasure_latch: ?*ErasureLatch = null,
};
/// Horizon draft section 6.1 -- the cone a synchronization runs under: the
/// stored one and, under a structural horizon, the held entries this store
/// states, so the origin keeps serving what it served when the rule's K moves
/// past it. The classification and the cursor key on the result, so a held
/// set that changed voids a cursor taken under the old one. Anything that
/// stops the entries being read leaves the stored cone, and the request
/// states none.
pub fn readSyncCone(gpa: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, holdings: *const ClientHoldings) ?cone_mod.Cone {
var stored = repocache.readStoreCone(gpa, io, root_dir) orelse return null;
const h = stored.horizon orelse return stored;
if (h.depth != .structural) return stored;
var arena_state = std.heap.ArenaAllocator.init(gpa);
defer arena_state.deinit();
const held = heldEntries(gpa, arena_state.allocator(), io, root_dir, holdings, h.hash) catch return stored;
if (held.len == 0) return stored;
const with = cone_mod.Cone.initFrom(gpa, &stored, .{ .hash = h.hash, .rule = h.rule, .depth = h.depth, .held = held }) catch return stored;
stored.deinit(gpa);
return with;
}
/// Horizon draft section 6.1 -- this store's held entries: the check-ins it
/// holds whose primary parent it does not, C aside (it is implied). A root
/// has no primary parent to hold, so a held root is one: the leaves rule
/// puts a root in K when a childless check-in's ancestry meets C's only
/// there, and once that check-in gains a child, only the root as an entry
/// keeps serving, and keeping, the branch the clone holds from it. A
/// baseline below the horizon is held for its delta's sake (section 5.1) and
/// looks the same, but stating it would serve its descendants, C's ancestry
/// among them; it counts only when the seed applies tags to it, which the
/// origin does for entries alone (section 5.2.1). Read from the structural
/// graph, which the store keeps beside it and extends by what arrived since.
/// Oldest first, at most `max_held`. Slices live in `arena`.
fn heldEntries(gpa: std.mem.Allocator, arena: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, holdings: *const ClientHoldings, c_hash: []const u8) error{OutOfMemory}![]const []const u8 {
const store = holdings.index.classifyStore();
var graph = try structgraph.Graph.loadOrBuild(gpa, io, root_dir, &holdings.index.log, store);
defer graph.deinit(gpa);
var seeded: std.StringHashMapUnmanaged(void) = .empty;
if (repocache.readHorizonSeed(gpa, io, root_dir)) |bytes| {
defer gpa.free(bytes);
if (artifact.parse(arena, bytes)) |seed| {
for (seed.t) |t| if (t.target) |target| try seeded.put(arena, try std.ascii.allocLowerString(arena, target), {});
} else |_| {}
}
var baselines = try std.DynamicBitSetUnmanaged.initEmpty(arena, @as(usize, graph.n) + 1);
var rid: repostate.Rid = 1;
while (rid <= graph.n) : (rid += 1) {
const rec = graph.record(rid) orelse continue;
if (rec.kind == .manifest) if (rec.baseline) |b| baselines.set(b);
}
var out: std.ArrayListUnmanaged([]const u8) = .empty;
rid = 1;
while (rid <= graph.n and out.items.len < cone_mod.max_held) : (rid += 1) {
const rec = graph.record(rid) orelse continue;
if (rec.kind != .manifest or (rec.parents.len != 0 and rec.parents[0] != 0)) continue;
const name = try std.ascii.allocLowerString(arena, store.hashOf(rid));
if (std.mem.eql(u8, name, c_hash)) continue;
if (baselines.isSet(rid) and !seeded.contains(name)) continue;
try out.append(arena, name);
}
return out.items;
}
/// The held seed's name (the hash of the sidecar's bytes), or null when the
/// store holds none. `buf` outlives the run that offers it.
pub fn heldSeedName(gpa: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, buf: *[64]u8) ?[]const u8 {
const bytes = repocache.readHorizonSeed(gpa, io, root_dir) orelse return null;
defer gpa.free(bytes);
return artifact.artifactName(.sha3_256, bytes, buf);
}
/// Horizon draft section 6.2.6 -- where the last successful exchange with
/// one remote left both sides: the origin's log position its replies were
/// served from (`peer`), and this store's log count at the end of the run
/// (`local`), so the next request carries neither an inventory of what the
/// origin sent nor one of what it already received. Advisory: without it a
/// request announces everything, as before. One member, one remote: a sync
/// with a different URL replaces it.
const SyncCursor = struct { peer: ?u64, local: repostate.Rid };
const sync_cursor_member = "horizon-cursor";
/// A remote is the same remote with or without its trailing slash (the saved
/// remote carries one, an explicit URL usually does not).
fn cursorUrl(url: []const u8) []const u8 {
return std.mem.trimEnd(u8, url, "/");
}
/// The cursor is a position in what the origin served THIS cone: a deepen or
/// any other cone change makes older holdings newly kept, which a cursor
/// taken under the old cone would tell the origin not to announce. So the
/// record names the cone's digest, and a cursor for another cone is none.
/// A cursor naming more local entries than `held`, the log-backed count, is
/// not one this log wrote, and announcing from it would skip check-ins the
/// origin never received; it reads as absent, so the next run announces
/// everything once.
pub fn readSyncCursor(gpa: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, url: []const u8, cone: *const cone_mod.Cone, held: repostate.Rid) ?SyncCursor {
const blob = (repocache.loadMember(gpa, io, root_dir, sync_cursor_member) catch return null) orelse return null;
defer gpa.free(blob);
var it = std.mem.splitScalar(u8, blob, '\n');
if (!std.mem.eql(u8, it.next() orelse return null, "2")) return null;
if (!std.mem.eql(u8, it.next() orelse return null, cursorUrl(url))) return null;
const digest = cone.digest(gpa) catch return null;
if (!std.mem.eql(u8, it.next() orelse return null, &std.fmt.bytesToHex(digest, .lower))) return null;
const peer_tok = it.next() orelse return null;
const local_tok = it.next() orelse return null;
const peer: ?u64 = if (std.mem.eql(u8, peer_tok, "-")) null else std.fmt.parseInt(u64, peer_tok, 10) catch return null;
const local = std.fmt.parseInt(repostate.Rid, local_tok, 10) catch return null;
if (local > held) return null;
return .{ .peer = peer, .local = local };
}
pub fn writeSyncCursor(gpa: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, url: []const u8, cone: *const cone_mod.Cone, cur: SyncCursor) void {
const digest = cone.digest(gpa) catch return;
var out: std.ArrayListUnmanaged(u8) = .empty;
defer out.deinit(gpa);
out.print(gpa, "2\n{s}\n{s}\n", .{ cursorUrl(url), &std.fmt.bytesToHex(digest, .lower) }) catch return;
if (cur.peer) |p| out.print(gpa, "{d}\n", .{p}) catch return else out.appendSlice(gpa, "-\n") catch return;
out.print(gpa, "{d}\n", .{cur.local}) catch return;
repocache.storeNamedMember(io, root_dir, sync_cursor_member, out.items);
}
/// The ONE construction of a sync `Client` from repository state. `pullRun`,
/// `pushRun` and `syncRun` differ only in the operation tag and whether a
/// credential is named, so everything else — the servercode, the version, and
/// both halves of `RepoAdmission` — is stated here once. Three copies of this
/// literal is how a repository filter comes to be wired into two verbs and not
/// the third.
pub fn syncClient(
op: sync.Operation,
identity: *const RepoSyncIdentity,
credential: ?sync.Credential,
admission: RepoAdmission,
) sync.Client {
return .{
.state = sync.initialState(op),
.operation = op,
.self_servercode = &identity.server_code,
.project_code = identity.project_code,
.version = sync_client_version_info,
// sync §6 — a named credential makes `buildRequest` emit the §6.1 login
// card; null leaves the session anonymous.
.credential = credential,
// sync §3.3 L553-556 — the per-round phantom scan's shun filter.
.shun = admission.shun,
.elided = admission.elided,
.cone_members = admission.cone_members,
.cone_not_members = admission.cone_not_members,
.cone_parents = admission.cone_parents,
.horizon = admission.horizon,
.seed_held = admission.seed_held,
.horizon_cursor = admission.horizon_cursor,
.announce_from = admission.announce_from,
.mergebase_query = admission.mergebase_query,
// sync §7.7 L1463-1467 — this repository's effective hash-policy, the
// SHA1-name half of the receive-side target-admission predicate.
.hash_policy = admission.hash_policy,
// submanifests §8.1/§7.2 — the durable indicator and the §8.1 emission
// setting together arm the §7.2 upload gate. A pull uploads nothing, so
// both are inert there; they are set for every operation so no caller has
// to remember which ones upload, which is the same reason the credential
// and the admission pair live here rather than at three call sites.
.seen_submanifest = identity.seen_submanifest,
.submanifests_enabled = identity.enable_submanifests,
// Every pull and sync session asks for the peer's `/shun` rows, and
// every push and sync carries this store's signed ones: the two
// places zit goes beyond Fossil, which moves rows only at clone and
// on an explicit `configuration pull`. A latched row is applied only
// if it verifies (`applySessionErasures`).
// A push asks too when it has rows to carry: only a row the peer's
// reply did not send back is pushed, on the next round.
.request_config = (admission.erasure_latch != null and (op == .pull or op == .sync)) or
(op == .push and admission.push_erasures.len != 0),
.push_erasures = if (op == .push or op == .sync) admission.push_erasures else &.{},
};
}
/// Horizon draft section 6.2.5 -- the history URL a reply carried, copied
/// out of the client before it goes.
pub const HorizonUrl = struct {
buf: [sync.max_horizon_url_len]u8 = undefined,
len: usize = 0,
pub fn of(client: *const sync.Client) HorizonUrl {
var h: HorizonUrl = .{};
const url = client.horizonUrl() orelse return h;
@memcpy(h.buf[0..url.len], url);
h.len = url.len;
return h;
}
pub fn get(self: *const HorizonUrl) ?[]const u8 {
return if (self.len == 0) null else self.buf[0..self.len];
}
};
/// The repository shun set widened by the seeds this store dropped on
/// receipt (horizon draft section 5.2.3) and by the file versions it thinned
/// (`purge artifacts`), so the client neither asks for one again nor counts it
/// as missing, and a copy a peer sends anyway is discarded as a shunned one
/// is. Only the client sees it: the shun table itself, which peers receive,
/// is untouched, so thinning stays local.
const DroppedSeedSet = struct {
base: sync.ShunSet,
names: std.StringHashMapUnmanaged(void) = .empty,
thinned: thinned.Set = .{},
fn load(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, base: sync.ShunSet) error{ OutOfMemory, Storage }!DroppedSeedSet {
var set: DroppedSeedSet = .{ .base = base };
errdefer set.deinit(gpa);
const names = try repocache.readDroppedSeeds(gpa, io, dir);
defer gpa.free(names);
for (names, 0..) |n, i| {
const gop = set.names.getOrPut(gpa, n) catch |e| {
for (names[i..]) |rest| gpa.free(rest);
return e;
};
if (gop.found_existing) gpa.free(n);
}
// Fail closed: a list that cannot be read would let this pull fetch
// every thinned version straight back.
set.thinned = thinned.load(gpa, io, dir) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
else => return error.Storage,
};
return set;
}
fn deinit(self: *DroppedSeedSet, gpa: std.mem.Allocator) void {
var it = self.names.keyIterator();
while (it.next()) |k| gpa.free(k.*);
self.names.deinit(gpa);
self.thinned.deinit(gpa);
}
fn contains(context: *anyopaque, name: []const u8) bool {
const self: *const DroppedSeedSet = @ptrCast(@alignCast(context));
if (self.base.contains(name)) return true;
if (self.thinned.contains(name)) return true;
if (self.names.count() == 0) return false;
var buf: [64]u8 = undefined;
if (name.len > buf.len) return false;
return self.names.contains(std.ascii.lowerString(buf[0..name.len], name));
}
fn shunSet(self: *DroppedSeedSet) sync.ShunSet {
return .{ .context = @ptrCast(self), .vtable = &.{ .contains = contains } };
}
};
/// The sync client's holdings view, log-backed and lazy. The clients
/// used to snapshot every stored artifact into a `MemStore` (`loadRepoHoldings`)
/// before the first wire byte, which resident-loaded the whole store's
/// plaintext per pull/push/sync — 3.7 GB for a 147,920-artifact store, an OOM
/// kill at tcl scale — just to announce igot names. This seats the client on
/// the serve side's `LogIndexStore` instead: names, held/phantom, the
/// shun mask, the hash-policy, and the config facts come off the frame index;
/// content and wire forms materialize per-rid on demand; received artifacts
/// land in the index's appendix `MemStore` and are the only new bytes
/// resident. `persistStore` then walks the same store — every pre-held rid
/// early-outs on the append log's own `lookup`, so persist stays flat too.
///
/// The read handle stays open across the run and the persist; readers take no
/// lock (`cli.openStoreRead`), so the append side's exclusive lock is not
/// contested by it.
pub const ClientHoldings = struct {
file: File,
index: *LogIndexStore,
gpa: std.mem.Allocator,
dropped: DroppedSeedSet,
pub fn open(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) error{ OutOfMemory, Storage }!ClientHoldings {
var h = try openHealed(gpa, io, dir);
h.dropped = DroppedSeedSet.load(gpa, io, dir, h.index.shun.shunSet()) catch |e| {
h.index.destroy();
h.file.close(io);
return e;
};
return h;
}
fn openHealed(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) error{ OutOfMemory, Storage }!ClientHoldings {
return openOnce(gpa, io, dir) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
// An interrupted write leaves an incomplete final frame, which
// the read-only open refuses and only a writer's open truncates.
// A sync exists to heal the repository, so it heals that first.
error.Corrupt => {
if (!healTornTail(gpa, io, dir)) return error.Storage;
return openOnce(gpa, io, dir) catch |e2| switch (e2) {
error.OutOfMemory => return error.OutOfMemory,
else => return error.Storage,
};
},
else => return error.Storage,
};
}
fn openOnce(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) error{ OutOfMemory, Storage, Corrupt }!ClientHoldings {
var file = store_open.openStoreRead(io, dir) catch return error.Storage;
errdefer file.close(io);
const st = file.stat(io) catch return error.Storage;
const index = LogIndexStore.openFromFileIndexed(gpa, io, file, st.size, dir) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
error.Corrupt => return error.Corrupt,
else => return error.Storage,
};
return .{ .file = file.file, .index = index, .gpa = gpa, .dropped = .{ .base = .none } };
}
/// Open the log for append under the writer lock, which truncates an
/// incomplete final frame, and close it. False when it cannot.
fn healTornTail(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) bool {
var sa = store_open.openStoreAppend(io, dir) catch return false;
defer sa.close(io);
const st = sa.file.stat(io) catch return false;
var fs = storage.FileStorage.init(io, sa.file, st.size);
var log = logstore.LogStore.open(gpa, fs.storageFile(), 0) catch return false;
log.deinit(gpa);
return true;
}
pub fn store(self: *ClientHoldings) repostate.ArtifactStore {
return self.index.store();
}
/// The number of already-durable, log-backed artifacts. Received
/// artifacts are appended beyond this, so persist begins here and never
/// re-walks the holdings a pull did not change.
pub fn logBackedCount(self: *ClientHoldings) repostate.Rid {
return @intCast(self.index.rids.len);
}
/// The §3.3/§7.7 admission pair, borrowed from the index — which outlives
/// the run exactly as the caller-owned `RepoShunSet` used to.
pub fn admission(self: *ClientHoldings) RepoAdmission {
self.dropped.base = self.index.shun.shunSet();
return .{ .shun = self.dropped.shunSet(), .hash_policy = self.index.hash_policy };
}
pub fn deinit(self: *ClientHoldings, io: std.Io) void {
self.dropped.deinit(self.gpa);
self.index.destroy();
self.file.close(io);
}
};
/// The durable config facts every sync-family run needs before it can build
/// a peer: §9.1's project code and draft-fossil-submanifests-00 §8.1's
/// seen-submanifest indicator and emission setting. Read together because they
/// come out of the same config frame — a second open to fetch another field
/// would be one more way for them to disagree about which frame they came from.
pub const RepoSyncIdentity = struct {
/// §9.1 — the adopted project code, or the zero placeholder.
project_code: []const u8,
/// submanifests §8.1 — has this repository ever stored a §7.2-gated
/// artifact? False for every repository predating this draft, and the
/// second thing that arms the §7.2 send gate (see `Server.seen_submanifest`).
seen_submanifest: bool,
/// submanifests §8.1 — the emission setting. The client twin of
/// `serveContext`'s server-side refresh: it is the OTHER half of the §7.2
/// arming disjunction (`Client.mayHoldSubmanifests`). Today it is
/// belt-and-braces, because any repository actually holding a gated artifact
/// also has `seen_submanifest` set — the two are written in one `log.commit`
/// with the first tree. It is threaded anyway so the field is never read
/// stale: leaving it at its `false` default would silently disarm the gate
/// for any future surface that commits mid-session, where the setting is on
/// but the indicator has not been written yet.
enable_submanifests: bool,
/// §9.1 — this instance's own SERVERCODE, derived from the checkout's
/// absolute path (`deriveServerCode`); informational on the wire and
/// never adopted from a peer. By value so the client's borrow has no
/// lifetime to manage beyond the identity itself.
server_code: sync.HashHex,
};
pub fn repoSyncIdentity(
gpa: std.mem.Allocator,
io: std.Io,
dir: std.Io.Dir,
abs: []const u8,
buf: *[sync.max_projectcode_len]u8,
) error{ OutOfMemory, Storage }!RepoSyncIdentity {
var file = store_open.openStoreRead(io, dir) catch return error.Storage;
defer file.close(io);
const st = file.stat(io) catch return error.Storage;
var fs = storage.FileStorage.init(io, file, st.size);
var log = openLogAdoptingIndex(gpa, io, dir, fs.storageFile(), .refresh_on_scan) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
else => return error.Storage,
};
defer log.deinit(gpa);
return syncIdentityIn(gpa, &log, abs, buf);
}
/// `repoSyncIdentity` over a log the caller holds open.
pub fn syncIdentityIn(
gpa: std.mem.Allocator,
log: *logstore.LogStore,
abs: []const u8,
buf: *[sync.max_projectcode_len]u8,
) error{ OutOfMemory, Storage }!RepoSyncIdentity {
var oc = (log.readConfig(gpa) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
else => return error.Storage,
}) orelse return .{
.project_code = sync_projectcode,
.seen_submanifest = false,
.enable_submanifests = sync.submanifest_emission_default,
.server_code = sync.deriveServerCode(&.{abs}),
};
defer oc.deinit(gpa);
const seen = oc.config.seen_submanifest;
const enabled = oc.config.enable_submanifests;
const server_code = sync.deriveServerCode(&.{abs});
const code = oc.config.project_code;
if (code.len == 0 or code.len > buf.len) return .{
.project_code = sync_projectcode,
.seen_submanifest = seen,
.enable_submanifests = enabled,
.server_code = server_code,
};
@memcpy(buf[0..code.len], code);
return .{
.project_code = buf[0..code.len],
.seen_submanifest = seen,
.enable_submanifests = enabled,
.server_code = server_code,
};
}
/// sync §9.1 — the repository's stored project code, copied into `buf`, or the
/// zero placeholder when the repo carries none (a repo predating the stored
/// code) or an out-of-spec-length one. `init` derives a project code and a
/// clone adopts the origin's (`storeClonedProjectCode`), so a real repo
/// announces its adopted code here; the pull/push client emits it verbatim as
/// the operation card's PROJECTCODE, and a real peer (fossil §9.1, ABNF
/// `pull-card = "pull" SP servercode SP projectcode`) refuses a mismatch — so a
/// zero placeholder would be rejected. Bounded by `max_projectcode_len`: a
/// longer stored field is out of spec and never truncated into the wire.
fn repoProjectCode(
gpa: std.mem.Allocator,
io: std.Io,
dir: std.Io.Dir,
buf: *[sync.max_projectcode_len]u8,
) error{ OutOfMemory, Storage }![]const u8 {
return (try repoSyncIdentity(gpa, io, dir, "test-fixture-repo", buf)).project_code;
}
test "sync §9.1: repoProjectCode returns the stored code, else the zero placeholder" {
const gpa = std.testing.allocator;
const io = std.testing.io;
const hash_kind: u8 = @backingInt(artifact.defaultPolicy(false, false));
const seed = struct {
fn withCode(g: std.mem.Allocator, i: std.Io, dir: std.Io.Dir, hk: u8, code: []const u8) !void {
var f = try dir.createFile(i, repo_filename, .{ .read = true, .exclusive = true });
defer f.close(i);
var fs = storage.FileStorage.init(i, f, 0);
var log = try logstore.LogStore.open(g, fs.storageFile(), hk);
defer log.deinit(g);
try log.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = code });
try log.commit();
}
};
// (a) a repo whose config stores a real 40-hex project code: it is returned
// verbatim — the code the pull/push card announces (§9.1), never the zeros
// fossil would refuse.
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const code = repeat("a1b2c3d4", 5); // 40 hex chars
try seed.withCode(gpa, io, tmp.dir, hash_kind, code);
var buf: [sync.max_projectcode_len]u8 = undefined;
const got = try repoProjectCode(gpa, io, tmp.dir, &buf);
try std.testing.expectEqualStrings(code, got);
try std.testing.expect(!std.mem.eql(u8, got, sync_projectcode));
// (b) a repo predating the stored code (empty project_code): the placeholder
// is the honest fallback (no adopted identity to announce yet).
var tmp2 = std.testing.tmpDir(.{});
defer tmp2.cleanup();
try seed.withCode(gpa, io, tmp2.dir, hash_kind, "");
var buf2: [sync.max_projectcode_len]u8 = undefined;
const got2 = try repoProjectCode(gpa, io, tmp2.dir, &buf2);
try std.testing.expectEqualStrings(sync_projectcode, got2);
}
test "sync §9.1: the pull request card carries the adopted project code, not the placeholder" {
const gpa = std.testing.allocator;
// The pull client, constructed exactly as `pullRun` does, with a stored code.
const code = repeat("a1b2c3d4", 5); // a real (non-zero) 40-hex project code
var client = sync.Client{
.state = sync.initialState(.pull),
.operation = .pull,
.self_servercode = sync_servercode,
.project_code = code,
.version = .{ .version = sync_client_version },
};
defer client.deinit(gpa);
var ms = repostate.MemStore.init(gpa);
defer ms.deinit();
var buf: std.ArrayListUnmanaged(u8) = .empty;
defer buf.deinit(gpa);
const request = try client.buildRequest(gpa, ms.store(), &buf);
// §9.1 ABNF `pull-card = "pull" SP servercode SP projectcode`: the adopted
// code MUST be the card's PROJECTCODE (a real peer refuses a mismatch).
const expected = "pull " ++ sync_servercode ++ " " ++ (repeat("a1b2c3d4", 5)) ++ "\n";
try std.testing.expect(std.mem.indexOf(u8, request, expected) != null);
// And the all-zero placeholder is NOT the project code the card announces.
const rejected = "pull " ++ sync_servercode ++ " " ++ sync_projectcode ++ "\n";
try std.testing.expect(std.mem.indexOf(u8, request, rejected) == null);
}
test "§10.1: the CLI announces a DATED client-version so the peer's version comes back" {
// §10.1 r11/r12 — the server replies `pragma server-version` exactly when
// the received client-version carried DATE and TIME. An undated pragma
// therefore leaves `Client.peer.version` at 0 for the whole session. This
// pins the one CLI constant that solicits the reply.
const gpa = std.testing.allocator;
try std.testing.expect(sync_client_version_info.datetime != null);
var ms = repostate.MemStore.init(gpa);
defer ms.deinit();
var client = sync.Client{
.state = sync.initialState(.pull),
.operation = .pull,
.self_servercode = sync_servercode,
.project_code = sync_projectcode,
.version = sync_client_version_info,
};
defer client.deinit(gpa);
var buf: std.ArrayListUnmanaged(u8) = .empty;
defer buf.deinit(gpa);
const request = try client.buildRequest(gpa, ms.store(), &buf);
// The emitted pragma carries at least §10.1 r11's five tokens.
const eol = std.mem.indexOfScalar(u8, request, '\n').?;
var tokens: usize = 0;
var it = std.mem.tokenizeScalar(u8, request[0..eol], ' ');
while (it.next()) |_| tokens += 1;
try std.testing.expect(std.mem.startsWith(u8, request, "pragma client-version "));
try std.testing.expect(tokens >= sync.min_datetime_tokens);
try std.testing.expect(sync.serverEmitsServerVersion(.{
.version = sync_client_version,
.datetime = sync_client_version_info.datetime,
}));
}