//! `zit shun`: record, list, sign and cancel shuns and erasures, and reclaim
//! the shunned bytes.
const std = @import("std");
const ErasureAppend = @import("session_erasures.zig").ErasureAppend;
const PackStats = @import("pack.zig").PackStats;
const applySessionErasures = @import("session_erasures.zig").applySessionErasures;
const artifact = zit.artifact;
const checkout = @import("zit").checkout;
const cli = @import("zit").cli;
const diagnostics = @import("../diagnostics.zig");
const digestToWireName = zit.digest_name.digestToWireName;
const digest_len = zit.digest_name.digest_len;
const help_pages = @import("../help.zig");
const holdsBytes = @import("session_erasures.zig").holdsBytes;
const lockRewrite = @import("pack.zig").lockRewrite;
const logProjectCode = @import("session_erasures.zig").logProjectCode;
const logstore = @import("zit").logstore;
const openErasureAppend = @import("session_erasures.zig").openErasureAppend;
const packOpenReadOnly = @import("sync_test_support.zig").packOpenReadOnly;
const packOpenWritable = @import("sync_test_support.zig").packOpenWritable;
const packSeedFullStore = @import("sync_test_support.zig").packSeedFullStore;
const pack_tmp_filename = @import("pack.zig").pack_tmp_filename;
const plural = @import("sync_dialogue.zig").plural;
const pluralEs = @import("sync_dialogue.zig").pluralEs;
const reasonOf = diagnostics.reasonOf;
const repeat = @import("zit").repeat;
const repoReadFail = diagnostics.repoReadFail;
const repo_filename = zit.repo_filename;
const rewriteAndSwap = @import("pack.zig").rewriteAndSwap;
const rewriteBusyFail = @import("pack.zig").rewriteBusyFail;
const rewrite_lock_name = @import("pack.zig").rewrite_lock_name;
const shunHexToDigest = @import("session_erasures.zig").shunHexToDigest;
const shun_help = help_pages.shun_help;
const stateOom = diagnostics.stateOom;
const storage = @import("zit").storage;
const storeReadFail = diagnostics.storeReadFail;
const tailChangedFail = @import("pack.zig").tailChangedFail;
const zit = @import("zit");
// ---------------------------------------------------------------------------
// `zit shun` — record artifacts in this repository's shun table and, by default,
// remove their bytes in the same operation.
//
// NO DRAFT SPECIFIES THIS VERB. sync §3.3 (docs/rfcs/
// draft-fossil-sync-protocol-00.txt L518-519) defines the repository shun table
// as "a persistent, repository-local set keyed by complete artifact name",
// L520-521 grants that "Local administration MAY add or remove names", and
// L527-530 makes the set mask the phantom scan. That is the whole of it: no
// draft names a command, an option, a report, a refusal, or the operation that
// removes a shunned artifact's bytes. Everything below — the refuse-by-default
// policy, the `--force` gate, the unconditional current-checkout stop, the
// per-type diagnostics — is this implementation's decision, and the choices are
// stated at the point that makes them rather than attributed to a section.
//
// The one advisory the plan of record cites for sub-manifests cannot be
// implemented or quoted here: there is no `submanifest` variant in
// `artifact.ArtifactType` on this branch (it runs manifest=1 .. forum=8) and no
// sub-manifest draft in docs/rfcs/. `shunConsequence`'s switch is total over
// that enum, so the day a ninth type lands the compiler demands its diagnostic
// — including the wider-blast-radius warning a sub-manifest deserves.
// ---------------------------------------------------------------------------
pub const NameSet = zit.pack.NameSet;
/// What a `zit shun` run will do about one hash the operator named. Split into
/// three groups by consequence, because the runner acts on the group, not the
/// member: the three `blocking` values stop the whole invocation before anything
/// durable happens; `remove`/`absent` each need a new tombstone; `reclaim` needs
/// no row but still has bytes to remove; `already` needs nothing at all.
const ShunDisposition = enum {
/// Held here: the rewrite drops its bytes and records its tombstone.
remove,
/// Already in the set from an earlier `--defer`, but the BYTES ARE STILL HERE:
/// no new row to write, and yet the removal the operator just asked for has
/// genuinely not happened. Grouping this with `already` is what would make
/// `zit shun --force H` after `zit shun --defer --force H` print "nothing to
/// do" and exit 0 with the content still readable — the worst sentence this
/// verb could produce, on the one path where an operator is acting under an
/// order. So it is its own disposition: no tombstone, but a rewrite.
reclaim,
/// Not held here: the tombstone is recorded and nothing is reclaimed. A
/// pre-emptive shun is meaningful and free — sync §3.3 L553-556 filters the
/// phantom scan on the set, so a name recorded before the artifact ever
/// arrives is never requested.
absent,
/// Already in the set AND already gone: a true no-op. `putShun` is idempotent
/// as set membership, so the durable row keeps the epoch and reason it was
/// written with.
already,
/// The manifest of the current checkout. REFUSED, with no `--force`
/// override — the one hard stop.
current_checkout,
/// Not a lowercase-hex artifact-name prefix at all.
not_a_name,
/// An abbreviated prefix matching no stored artifact. Refused rather than
/// recorded: the shun table is keyed by COMPLETE name, so a prefix cannot be
/// completed and a row keyed on one would name nothing.
unresolved,
/// A prefix matching more than one stored artifact.
ambiguous,
/// Whether this disposition stops the whole invocation before any durable
/// write. A total switch so a value added later cannot silently join the
/// permissive group.
fn blocks(self: ShunDisposition) bool {
return switch (self) {
.current_checkout, .not_a_name, .unresolved, .ambiguous => true,
.remove, .reclaim, .absent, .already => false,
};
}
/// Whether this disposition needs a new tombstone row.
fn records(self: ShunDisposition) bool {
return switch (self) {
.remove, .absent => true,
.reclaim, .already, .current_checkout, .not_a_name, .unresolved, .ambiguous => false,
};
}
/// Whether this disposition has BYTES for the rewrite to drop. Separate from
/// `records` precisely because the two are not the same question: `absent`
/// records without removing and `reclaim` removes without recording.
fn reclaims(self: ShunDisposition) bool {
return switch (self) {
.remove, .reclaim => true,
.absent, .already, .current_checkout, .not_a_name, .unresolved, .ambiguous => false,
};
}
};
/// One hash the operator named, resolved. `name` is the full lowercase-hex
/// artifact name — or, for the three unresolvable dispositions, the operator's
/// own token, which is all there is to name. `digest` is the raw binary key the
/// shun table and the pack filter both use, empty when there is none. `kind` is
/// null for an opaque blob (an artifact that does not parse as a structural one),
/// which is a first-class answer here exactly as it is for `zit artifact`.
const ShunTarget = struct {
name: []const u8,
digest: []const u8 = &.{},
kind: ?artifact.ArtifactType = null,
disposition: ShunDisposition,
};
/// The report label for a target's type. Structural artifacts use §5.1 Table 3's
/// external name (`artifact.ArtifactType.externalName`), the same vocabulary
/// `zit artifact` prints, so an operator sees one word per type across the CLI;
/// a blob is "file", matching `zit artifact`'s "type: file".
fn shunTypeLabel(kind: ?artifact.ArtifactType) []const u8 {
const t = kind orelse return "file";
return t.externalName();
}
/// The consequence of removing an artifact of this type, in one clause.
///
/// A TOTAL switch on `artifact.ArtifactType`, deliberately: the alternative is a
/// default arm, and a type added later would then get no diagnostic at all while
/// the operator was told the removal was safe. The six types that all lose the
/// same thing share one arm rather than repeating one sentence six times.
///
/// NO COUNTS, and that is a deliberate reduction from the intended report shape.
/// "N descendant check-ins become unresolvable" needs a public descendants
/// accessor over `repostate`'s child map plus a BFS, and "src/secret.key, in 6
/// check-ins" needs a reverse F-card index that exists nowhere in this tree —
/// producing either means decoding every manifest in the repository on the
/// refusal path, which is supposed to be the cheap path. The clause without the
/// count states the same consequence; the count is worth revisiting only
/// alongside the index that would make it cheap.
fn shunConsequence(kind: ?artifact.ArtifactType) []const u8 {
const t = kind orelse return "file content; every check-in listing it loses that file";
return switch (t) {
.manifest => "a check-in; its descendants become unresolvable",
.cluster => "sync housekeeping only; regenerable",
.submanifest => "part of a check-in's file list; every check-in whose tree names it stops enumerating",
.control, .wiki, .ticket, .attachment, .event, .forum => "structural content; what it renders stops rendering",
};
}
/// Render the hard stops: one line per blocking target, then nothing happens.
/// Every arm of the switch prints, including the non-blocking ones — a renderer
/// with an `unreachable` arm would be undefined behavior in `ReleaseFast`, which
/// is a poor trade for a line of output nobody should ever see.
fn renderShunBlockers(err: *std.Io.Writer, targets: []const ShunTarget) void {
for (targets) |t| switch (t.disposition) {
.current_checkout => {
err.print("zit shun: {s} is the check-in this checkout is on; refusing\n", .{t.name}) catch {};
err.writeAll("run 'zit update' to a different check-in first\n") catch {};
},
.not_a_name => err.print("zit shun: '{s}' is not an artifact name\n", .{t.name}) catch {},
.unresolved => err.print(
"zit shun: no artifact matches '{s}'; give the complete name to shun a hash this repository does not hold\n",
.{t.name},
) catch {},
.ambiguous => err.print("zit shun: hash '{s}' is ambiguous\n", .{t.name}) catch {},
.remove, .reclaim, .absent, .already => {},
};
}
/// How many rows already in `src`'s shun table still hold bytes that this run's
/// rewrite would drop, EXCLUDING the ones `targets` names (those are counted as
/// `.reclaim` targets and listed by name, so counting them here too would double
/// them). This is the clause the refusal — the consent gate — would otherwise be
/// silent about: `renderShunStats` is honest that `dropped` can exceed `recorded`,
/// but that honesty arrives after the deletion.
fn deferredStillHeld(src: *const logstore.LogStore, targets: []const ShunTarget) usize {
var n: usize = 0;
const all = src.shunList();
rows: for (all, 0..) |row, i| {
if (!src.isShunned(row.hash) or !holdsBytes(src, row.hash)) continue;
// A name folds several rows (an erasure and its cancel); count it once.
for (all[0..i]) |prev| {
if (std.mem.eql(u8, prev.hash, row.hash)) continue :rows;
}
for (targets) |t| {
if (std.mem.eql(u8, t.digest, row.hash)) continue :rows;
}
n += 1;
}
return n;
}
/// Render the default refusal: what this run would do, then stop. The register is
/// `clean`'s (`cleanRefuse` in cmd/tracking.zig) — the counts and the word
/// "refusing" in ONE line, so an operator learns nothing happened before reading
/// six lines of inventory, then the flag that proceeds, and never a prompt.
///
/// THREE counts, because they answer three different questions and only the first
/// used to be stated. How many rows become permanent (`recording` — including the
/// pre-emptive ones, which remove nothing). How much content this invocation's own
/// targets destroy (`removing` — which is NOT a subset of `recording`: a hash
/// shunned earlier with `--defer` records nothing and still has bytes to lose).
/// And `deferred_held`, the content the same rewrite reclaims from rows an EARLIER
/// run recorded — collateral the operator never named, which the success line
/// already admits to and the consent gate must not hide.
///
/// `defer_reclaim` IS A PARAMETER BECAUSE THE TWO RUNS ARE DIFFERENT OPERATIONS,
/// and this block's whole job is to state the operation accurately before an
/// irreversible act. A `--defer` run removes nothing NOW: describing it as "would
/// be permanently removed" overstates it, the `deferred_held` collateral clause is
/// about a rewrite that is not going to happen, and — worst — a suggestion of
/// `zit shun --force` would have an operator who copies it escalate a deferred
/// tombstone into a full-store reclaim of the whole union set, including collateral
/// the run never named. The suggested command is therefore always the one the
/// operator actually asked for, plus `--force`.
fn renderShunRefusal(
err: *std.Io.Writer,
targets: []const ShunTarget,
deferred_held: usize,
defer_reclaim: bool,
) void {
var recording: usize = 0;
var removing: usize = 0;
for (targets) |t| {
if (t.disposition.records()) recording += 1;
if (t.disposition.reclaims()) removing += 1;
}
err.writeAll("zit shun: ") catch {};
if (recording == 0) {
err.writeAll("no new hash would be recorded") catch {};
} else {
err.print("{d} hash{s} would be shunned in this repository", .{ recording, pluralEs(recording) }) catch {};
}
if (removing == 0) {
err.writeAll("; nothing you named holds content to remove") catch {};
} else if (defer_reclaim) {
// Named, still held, and deliberately NOT reclaimed by this run. "stays
// reconstructible" rather than merely "unreclaimed": the mask is on the
// name, so the plaintext is still materialisable through any surviving
// delta, which is precisely what an operator under a takedown order would
// otherwise assume they had already prevented.
err.print(
"; the bytes of {d} artifact{s} stay on disk and stay reconstructible until 'zit pack'",
.{ removing, plural(removing) },
) catch {};
} else {
err.print("; {d} artifact{s} would be permanently removed", .{ removing, plural(removing) }) catch {};
}
// Collateral of the REWRITE, so it is silent on the deferred path: there is no
// rewrite in a `--defer` run and those rows keep their bytes untouched.
if (deferred_held != 0 and !defer_reclaim) {
err.print(
"; the same rewrite also removes {d} artifact{s} shunned earlier and not yet reclaimed",
.{ deferred_held, plural(deferred_held) },
) catch {};
}
err.writeAll("; refusing without --force:\n\n") catch {};
for (targets) |t| switch (t.disposition) {
.remove => err.print(" {s} {s} {s}\n", .{
t.name,
shunTypeLabel(t.kind),
shunConsequence(t.kind),
}) catch {},
.reclaim => if (defer_reclaim) {
err.print(" {s} {s} already shunned; content still here and stays\n", .{
t.name,
shunTypeLabel(t.kind),
}) catch {};
} else {
err.print(" {s} {s} already shunned; content still here and would be removed\n", .{
t.name,
shunTypeLabel(t.kind),
}) catch {};
},
.absent => err.print(" {s} recorded only (not present in this repository)\n", .{t.name}) catch {},
.already => err.print(" {s} already shunned; content already gone\n", .{t.name}) catch {},
// Unreachable in practice (`renderShunBlockers` ran and the caller
// exited), but printed rather than asserted: see `renderShunBlockers`.
.current_checkout, .not_a_name, .unresolved, .ambiguous => err.print(
" {s} cannot be shunned\n",
.{t.name},
) catch {},
};
err.writeAll(
\\
\\This is irreversible: zit undo does not recover a shun, and the content
\\cannot be re-fetched from a peer.
\\
) catch {};
err.print("run 'zit shun {s}--force <HASH>...' to proceed\n", .{
if (defer_reclaim) "--defer " else "",
}) catch {};
}
/// One human line summarizing a completed reclaiming shun, in `renderPackStats`'s
/// register. `dropped` can EXCEED `shuns_recorded`, because the same rewrite also
/// reclaims any shun that was deferred earlier — an operator must be told that
/// rather than left to infer it from a byte count. Split out so the exact wording
/// is unit tested without a filesystem.
///
/// EVERY NUMBER HERE COMES FROM THE PACK, none from the caller's intent — which is
/// the whole reason `PackStats.shuns_recorded` exists. The rows this run meant to
/// write and the rows the new generation actually holds are two different facts,
/// and the one an operator is owed after a takedown is the second. `packLog`'s
/// row-count gate makes them equal or fails the pack; if that gate were ever
/// weakened, this line would under-report rather than over-report.
fn renderShunStats(out: *std.Io.Writer, stats: PackStats) void {
// `dropped` is counted among the source frames walked, so this subtraction
// cannot underflow. Asserted anyway, and precisely because it is a tautology:
// it is the only unchecked arithmetic in this verb's reporting, and an
// underflow would print an absurd remaining count rather than trap.
std.debug.assert(stats.dropped <= stats.artifacts);
out.print("shunned: {d} hash{s} recorded, {d} artifact{s} removed, {d} -> {d} remaining, {d} -> {d} bytes\n", .{
stats.shuns_recorded,
pluralEs(stats.shuns_recorded),
stats.dropped,
plural(stats.dropped),
stats.artifacts,
stats.artifacts - stats.dropped,
stats.bytes_before,
stats.bytes_after,
}) catch {};
}
/// `--defer`'s success line. It does NOT promise a byte count: nothing on this
/// path measured one, and the only honest number would require doing the rewrite
/// the operator just declined.
///
/// `recorded == 0` with `holding != 0` is the re-`--defer` of a hash already
/// deferred: no row to add, and yet content still to lose. Saying "0 hashes
/// recorded" there would read as a no-op on a repository that still holds the
/// bytes, so that case gets its own clause naming what is left.
///
/// `repo` is the `-R` the run was given, repeated in the hint so the command
/// it names reaches the same store from the same directory.
fn renderShunDeferred(out: *std.Io.Writer, recorded: usize, holding: usize, repo: ?[]const u8) void {
if (recorded == 0) {
out.print(
"shunned: no new hash to record; {d} artifact{s} still hold{s} content; ",
.{ holding, plural(holding), if (holding == 1) "s" else "" },
) catch {};
} else {
out.print("shunned: {d} hash{s} recorded; ", .{ recorded, pluralEs(recorded) }) catch {};
}
if (repo) |path| {
out.print("run 'zit pack -R {s}' to reclaim the space\n", .{path}) catch {};
} else out.writeAll("run 'zit pack' to reclaim the space\n") catch {};
}
/// The success line for a run with tombstones to write and NOTHING to reclaim —
/// the purely pre-emptive shun. It takes the append path rather than the rewrite
/// (see `runShun`), so there is no byte count to report and, more to the point,
/// nothing was removed: a line ending in a store that had GROWN would be the
/// wrong thing to print under the word "shunned".
fn renderShunRecordedOnly(out: *std.Io.Writer, recorded: usize) void {
out.print(
"shunned: {d} hash{s} recorded; none is held here, so nothing was removed\n",
.{ recorded, pluralEs(recorded) },
) catch {};
}
/// `--porcelain`: one `ACTION HASH` line per named hash, in argument order, after
/// the run has done what it reports — the shape `zit frames` uses for its header
/// and trailer lines (a keyword, then fields), so a forge logs exactly what
/// happened to each hash without parsing prose. `rewrote` is whether this run's
/// rewrite swapped in a new generation; it decides whether held content was
/// `reclaimed` or is still `deferred`.
///
/// reclaimed the bytes were removed (the row is new, or was deferred before)
/// deferred the row is recorded; the bytes stay on disk until `zit pack`
/// recorded the row is recorded; nothing was held here to remove
/// gone already shunned and already removed; nothing was done
///
/// Collateral the same rewrite reclaims from rows an earlier run deferred is not
/// listed: those hashes were reported `deferred` by the run that named them.
fn renderShunPorcelain(out: *std.Io.Writer, targets: []const ShunTarget, rewrote: bool) void {
for (targets) |t| {
const action: []const u8 = switch (t.disposition) {
.remove, .reclaim => if (rewrote) "reclaimed" else "deferred",
.absent => "recorded",
.already => "gone",
// A blocking target stops the run before anything is reported;
// named rather than `unreachable` for `renderShunBlockers`' reason.
.current_checkout, .not_a_name, .unresolved, .ambiguous => "refused",
};
out.print("{s} {s}\n", .{ action, t.name }) catch {};
}
}
/// Render shun's failure `err` as `zit shun: <reason>` on stderr, exit 1. On
/// every path that reaches this the store is byte-identical: either nothing was
/// written yet, or every write went to the temp the rewrite's `defer` deletes.
fn shunFail(s: cli.Streams, err: anyerror) cli.Exit {
s.err.print("zit shun: {s}\n", .{reasonOf(err)}) catch {};
return .failure;
}
/// The two shun-row rejections (`BadKey`, `ReasonTooLong`) that are unreachable by
/// construction here — every digest passed `isCompleteDigest` and every reason
/// passed the length gate — given a REAL phrase rather than left to `reasonOf`,
/// whose `else` arm renders both as "input/output error". Being unreachable is
/// exactly why the phrase matters: if one ever fires it is a key-width or
/// reason-length bug, and telling the operator their disk failed would send them
/// looking at hardware. Nothing durable has happened on either path.
fn shunRowBug(s: cli.Streams) cli.Exit {
s.err.writeAll("zit shun: internal error: a shun row was rejected as malformed; nothing was changed\n") catch {};
return .failure;
}
/// `shunAppendRows`' failure, with its two unreachable-by-construction arms routed
/// to `shunRowBug` instead of through `reasonOf`'s "input/output error" catch-all.
/// A torn append is truncated by the log's own recovery, so a failure here leaves
/// the shun simply absent, never half present.
///
/// `TailChanged` and `RewriteBusy` join the set for the reason `RewriteError`
/// carries them: neither is a failure of the append at all, both leave the store
/// exactly as it was, and both have the same operator-facing meaning here as they
/// do on the rewrite path — which is why they route to the SAME two diagnostics
/// rather than growing a second pair of sentences for the append.
const ShunAppendError = logstore.OpenError || logstore.ShunError || logstore.CommitError ||
error{ TailChanged, RewriteBusy, StoreBusy };
fn shunAppendFail(s: cli.Streams, err: ShunAppendError) cli.Exit {
return switch (err) {
error.OutOfMemory => stateOom(s, "shun"),
error.BadKey, error.ReasonTooLong => shunRowBug(s),
error.TailChanged => tailChangedFail(s, "shun"),
error.RewriteBusy => rewriteBusyFail(s, "shun"),
error.StoreBusy => .failure, // the lock notice already said it
else => shunFail(s, err),
};
}
/// Canonicalize a `zit shun` positional to a lowercase-hex artifact-name prefix,
/// or null when it is not one. The same band `zit artifact` accepts (4..64 hex),
/// deliberately: an operator pastes the same token into both verbs.
fn canonicalizeShunHex(arg: []const u8, out: *[2 * logstore.max_hash_len]u8) ?[]const u8 {
if (arg.len < 4 or arg.len > out.len) return null;
for (arg, 0..) |c, i| {
const lc = std.ascii.toLower(c);
if (!((lc >= '0' and lc <= '9') or (lc >= 'a' and lc <= 'f'))) return null;
out[i] = lc;
}
return out[0..arg.len];
}
/// Append `rows` to the live store and fsync — `--defer`'s whole effect, and the
/// path a `--force` run with nothing to reclaim takes too. One frame per row plus
/// one `commit`, so a crash mid-append leaves a torn tail the log's existing
/// recovery truncates: the shun is then simply absent, never half present.
/// Deliberately NOT the rewrite path: nothing here is atomic across rows, and
/// nothing needs to be, because each row is independently meaningful.
///
/// IT CARRIES BOTH OF `rewriteAndSwap`'S CONCURRENCY PROTECTIONS, for reasons that
/// are this path's own and not a symmetry argument.
///
/// The LOCK — the same exclusive non-blocking lock on the same fixed
/// `pack_tmp_filename`, so an append and a rewrite exclude each other. Without it a
/// `zit pack` (or another `zit shun --force`) that renames its new generation over
/// `.zit` after our `openFile` leaves us appending to an ORPHANED INODE: the row
/// lands nowhere anyone will ever read, and this run still reports success. On the
/// `--defer` path that means the deferred shun silently does not exist while the
/// help text has just told the operator to run `zit pack` to finish it. A cron'd
/// pack overlapping an operator's shun is an entirely ordinary way to hit that.
///
/// The TAIL RE-VALIDATION against `src_key` — because the caller classified its
/// targets against a snapshot taken before the lock existed, and both success
/// lines this path can print (`renderShunRecordedOnly`'s "none is held here, so
/// nothing was removed", `renderShunDeferred`'s count of what still holds content)
/// are claims about STORE STATE, not about the argument list. A `zit commit`
/// landing a named hash in that window makes the first of them false: the
/// tombstone would be recorded, exit 0, and an operator under a takedown order
/// told nothing was held while the bytes were live. Re-checking the tail on the
/// very handle the append will go through — under the lock, so no rename can have
/// intervened — turns that into an abort. `error.TailChanged` here means nothing
/// was written: the check precedes the first `putShun`.
///
/// The check reads the REOPENED handle rather than the caller's, and that is the
/// stronger of the two: a rewrite that completed just before we took the lock has
/// left the caller's handle pointing at an orphan whose tail still matches its own
/// key, while `.zit` by name is now a different generation. Validating the handle
/// we are about to WRITE is what makes that case an abort instead of an append
/// driven by a stale snapshot.
fn shunAppendRows(
gpa: std.mem.Allocator,
io: std.Io,
dir: std.Io.Dir,
src_key: logstore.LogStore.LogKey,
rows: []const logstore.ShunRecord,
) ShunAppendError!void {
// The rewrite lock, so no `pack` or `shun --force` runs underneath this
// append, then the writer lock inside it, in the order every rewrite takes
// them.
var rewrite_lock = try lockRewrite(io, dir);
defer rewrite_lock.release(io);
var store_append = cli.openStoreAppend(io, dir) catch |e| switch (e) {
error.StoreBusy => return error.StoreBusy,
else => return error.Storage,
};
defer store_append.close(io);
const file = store_append.file;
const st = file.stat(io) catch return error.Storage;
var fs = storage.FileStorage.init(io, file, st.size);
// A FRESH handle and a FRESH stat, for the same reason `rewriteAndSwap` takes
// them: the caller's view answers `size()` from the cached watermark its key
// was derived from, so asking it could never disagree.
if (!logstore.LogStore.validateTail(fs.storageFile(), src_key)) return error.TailChanged;
// The header of the existing repo carries the hash kind; `open` reads it from
// the non-empty file, so the passed value is a don't-care (0).
var log = try logstore.LogStore.open(gpa, fs.storageFile(), 0);
defer log.deinit(gpa);
for (rows) |row| try log.putShun(row.hash, row.reason, row.epoch);
try log.commit();
}
/// `zit shun` — record one or more artifacts in this repository's shun table and,
/// unless `--defer`, remove their bytes in the same operation.
///
/// POLICY, decided here and not by any draft: refuse by default and name the
/// consequence; require `--force` for BOTH paths, because `--defer` also appends
/// an irreversible tombstone and the read mask hides the content the instant it
/// lands; never prompt; refuse the current checkout's own check-in with no
/// override, because that is the one target whose removal breaks the tree the
/// operator is standing in and `zit update` is a cheap way out.
///
/// CRASH SAFETY. `--force` performs exactly ONE durable transition. When there is
/// content to remove that is the rename inside `rewriteAndSwap`, and the new
/// tombstones are written into the NEW generation (`packLog`'s `extra_shuns`),
/// never appended to `.zit` first — two durable transitions would expose a state
/// where the tombstone exists and the content still does. It also means an aborted
/// run leaves no tombstone at all: the rows were in the temp that the abort
/// deletes. Pinned by "runShun: a --force run the temp lock turns away records NO
/// tombstone".
///
/// When NOTHING is held — every named hash is pre-emptive — the single durable
/// transition is instead the append plus commit, and the rewrite is skipped
/// altogether. It is not load-bearing there: the rule exists to stop a tombstone
/// outliving its content, and with no content to remove the append is already
/// crash-safe under the log's torn-tail recovery. Running a whole-store rewrite to
/// reclaim nothing would cost O(store) plus transient room for both generations and
/// end with a report whose byte count had GROWN.
///
/// The rename is visible to a running `zit serve` DESPITE its held handle:
/// serve's `baseSnapshot` stats the path beside the handle each round and
/// reopens on an inode change, so the round after this swap serves the
/// rewritten generation — shunned content gone — with no restart.
pub fn runShun(
gpa: std.mem.Allocator,
io: std.Io,
arena: std.mem.Allocator,
verb_args: []const []const u8,
streams: cli.Streams,
amb: cli.Ambient,
) cli.Exit {
const parsed = switch (cli.parseShunArgs(arena, verb_args) catch return stateOom(streams, "shun")) {
.ok => |a| a,
.unknown_option => |tok| return cli.usageError(streams, "shun", .unknown_option, tok),
.extra_argument => |tok| return cli.usageError(streams, "shun", .extra_argument, tok),
};
if (parsed.help) {
streams.out.writeAll(shun_help) catch {};
return .ok;
}
if (parsed.hashes.len != 0 and std.mem.eql(u8, parsed.hashes[0], "key")) {
return runShunKey(gpa, io, arena, parsed, streams, amb);
}
if (parsed.hashes.len != 0 and std.mem.eql(u8, parsed.hashes[0], "cancel")) {
return runShunCancel(gpa, io, arena, parsed, streams, amb);
}
if (!parsed.list and parsed.hashes.len == 0) {
return cli.usageError(streams, "shun", .no_hash, "");
}
if (parsed.now and !parsed.sign) {
streams.err.writeAll("zit shun: --now applies to a signed erasure; add --sign\n") catch {};
return .usage;
}
if (parsed.json and !parsed.list) {
streams.err.writeAll("zit shun: -F json applies to --list and 'key generate'\n") catch {};
return .usage;
}
// A reason the durable row cannot hold is refused BEFORE anything is opened,
// and refused rather than truncated: the note on a shun is often the legal
// reference the operator will be asked for, and silently keeping a prefix of
// it is worse than making them shorten it themselves.
//
// A CONTROL BYTE IS REFUSED THE SAME WAY, and this is the reason `--reason` is
// validated at all rather than merely bounded. `--list` is the only view of a
// durable, irreversible, un-removable record, and `renderShunList` prints one
// row per line: a newline inside a reason forges a row there that is
// indistinguishable from a real one. Reasons arrive from scripts and from pasted
// takedown text as often as they are typed, so this is not a hand-typed-only
// hazard. Rejecting at input rather than escaping at render keeps the fix to one
// place and keeps the stored bytes exactly what the operator supplied. NO DRAFT
// SPEAKS TO THIS and `logstore.ShunError` has no arm for it — a local decision,
// taken the same way the length gate was: refuse rather than mangle.
if (parsed.reason) |r| {
if (r.len > logstore.max_shun_reason) {
streams.err.print(
"zit shun: --reason is {d} bytes; the recorded note is at most {d}\n",
.{ r.len, logstore.max_shun_reason },
) catch {};
return .failure;
}
for (r) |c| {
if (c >= 0x20 and c != 0x7f) continue;
streams.err.writeAll(
"zit shun: --reason contains a control byte; the recorded note must be a single line of text\n",
) catch {};
return .failure;
}
// The prefix that marks a signed statement. A plain note spelled
// with it would read as a statement that does not verify, and the
// shun would mask nothing.
if (std.mem.startsWith(u8, r, zit.erasure.prefix)) {
streams.err.print("zit shun: --reason may not begin with '{s}'\n", .{zit.erasure.prefix}) catch {};
return .failure;
}
// Nor be the note a store records once an erasure took effect.
if (zit.erasure.isApplied(r)) {
streams.err.print("zit shun: --reason may not be '{s}'\n", .{zit.erasure.applied_reason}) catch {};
return .failure;
}
}
// `-R` names a bare store as readily as a checkout: everything below is
// store-side except the current-checkout guard, which reads the checkout
// record of whatever directory was named and is empty on a bare store.
const root = (cli.resolveRoot(arena, io, amb.repo_override) catch return stateOom(streams, "shun")) orelse {
diagnostics.reportNoRoot(streams, io, "shun", amb.repo_override);
return .failure;
};
var root_dir = root.dir;
defer root_dir.close(io);
// shun is store-scoped end to end: the reads, the pack-tmp lock
// and the final rename must all land beside the STORE, so a detached
// worktree resolves its pointer once here and the whole flow inherits it.
if (cli.storeDirOf(io, root_dir) catch return repoReadFail(streams, "shun")) |resolved| {
root_dir.close(io);
root_dir = resolved;
}
// Open the source read-only, exactly as `pack` does, and for the same
// reasons — including the same caveat: this open no longer CRC-verifies
// payloads (it scans header-only), so a corrupt source aborts during the
// rewrite's own reads rather than here. Nothing is written either way. The
// tail key pins the log for the pre-rename re-check. See `runPack`'s doc
// comment for why that ordering matters to a verb that renames over `.zit`.
var src_file = cli.openStoreRead(io, root_dir) catch |e| return storeReadFail(streams, "shun", e);
defer src_file.close(io);
const src_st = src_file.stat(io) catch return repoReadFail(streams, "shun");
var src_fs = storage.FileStorage.init(io, src_file, src_st.size);
var src = logstore.LogStore.openReadOnly(gpa, src_fs.storageFile()) catch |e| switch (e) {
error.OutOfMemory => return stateOom(streams, "shun"),
else => |re| return shunFail(streams, re),
};
defer src.deinit(gpa);
if (parsed.list) {
if (parsed.json) {
renderShunListJson(streams.out, &src) catch {};
} else renderShunTable(streams.out, &src);
return .ok;
}
const src_key = src.logKey() catch return shunFail(streams, error.Corrupt);
// A signed erasure needs the owner key before anything is classified,
// so a refusal costs nothing.
var code_buf: [logstore.max_config_str]u8 = undefined;
const signer: ?ErasureSigner = if (parsed.sign)
(loadErasureSigner(gpa, io, &src, amb, &code_buf, streams) orelse return .failure)
else
null;
// An erasure that takes effect now is recorded as applied once it has
// landed, as a session records one it latched (`markErasuresApplied`).
defer if (signer != null and parsed.now) {
_ = applySessionErasures(gpa, io, root_dir, null, "shun", null, &.{}, false);
};
// The current checkout's own check-in, for the one refusal with no override.
// A `.zit-checkout` we cannot parse is a hard failure, not an empty answer:
// the guard would silently become vacuous and the operator would be allowed
// to delete the check-in they are standing on.
var ck_buf: [checkout.max_ck_payload + 1]u8 = undefined;
const ck_state = checkout.read(io, root_dir, &ck_buf) catch |e|
return diagnostics.checkoutFail(streams, "shun", e);
const ck_version: []const u8 = if (ck_state) |s| s.version else "";
// Classified, then DEDUPLICATED BY RESOLVED DIGEST — which is why it cannot be
// done in the parser. `zit shun --force H <prefix-of-H>` is one artifact named
// twice, and an operator pasting a takedown list beside an abbreviation from
// `zit log` cannot see that it is. Left folded in, the duplicate builds two
// identical rows, `putShun` collapses them, and `packLog`'s row-count gate —
// whose documented precondition is that `extra_shuns` rows are DISTINCT — fires
// `error.Corrupt`: the verb would tell the operator their repository is corrupt,
// on the one occasion they can least afford to doubt it. Deduping here rather
// than in `packLog` keeps that gate a gate. O(n^2) over an argument list.
const target_buf = arena.alloc(ShunTarget, parsed.hashes.len) catch return stateOom(streams, "shun");
var target_count: usize = 0;
tokens: for (parsed.hashes) |tok| {
const t = classifyShunTarget(gpa, arena, &src, ck_version, tok) catch |e|
return shunFail(streams, e);
// Only a resolved target can be a duplicate: the unresolvable dispositions
// carry the operator's own token and no digest, and two different bad tokens
// both deserve their own diagnostic line.
if (t.digest.len != 0) {
for (target_buf[0..target_count]) |prev| {
if (std.mem.eql(u8, prev.digest, t.digest)) continue :tokens;
}
}
target_buf[target_count] = t;
target_count += 1;
}
const targets = target_buf[0..target_count];
// THE GUARD RUNS BEFORE ANY DURABLE WRITE — the ordering is the point, not an
// implementation detail. A refused run must leave the store byte-identical,
// which it cannot do if a tombstone was recorded while deciding.
for (targets) |t| {
if (t.disposition.blocks()) {
renderShunBlockers(streams.err, targets);
return .failure;
}
}
// Two counts, and they are independent: `absent` records without removing,
// `reclaim` removes without recording. Either one alone is work to do.
var recorded: usize = 0;
var reclaiming: usize = 0;
for (targets) |t| {
if (t.disposition.records()) recorded += 1;
if (t.disposition.reclaims()) reclaiming += 1;
}
if (recorded == 0 and reclaiming == 0) {
// Every named hash was already in the set AND its content already gone: a
// genuine no-op, so it needs no `--force` and it is not a failure. Reaching
// this on a hash whose bytes SURVIVED is the defect `.reclaim` exists to
// prevent — it would report "nothing to do" over content the operator had
// just been ordered to remove.
if (parsed.porcelain) {
renderShunPorcelain(streams.out, targets, false);
} else streams.out.print(
"shunned: nothing to do; {d} hash{s} already shunned\n",
.{ targets.len, pluralEs(targets.len) },
) catch {};
return .ok;
}
if (!parsed.force) {
renderShunRefusal(streams.err, targets, deferredStillHeld(&src, targets), parsed.defer_reclaim);
return .failure;
}
// ONE owned name set drives both the drop predicate and the tombstone list,
// so a name cannot be recorded without also being dropped. It is the UNION of
// the source's already-deferred shuns and the hashes named now: `shunFilter`
// covers only the first half, and half a drop set would relocate into the new
// generation exactly the bytes this run reports as removed.
var set: NameSet = .{};
defer set.deinit(gpa);
for (src.shunList()) |row| if (src.isShunned(row.hash)) set.add(gpa, row.hash) catch |e| switch (e) {
error.OutOfMemory => return stateOom(streams, "shun"),
// A persisted row whose key is not a complete digest is a corrupt store,
// and that is the one place `BadKey` here can come from.
error.BadKey => return shunFail(streams, error.Corrupt),
};
const row_buf = arena.alloc(logstore.ShunRecord, recorded) catch return stateOom(streams, "shun");
var n: usize = 0;
for (targets) |t| {
if (!t.disposition.records()) continue;
set.add(gpa, t.digest) catch |e| switch (e) {
error.OutOfMemory => return stateOom(streams, "shun"),
error.BadKey => return shunRowBug(streams),
};
row_buf[n] = .{ .hash = t.digest, .epoch = amb.now_epoch, .reason = parsed.reason orelse "" };
if (signer) |sg| {
const nb = if (parsed.now) amb.now_epoch else amb.now_epoch + zit.erasure.default_delay;
row_buf[n].reason = sg.sign(arena, t.digest, amb.now_epoch, nb, .erase, parsed.reason orelse "") catch |e| switch (e) {
error.OutOfMemory => return stateOom(streams, "shun"),
error.ReasonTooLong => {
streams.err.writeAll("zit shun: --reason is too long for a signed erasure, whose signature shares the recorded note's 200 bytes\n") catch {};
return .failure;
},
else => return shunRowBug(streams),
};
}
n += 1;
}
// SLICED, not asserted-and-passed-whole. `recorded` and `n` count the same pure
// predicate over the same unmutated `targets`, so they cannot differ today — but
// `row_buf` is arena memory and the FULL buffer used to be what went to
// `packLog` and `shunAppendRows`. Had they ever differed, `row_buf[n..]` would
// be undefined `ShunRecord`s whose `hash` is a garbage slice, handed to
// `putShun` on the way to a durable irreversible write — in `ReleaseFast`, where
// the assert below does not exist. Taking the slice makes the mismatch
// unrepresentable and leaves the assert as documentation of the tautology.
const rows = row_buf[0..n];
std.debug.assert(rows.len == recorded);
// Nothing to reclaim: take the append path even without `--defer`. See the
// crash-safety note in the doc above — the rewrite is not what makes this safe,
// and running it would cost a whole-store copy to remove nothing.
if (reclaiming == 0) {
shunAppendRows(gpa, io, root_dir, src_key, rows) catch |e| return shunAppendFail(streams, e);
if (parsed.porcelain) {
renderShunPorcelain(streams.out, targets, false);
} else if (signer != null) {
renderErasureSigned(streams.out, rows.len, parsed.now, amb.now_epoch);
} else renderShunRecordedOnly(streams.out, rows.len);
return .ok;
}
// A signed erasure with a delay masks nothing yet, so nothing is reclaimed
// now: its bytes go at the first sync, pull or pack past its not-before.
if (parsed.defer_reclaim or (signer != null and !parsed.now)) {
// `rows` is empty when every target was already tombstoned and only its
// bytes remain; skip the append rather than fsync for nothing.
if (rows.len != 0) {
shunAppendRows(gpa, io, root_dir, src_key, rows) catch |e| return shunAppendFail(streams, e);
}
if (parsed.porcelain) {
renderShunPorcelain(streams.out, targets, false);
} else if (signer != null) {
renderErasureSigned(streams.out, rows.len, parsed.now, amb.now_epoch);
} else renderShunDeferred(streams.out, rows.len, reclaiming, amb.repo_override);
return .ok;
}
// THE CURRENT-CHECKOUT STOP, RE-ASKED OF THE DROP SET ITSELF — one hashmap
// lookup, at the point of consequence. `classifyShunTarget` enforces it over the
// NAMED TOKENS, but `set` is the union of those with every row already in the
// shun table, and the rewrite deletes the union. A table that already contained
// this check-in's manifest would therefore have `--force` delete the check-in the
// operator is standing in while the per-token guard never fired — the refusal
// line would count it only as an anonymous integer of earlier deferred
// collateral. That state is not constructible through zit today (`--defer` goes
// through the same per-token guard, and S1's mask makes `zit update` to a shunned
// check-in fail), which is exactly why the invariant belongs here as well: the
// property `shun_help` promises is about what gets deleted, not about the
// argument list.
if (ck_version.len != 0) {
var ck_raw: [logstore.max_hash_len]u8 = undefined;
if (shunHexToDigest(ck_version, &ck_raw)) |ck_digest| {
if (set.contains(ck_digest)) {
renderShunBlockers(streams.err, &.{.{
.name = ck_version,
.digest = ck_digest,
.disposition = .current_checkout,
}});
return .failure;
}
}
}
const stats = rewriteAndSwap(
gpa,
io,
root_dir,
&src,
src_key,
set.filter(),
rows,
) catch |e| switch (e) {
error.TailChanged => return tailChangedFail(streams, "shun"),
error.RewriteBusy => return rewriteBusyFail(streams, "shun"),
else => |pe| return shunFail(streams, pe),
};
// Reported from the PACK's observation of the new generation, not from
// `rows.len`: see `renderShunStats`. They agree or `packLog`'s row-count gate
// failed the pack, which is why this is an assert rather than a branch.
std.debug.assert(stats.shuns_recorded == rows.len);
if (parsed.porcelain) {
renderShunPorcelain(streams.out, targets, true);
} else renderShunStats(streams.out, stats);
return .ok;
}
// ---------------------------------------------------------------------------
// Signed erasures at the CLI: the owner key, `--sign`, `cancel`, the list, and
// the per-session carriage sync adds on top of Fossil's `/shun` rows. The
// statement itself (message, signature, SCOM grammar, key file) lives in
// src/erasure.zig; nothing here touches the crypto beyond calling it.
// ---------------------------------------------------------------------------
const erasure = zit.erasure;
/// The owner's private seed for one call, checked against the pinned key.
const ErasureSigner = struct {
seed: erasure.Seed,
project_code: []const u8,
/// The SCOM of a signed row for `digest`, arena-owned.
fn sign(self: ErasureSigner, arena: std.mem.Allocator, digest: []const u8, epoch: i64, nb: i64, kind: erasure.Kind, reason: []const u8) (erasure.SignError || error{OutOfMemory})![]const u8 {
var hex_buf: [2 * logstore.max_hash_len]u8 = undefined;
const hex = digestToWireName(digest, &hex_buf);
var out: [erasure.max_scom]u8 = undefined;
const scom = try erasure.sign(self.seed, .{ .project_code = self.project_code, .hash_hex = hex, .epoch = epoch }, nb, kind, reason, &out);
return arena.dupe(u8, scom);
}
};
/// The signer for `log`, or null with the reason already on stderr. The key
/// comes from `$ZIT_ERASURE_KEY` (64 hex) when set, so an application that
/// keeps it in a platform keychain hands it over per call, else from the key
/// file `zit shun key generate` wrote.
fn loadErasureSigner(
gpa: std.mem.Allocator,
io: std.Io,
log: *logstore.LogStore,
amb: cli.Ambient,
code_buf: *[logstore.max_config_str]u8,
streams: cli.Streams,
) ?ErasureSigner {
const pinned = log.erasureKey() orelse {
streams.err.writeAll("zit shun: no erasure key is pinned in this repository; run 'zit shun key generate' or 'zit shun key pin PUBKEY'\n") catch {};
return null;
};
const code = logProjectCode(gpa, log, code_buf) catch {
_ = repoReadFail(streams, "shun");
return null;
};
if (code.len == 0) {
streams.err.writeAll("zit shun: this repository has no project code to sign an erasure for\n") catch {};
return null;
}
const seed: erasure.Seed = if (amb.environ.getPosix("ZIT_ERASURE_KEY")) |text|
erasure.parseKeyHex(erasure.seed_len, text) orelse {
streams.err.writeAll("zit shun: ZIT_ERASURE_KEY is not a 64-hex private key\n") catch {};
return null;
}
else
erasure.readKeyFile(io, amb.environ, code) catch |e| {
switch (e) {
error.NotFound, error.NoHome => streams.err.writeAll(
"zit shun: no private erasure key on this device; set ZIT_ERASURE_KEY or run 'zit shun key generate'\n",
) catch {},
else => streams.err.writeAll("zit shun: the private erasure key file cannot be read\n") catch {},
}
return null;
};
const public = erasure.publicKeyOf(seed) catch {
streams.err.writeAll("zit shun: the private erasure key is not a usable Ed25519 seed\n") catch {};
return null;
};
if (!std.mem.eql(u8, &public, &pinned)) {
streams.err.writeAll("zit shun: the private erasure key does not match the key pinned in this repository\n") catch {};
return null;
}
return .{ .seed = seed, .project_code = code };
}
fn renderErasureSigned(out: *std.Io.Writer, recorded: usize, now: bool, epoch: i64) void {
if (now) {
out.print("erased: {d} hash{s} signed; none is held here, so nothing was removed\n", .{ recorded, pluralEs(recorded) }) catch {};
return;
}
var ts: [19]u8 = undefined;
out.print(
"erasure signed: {d} hash{s}; takes effect at {s} UTC; 'zit shun cancel HASH' undoes it before then\n",
.{ recorded, pluralEs(recorded), cli.formatWriterTimestamp(epoch + erasure.default_delay, &ts) },
) catch {};
}
/// The words `--list` uses for one row: its kind, whether its signature
/// verifies, and what its name's fold says.
const ShunListRow = struct {
kind: []const u8,
signer: []const u8,
state: []const u8,
not_before: ?i64,
};
fn shunListRow(log: *const logstore.LogStore, i: usize) ShunListRow {
const row = log.shunList()[i];
const st = log.shunRowState(i);
const status = log.shunStatus(row.hash);
const state: []const u8 = switch (status.state) {
.none, .inert => "inert",
.pending => "pending",
.shunned, .erased => "active",
};
return switch (st.kind) {
.plain => .{ .kind = "plain", .signer = "none", .state = state, .not_before = null },
.applied => .{ .kind = "applied", .signer = "none", .state = state, .not_before = null },
.erase => .{ .kind = "erase", .signer = "verified", .state = state, .not_before = st.not_before },
.cancel => .{ .kind = "cancel", .signer = "verified", .state = state, .not_before = st.not_before },
.unverified => .{ .kind = "signed", .signer = "unverified", .state = state, .not_before = null },
};
}
/// `--list`: the shun table in persisted order, one row per line — full artifact
/// name, the UTC date it was recorded, and the reason when one was given. The
/// date comes from `cli.formatWriterTimestamp`'s first ten bytes, so this shares
/// the CLI's one epoch formatter rather than growing a second.
fn renderShunList(out: *std.Io.Writer, rows: []const logstore.ShunRecord) void {
if (rows.len == 0) {
out.writeAll("the shun table is empty\n") catch {};
return;
}
for (rows) |row| renderShunRow(out, row, null);
}
/// `renderShunList` over the store, which knows what each row's reason says:
/// a signed row names its kind (`erase`, `cancel`), its name's state
/// (`pending`, `active`, `inert`), its not-before, and whether its signature
/// verifies against the pinned key, and its note is the statement's reason.
fn renderShunTable(out: *std.Io.Writer, log: *const logstore.LogStore) void {
const rows = log.shunList();
if (rows.len == 0) return renderShunList(out, rows);
for (rows, 0..) |row, i| renderShunRow(out, row, shunListRow(log, i));
}
fn renderShunRow(out: *std.Io.Writer, row: logstore.ShunRecord, signed: ?ShunListRow) void {
var hex: [2 * digest_len]u8 = undefined;
var ts: [19]u8 = undefined;
const date = cli.formatWriterTimestamp(row.epoch, &ts)[0..10];
out.print("{s} {s}", .{ digestToWireName(row.hash, &hex), date }) catch {};
var reason = row.reason;
if (signed) |lr| if (!std.mem.eql(u8, lr.kind, "plain")) {
out.print(" {s} {s}", .{ lr.kind, lr.state }) catch {};
if (lr.not_before) |nb| {
var nb_ts: [19]u8 = undefined;
out.print(" not-before {s}", .{cli.formatWriterTimestamp(nb, &nb_ts)}) catch {};
}
out.print(" signer {s}", .{lr.signer}) catch {};
reason = switch (erasure.classify(row.reason)) {
.signed => |stmt| stmt.reason,
else => "",
};
};
if (reason.len != 0) out.print(" {s}", .{reason}) catch {};
out.writeAll("\n") catch {};
}
/// `--list -F json`: one array, a row per element, in persisted order.
fn renderShunListJson(out: *std.Io.Writer, log: *const logstore.LogStore) std.Io.Writer.Error!void {
var jw: std.json.Stringify = .{ .writer = out };
try jw.beginArray();
for (log.shunList(), 0..) |row, i| {
var hex: [2 * digest_len]u8 = undefined;
const lr = shunListRow(log, i);
try jw.beginObject();
try jw.objectField("hash");
try jw.write(digestToWireName(row.hash, &hex));
try jw.objectField("epoch");
try jw.write(row.epoch);
try jw.objectField("kind");
try jw.write(lr.kind);
try jw.objectField("state");
try jw.write(lr.state);
try jw.objectField("not_before");
try jw.write(lr.not_before);
try jw.objectField("signer");
try jw.write(lr.signer);
try jw.objectField("reason");
try jw.write(switch (erasure.classify(row.reason)) {
.signed => |stmt| stmt.reason,
.plain => row.reason,
.malformed => "",
});
try jw.endObject();
}
try jw.endArray();
try out.writeByte('\n');
}
/// The repository a `shun key` or `shun cancel` acts on: the store directory.
fn shunStoreDir(arena: std.mem.Allocator, io: std.Io, streams: cli.Streams, amb: cli.Ambient) ?std.Io.Dir {
const root = (cli.resolveRoot(arena, io, amb.repo_override) catch {
_ = stateOom(streams, "shun");
return null;
}) orelse {
diagnostics.reportNoRoot(streams, io, "shun", amb.repo_override);
return null;
};
var dir = root.dir;
if (cli.storeDirOf(io, dir) catch {
dir.close(io);
_ = repoReadFail(streams, "shun");
return null;
}) |resolved| {
dir.close(io);
dir = resolved;
}
return dir;
}
fn erasureAppendFail(streams: cli.Streams, e: anyerror) cli.Exit {
return switch (e) {
error.OutOfMemory => stateOom(streams, "shun"),
error.RewriteBusy => rewriteBusyFail(streams, "shun"),
error.StoreBusy => .failure, // the lock notice already said it
else => shunFail(streams, e),
};
}
/// `zit shun key generate [--print | -F json]`, `zit shun key show`,
/// `zit shun key pin PUBKEY` — the repository's one owner key.
fn runShunKey(
gpa: std.mem.Allocator,
io: std.Io,
arena: std.mem.Allocator,
parsed: cli.ShunArgs,
streams: cli.Streams,
amb: cli.Ambient,
) cli.Exit {
const args = parsed.hashes[1..];
if (args.len == 0) {
streams.err.writeAll("zit shun key: name one of generate, show, pin\n") catch {};
return .usage;
}
const sub = args[0];
const is_generate = std.mem.eql(u8, sub, "generate");
const is_show = std.mem.eql(u8, sub, "show");
const is_pin = std.mem.eql(u8, sub, "pin");
if (!is_generate and !is_show and !is_pin) return cli.usageError(streams, "shun", .extra_argument, sub);
const want_args: usize = if (is_pin) 2 else 1;
if (args.len != want_args) {
if (args.len > want_args) return cli.usageError(streams, "shun", .extra_argument, args[want_args]);
streams.err.writeAll("zit shun key pin: name the public key, 64 hex\n") catch {};
return .usage;
}
if ((parsed.print or parsed.json) and !is_generate) {
streams.err.writeAll("zit shun key: --print and -F json apply to 'key generate'\n") catch {};
return .usage;
}
// `--print` touches no repository and writes no file: the keypair goes to
// stdout for a caller that keeps the private half in a keychain and pins
// the public half with `key pin`.
if (is_generate and (parsed.print or parsed.json)) {
var seed: erasure.Seed = undefined;
io.random(&seed);
defer std.crypto.secureZero(u8, &seed);
const public = erasure.publicKeyOf(seed) catch return shunFail(streams, error.Corrupt);
const pub_hex = erasure.keyHex(public);
var priv_hex = erasure.keyHex(seed);
defer std.crypto.secureZero(u8, &priv_hex);
if (parsed.json) {
streams.out.print("{{\"public\":\"{s}\",\"private\":\"{s}\"}}\n", .{ &pub_hex, &priv_hex }) catch {};
} else streams.out.print("public {s}\nprivate {s}\n", .{ &pub_hex, &priv_hex }) catch {};
return .ok;
}
var dir = shunStoreDir(arena, io, streams, amb) orelse return .failure;
defer dir.close(io);
if (is_show) {
var src_file = cli.openStoreRead(io, dir) catch |e| return storeReadFail(streams, "shun", e);
defer src_file.close(io);
const st = src_file.stat(io) catch return repoReadFail(streams, "shun");
var fs = storage.FileStorage.init(io, src_file, st.size);
var log = logstore.LogStore.openReadOnly(gpa, fs.storageFile()) catch |e| return shunFail(streams, e);
defer log.deinit(gpa);
const key = log.erasureKey() orelse {
streams.err.writeAll("zit shun key: no erasure key is pinned in this repository\n") catch {};
return .failure;
};
streams.out.print("{s}\n", .{&erasure.keyHex(key)}) catch {};
return .ok;
}
var pin_key: erasure.PublicKey = undefined;
if (is_pin) {
pin_key = erasure.pinnedKey(args[1]) orelse {
streams.err.print("zit shun key pin: '{s}' is not a 64-hex Ed25519 public key\n", .{args[1]}) catch {};
return .failure;
};
}
var ap: ErasureAppend = undefined;
openErasureAppend(gpa, io, dir, &ap) catch |e| return erasureAppendFail(streams, e);
defer ap.close(gpa, io);
if (is_generate) {
// Generating over a pinned key would strand every device that holds
// the old one; replacing a key is the operator's `key pin`.
if (ap.log.erasureKey() != null) {
streams.err.writeAll("zit shun key generate: this repository already pins an erasure key; 'zit shun key pin PUBKEY' replaces it\n") catch {};
return .failure;
}
var code_buf: [logstore.max_config_str]u8 = undefined;
const code = logProjectCode(gpa, &ap.log, &code_buf) catch return repoReadFail(streams, "shun");
var seed: erasure.Seed = undefined;
io.random(&seed);
defer std.crypto.secureZero(u8, &seed);
pin_key = erasure.publicKeyOf(seed) catch return shunFail(streams, error.Corrupt);
var path_buf: [std.fs.max_path_bytes]u8 = undefined;
const path = erasure.writeKeyFile(io, amb.environ, code, seed, &path_buf) catch |e| {
switch (e) {
error.NoHome => streams.err.writeAll("zit shun key generate: no XDG_CONFIG_HOME or HOME to hold the private key; use --print\n") catch {},
error.Exists => streams.err.writeAll("zit shun key generate: a private key file for this repository already exists\n") catch {},
error.BadProjectCode => streams.err.writeAll("zit shun key generate: this repository has no usable project code\n") catch {},
else => streams.err.writeAll("zit shun key generate: the private key file cannot be written\n") catch {},
}
return .failure;
};
writeErasureKey(&ap.log, pin_key, amb.now_epoch) catch |e| return erasureAppendFail(streams, e);
streams.out.print("erasure key pinned: {s}\nprivate key written to {s}\n", .{ &erasure.keyHex(pin_key), path }) catch {};
return .ok;
}
writeErasureKey(&ap.log, pin_key, amb.now_epoch) catch |e| return erasureAppendFail(streams, e);
streams.out.print("erasure key pinned: {s}\n", .{&erasure.keyHex(pin_key)}) catch {};
return .ok;
}
fn writeErasureKey(log: *logstore.LogStore, key: erasure.PublicKey, now: i64) !void {
const hex = erasure.keyHex(key);
try log.putSetting(.{ .name = erasure.setting_name, .value = &hex, .mtime = now });
try log.commit();
}
/// `zit shun cancel HASH` — sign a cancel for a pending erasure, inside its
/// window. Outside it the erasure has taken effect and nothing can undo it,
/// as nothing undoes a shun.
fn runShunCancel(
gpa: std.mem.Allocator,
io: std.Io,
arena: std.mem.Allocator,
parsed: cli.ShunArgs,
streams: cli.Streams,
amb: cli.Ambient,
) cli.Exit {
const args = parsed.hashes[1..];
if (args.len != 1) {
if (args.len > 1) return cli.usageError(streams, "shun", .extra_argument, args[1]);
return cli.usageError(streams, "shun", .no_hash, "");
}
var dir = shunStoreDir(arena, io, streams, amb) orelse return .failure;
defer dir.close(io);
var ap: ErasureAppend = undefined;
openErasureAppend(gpa, io, dir, &ap) catch |e| return erasureAppendFail(streams, e);
defer ap.close(gpa, io);
var canon_buf: [2 * logstore.max_hash_len]u8 = undefined;
const canon = canonicalizeShunHex(args[0], &canon_buf) orelse {
streams.err.print("zit shun cancel: '{s}' is not an artifact name\n", .{args[0]}) catch {};
return .failure;
};
// The name is the table's, not the store's: a pending erasure of a hash
// this repository never held is as cancellable as one it holds.
var digest: ?[]const u8 = null;
for (ap.log.shunList()) |row| {
var hex: [2 * logstore.max_hash_len]u8 = undefined;
if (!std.mem.startsWith(u8, digestToWireName(row.hash, &hex), canon)) continue;
if (digest) |d| if (!std.mem.eql(u8, d, row.hash)) {
streams.err.print("zit shun cancel: hash '{s}' is ambiguous\n", .{args[0]}) catch {};
return .failure;
};
digest = row.hash;
}
const target = arena.dupe(u8, digest orelse {
streams.err.print("zit shun cancel: {s} has no erasure to cancel\n", .{args[0]}) catch {};
return .failure;
}) catch return stateOom(streams, "shun");
var hex_buf: [2 * logstore.max_hash_len]u8 = undefined;
const name = digestToWireName(target, &hex_buf);
const status = ap.log.shunStatus(target);
var ts: [19]u8 = undefined;
switch (status.state) {
.pending => {},
.erased => {
streams.err.print("zit shun cancel: the erasure of {s} took effect at {s} UTC and cannot be cancelled\n", .{ name, cli.formatWriterTimestamp(status.not_before, &ts) }) catch {};
return .failure;
},
else => {
streams.err.print("zit shun cancel: {s} has no pending erasure to cancel\n", .{name}) catch {};
return .failure;
},
}
var code_buf: [logstore.max_config_str]u8 = undefined;
const signer = loadErasureSigner(gpa, io, &ap.log, amb, &code_buf, streams) orelse return .failure;
// A cancel is newer than the erasure it cancels and older than its
// not-before; a clock that disagrees is nudged into the window, and an
// erasure with no window left cannot be cancelled at all.
var newest_erase: i64 = std.math.minInt(i64);
for (ap.log.shunList(), 0..) |row, i| {
if (std.mem.eql(u8, row.hash, target) and ap.log.shunRowState(i).kind == .erase) newest_erase = @max(newest_erase, row.epoch);
}
const epoch = @max(amb.now_epoch, newest_erase + 1);
if (epoch >= status.not_before) {
streams.err.print("zit shun cancel: the erasure of {s} takes effect at {s} UTC; it is too late to cancel\n", .{ name, cli.formatWriterTimestamp(status.not_before, &ts) }) catch {};
return .failure;
}
const scom = signer.sign(arena, target, epoch, epoch, .cancel, "") catch return shunRowBug(streams);
ap.log.putShun(target, scom, epoch) catch |e| return erasureAppendFail(streams, e);
ap.log.commit() catch |e| return erasureAppendFail(streams, e);
streams.out.print("cancelled: the erasure of {s}\n", .{name}) catch {};
return .ok;
}
/// Resolve one operator token against `src` into a `ShunTarget`. Impure only in
/// that it reads the store: no policy, no output, no durable write, so the
/// runner's whole decision is a fold over the results.
///
/// RESOLUTION RULE. Every token is offered to prefix resolution FIRST, at every
/// width in `canonicalizeShunHex`'s band — the same band and the same resolver
/// `zit artifact` uses (cmd/artifact.zig), which is what makes "paste the same
/// token into both verbs" true rather than merely intended. Only when nothing
/// matches does a COMPLETE name (40 or 64 hex — artifact-format §3.2's two forms)
/// fall back to being used literally, because a hash this repository does not hold
/// is precisely the pre-emptive case worth recording; an ABBREVIATED prefix that
/// matches nothing is refused, since the shun table is keyed by complete name
/// (sync §3.3 L544-545), a prefix cannot be completed, and a row keyed on one would
/// read as a removal while naming nothing.
///
/// TRYING RESOLUTION FIRST IS THE LOAD-BEARING PART, not an optimisation. Treating
/// a complete-WIDTH token as a complete NAME without asking the store means a
/// 40-hex abbreviation of a 64-hex artifact (and a 64-hex abbreviation in a sha1
/// repository) records a tombstone naming nothing, reports success, and leaves the
/// content the operator was ordered to remove still readable — the `unresolved`
/// refusal exists to stop exactly that, and a width-first rule walks past it.
/// It also un-hides the current-checkout guard, which cannot fire on a token that
/// never resolved to the check-in's name.
fn classifyShunTarget(
gpa: std.mem.Allocator,
arena: std.mem.Allocator,
src: *logstore.LogStore,
ck_version: []const u8,
tok: []const u8,
) (logstore.ContentError || error{OutOfMemory})!ShunTarget {
var canon_buf: [2 * logstore.max_hash_len]u8 = undefined;
const canon = canonicalizeShunHex(tok, &canon_buf) orelse
return .{ .name = tok, .disposition = .not_a_name };
var raw_buf: [logstore.max_hash_len]u8 = undefined;
var digest: []const u8 = undefined;
if (src.resolveHexPrefix(canon) catch |e| switch (e) {
error.Ambiguous => return .{ .name = tok, .disposition = .ambiguous },
}) |rid| {
digest = src.hashOf(rid);
} else if (shunHexToDigest(canon, &raw_buf)) |d| {
digest = d;
} else {
return .{ .name = tok, .disposition = .unresolved };
}
std.debug.assert(logstore.isCompleteDigest(digest.len));
const owned_digest = try arena.dupe(u8, digest);
var hex_buf: [2 * digest_len]u8 = undefined;
const name = try arena.dupe(u8, digestToWireName(owned_digest, &hex_buf));
// THE CURRENT-CHECKOUT STOP IS CHECKED FIRST, ahead of the shun table. An
// already-tombstoned check-in whose bytes survive is otherwise `.reclaim`, and
// reclaiming it would delete the check-in the operator is standing on — the one
// thing this verb refuses outright. `--defer` goes through this same guard, so
// the state cannot arise through zit today; the ordering is what keeps that
// true if it ever does.
if (std.mem.eql(u8, name, ck_version)) return .{
.name = name,
.digest = owned_digest,
.disposition = .current_checkout,
};
const already = src.isShunned(owned_digest);
const rid = src.lookup(owned_digest) orelse return .{
.name = name,
.digest = owned_digest,
.disposition = if (already) .already else .absent,
};
// THROUGH THE MAINTENANCE READER, deliberately. `content` applies the shun
// mask, so an already-shunned artifact whose bytes are still on disk would read
// as absent and be reported as nothing left to do — which is the whole defect
// `.reclaim` exists to prevent. Shunning is maintenance, not an artifact read.
//
// A phantom is an announced name with no frame: there are no bytes to reclaim,
// so it is the `absent` case with a rid attached.
const content = (try src.contentUnmasked(gpa, rid, null)) orelse return .{
.name = name,
.digest = owned_digest,
.disposition = if (already) .already else .absent,
};
defer gpa.free(content);
// The type verdict, through the same door `zit artifact` uses: a structural
// artifact classifies (`parseWindow` runs §5's `classify` internally), and
// anything that does not parse is an opaque blob — a first-class answer, not
// an error. A blob is by far the common shun target.
const held: ShunDisposition = if (already) .reclaim else .remove;
var m = artifact.parseWindow(gpa, content) catch |e| switch (e) {
error.OutOfMemory => return error.OutOfMemory,
else => return .{ .name = name, .digest = owned_digest, .kind = null, .disposition = held },
};
defer m.deinit();
return .{ .name = name, .digest = owned_digest, .kind = m.kind, .disposition = held };
}
// --- `zit shun`'s pure renderers -------------------------------------------
//
// Every operator-visible byte this verb emits is produced by a function of data
// alone, for the same reason `renderPackStats` is: the exact wording of a
// refusal that precedes irreversible deletion is the part most worth pinning,
// and pinning it through a subprocess would make the e2e tests the only place
// it is stated.
const shun_name_a = "1c04b7" ++ repeat("0", 58);
const shun_name_b = "7bd1e0" ++ repeat("1", 58);
const shun_name_c = "9f2a1c" ++ repeat("2", 58);
test "renderShunRefusal: the counts and the word refusing share the first line, then one line per hash" {
// The register is `clean`'s (`cleanRefuse`): an operator must not have to read
// six lines of inventory to discover that nothing happened.
var buf: [1024]u8 = undefined;
var w: std.Io.Writer = .fixed(&buf);
renderShunRefusal(&w, &.{
.{ .name = shun_name_a, .kind = .manifest, .disposition = .remove },
.{ .name = shun_name_b, .kind = null, .disposition = .remove },
.{ .name = shun_name_c, .disposition = .absent },
}, 0, false);
try std.testing.expectEqualStrings(
"zit shun: 3 hashes would be shunned in this repository; 2 artifacts would be permanently removed; refusing without --force:\n" ++
"\n" ++
" " ++ shun_name_a ++ " checkin a check-in; its descendants become unresolvable\n" ++
" " ++ shun_name_b ++ " file file content; every check-in listing it loses that file\n" ++
" " ++ shun_name_c ++ " recorded only (not present in this repository)\n" ++
"\n" ++
"This is irreversible: zit undo does not recover a shun, and the content\n" ++
"cannot be re-fetched from a peer.\n" ++
"run 'zit shun --force <HASH>...' to proceed\n",
w.buffered(),
);
}
test "renderShunRefusal: singular agreement, an already-shunned line, and the nothing-held wording" {
var buf: [1024]u8 = undefined;
{
// One target, held here: "1 hash", "1 artifact".
var w: std.Io.Writer = .fixed(&buf);
renderShunRefusal(&w, &.{
.{ .name = shun_name_a, .kind = .wiki, .disposition = .remove },
.{ .name = shun_name_b, .disposition = .already },
}, 0, false);
try std.testing.expectEqualStrings(
"zit shun: 1 hash would be shunned in this repository; 1 artifact would be permanently removed; refusing without --force:\n" ++
"\n" ++
" " ++ shun_name_a ++ " wiki structural content; what it renders stops rendering\n" ++
" " ++ shun_name_b ++ " already shunned; content already gone\n" ++
"\n" ++
"This is irreversible: zit undo does not recover a shun, and the content\n" ++
"cannot be re-fetched from a peer.\n" ++
"run 'zit shun --force <HASH>...' to proceed\n",
w.buffered(),
);
}
{
// A purely pre-emptive run: the tombstones are still irreversible, so the
// refusal stands, but nothing would be removed and the line says so
// instead of claiming a removal that is not going to happen.
var w: std.Io.Writer = .fixed(&buf);
renderShunRefusal(&w, &.{.{ .name = shun_name_c, .disposition = .absent }}, 0, false);
try std.testing.expectEqualStrings(
"zit shun: 1 hash would be shunned in this repository; nothing you named holds content to remove; refusing without --force:\n" ++
"\n" ++
" " ++ shun_name_c ++ " recorded only (not present in this repository)\n" ++
"\n" ++
"This is irreversible: zit undo does not recover a shun, and the content\n" ++
"cannot be re-fetched from a peer.\n" ++
"run 'zit shun --force <HASH>...' to proceed\n",
w.buffered(),
);
}
}
test "renderShunRefusal: a reclaim-only run, and the collateral an earlier --defer left behind" {
// THE CONSENT GATE MUST NAME EVERYTHING THE REWRITE DESTROYS, including what the
// operator did not name. `renderShunStats` is honest after the fact that
// `dropped` can exceed `recorded`; a refusal that only counted this
// invocation's own targets would have the operator consent to one deletion and
// get several.
var buf: [1024]u8 = undefined;
var w: std.Io.Writer = .fixed(&buf);
renderShunRefusal(&w, &.{
.{ .name = shun_name_a, .kind = null, .disposition = .reclaim },
}, 2, false);
try std.testing.expectEqualStrings(
"zit shun: no new hash would be recorded; 1 artifact would be permanently removed; " ++
"the same rewrite also removes 2 artifacts shunned earlier and not yet reclaimed; " ++
"refusing without --force:\n" ++
"\n" ++
" " ++ shun_name_a ++ " file already shunned; content still here and would be removed\n" ++
"\n" ++
"This is irreversible: zit undo does not recover a shun, and the content\n" ++
"cannot be re-fetched from a peer.\n" ++
"run 'zit shun --force <HASH>...' to proceed\n",
w.buffered(),
);
}
test "renderShunRefusal: a --defer run is described as a --defer run, and suggests --defer --force" {
// THE CONSENT GATE MUST DESCRIBE THE OPERATION THE OPERATOR ASKED FOR. A
// `--defer` run removes nothing now, so it must not say "would be permanently
// removed"; it must not attribute rewrite collateral to a run that performs no
// rewrite; and — the reason this is pinned byte for byte — the command it
// suggests must be the deferred one. An operator who copies `zit shun --force`
// out of a `--defer` refusal escalates a tombstone into a full-store reclaim of
// the whole union set, including collateral this run never named.
var buf: [1024]u8 = undefined;
{
// `deferred_held` is 2 here and the clause must NOT appear: nothing on this
// path reclaims those rows.
var w: std.Io.Writer = .fixed(&buf);
renderShunRefusal(&w, &.{
.{ .name = shun_name_a, .kind = .manifest, .disposition = .remove },
.{ .name = shun_name_b, .kind = null, .disposition = .remove },
.{ .name = shun_name_c, .disposition = .absent },
}, 2, true);
try std.testing.expectEqualStrings(
"zit shun: 3 hashes would be shunned in this repository; " ++
"the bytes of 2 artifacts stay on disk and stay reconstructible until 'zit pack'; " ++
"refusing without --force:\n" ++
"\n" ++
" " ++ shun_name_a ++ " checkin a check-in; its descendants become unresolvable\n" ++
" " ++ shun_name_b ++ " file file content; every check-in listing it loses that file\n" ++
" " ++ shun_name_c ++ " recorded only (not present in this repository)\n" ++
"\n" ++
"This is irreversible: zit undo does not recover a shun, and the content\n" ++
"cannot be re-fetched from a peer.\n" ++
"run 'zit shun --defer --force <HASH>...' to proceed\n",
w.buffered(),
);
}
{
// Singular agreement on the deferred clause, and the `.reclaim` line: under
// `--defer` the content stays rather than being removed.
var w: std.Io.Writer = .fixed(&buf);
renderShunRefusal(&w, &.{
.{ .name = shun_name_a, .kind = .wiki, .disposition = .reclaim },
}, 0, true);
try std.testing.expectEqualStrings(
"zit shun: no new hash would be recorded; " ++
"the bytes of 1 artifact stay on disk and stay reconstructible until 'zit pack'; " ++
"refusing without --force:\n" ++
"\n" ++
" " ++ shun_name_a ++ " wiki already shunned; content still here and stays\n" ++
"\n" ++
"This is irreversible: zit undo does not recover a shun, and the content\n" ++
"cannot be re-fetched from a peer.\n" ++
"run 'zit shun --defer --force <HASH>...' to proceed\n",
w.buffered(),
);
// The escalating suggestion must be ABSENT, not merely reworded: this is the
// one substring an operator is most likely to paste.
try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "run 'zit shun --force") == null);
}
{
// Nothing named holds content: the wording is the same on both paths, and
// only the suggested command differs.
var w: std.Io.Writer = .fixed(&buf);
renderShunRefusal(&w, &.{.{ .name = shun_name_c, .disposition = .absent }}, 0, true);
try std.testing.expectEqualStrings(
"zit shun: 1 hash would be shunned in this repository; " ++
"nothing you named holds content to remove; refusing without --force:\n" ++
"\n" ++
" " ++ shun_name_c ++ " recorded only (not present in this repository)\n" ++
"\n" ++
"This is irreversible: zit undo does not recover a shun, and the content\n" ++
"cannot be re-fetched from a peer.\n" ++
"run 'zit shun --defer --force <HASH>...' to proceed\n",
w.buffered(),
);
}
}
test "shunConsequence/shunTypeLabel: one arm per consequence, total over ArtifactType" {
// The per-type diagnostic, pinned type by type. The switch is total, so this
// test and the compiler together guarantee a type added later cannot ship
// with no warning attached to its removal.
try std.testing.expectEqualStrings("file", shunTypeLabel(null));
try std.testing.expectEqualStrings(
"file content; every check-in listing it loses that file",
shunConsequence(null),
);
try std.testing.expectEqualStrings("checkin", shunTypeLabel(.manifest));
try std.testing.expectEqualStrings(
"a check-in; its descendants become unresolvable",
shunConsequence(.manifest),
);
try std.testing.expectEqualStrings("cluster", shunTypeLabel(.cluster));
try std.testing.expectEqualStrings("sync housekeeping only; regenerable", shunConsequence(.cluster));
// The six that all stop rendering share one arm; their LABELS still differ,
// so the operator can tell a ticket from a forum post.
const rendering = "structural content; what it renders stops rendering";
inline for (.{ .control, .wiki, .ticket, .attachment, .event, .forum }) |k| {
try std.testing.expectEqualStrings(rendering, shunConsequence(k));
}
try std.testing.expectEqualStrings("tag", shunTypeLabel(.control));
try std.testing.expectEqualStrings("technote", shunTypeLabel(.event));
try std.testing.expectEqualStrings("forumpost", shunTypeLabel(.forum));
}
test "renderShunBlockers: the unconditional stops, one line each, with no --force offered" {
// The current-checkout stop is the only refusal in this verb with no
// override, so its text must NOT mention --force — an operator who reads a
// flag out of it will try the flag and be refused twice.
var buf: [1024]u8 = undefined;
var w: std.Io.Writer = .fixed(&buf);
renderShunBlockers(&w, &.{
.{ .name = shun_name_a, .kind = .manifest, .disposition = .current_checkout },
.{ .name = "nothex", .disposition = .not_a_name },
.{ .name = "1c04", .disposition = .unresolved },
.{ .name = "7bd1", .disposition = .ambiguous },
// A permissive target contributes nothing to this block.
.{ .name = shun_name_c, .disposition = .remove },
});
try std.testing.expectEqualStrings(
"zit shun: " ++ shun_name_a ++ " is the check-in this checkout is on; refusing\n" ++
"run 'zit update' to a different check-in first\n" ++
"zit shun: 'nothex' is not an artifact name\n" ++
"zit shun: no artifact matches '1c04'; give the complete name to shun a hash this repository does not hold\n" ++
"zit shun: hash '7bd1' is ambiguous\n",
w.buffered(),
);
try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "--force") == null);
}
test "renderShunStats/renderShunDeferred: the two success lines" {
var buf: [256]u8 = undefined;
{
var w: std.Io.Writer = .fixed(&buf);
renderShunStats(&w, .{
.artifacts = 12,
.deltas = 4,
.dropped = 3,
.shuns_recorded = 3,
.bytes_before = 481232,
.bytes_after = 402118,
});
try std.testing.expectEqualStrings(
"shunned: 3 hashes recorded, 3 artifacts removed, 12 -> 9 remaining, 481232 -> 402118 bytes\n",
w.buffered(),
);
}
{
// `dropped` legitimately EXCEEDS `recorded`: the same rewrite reclaims
// shuns deferred by earlier runs, and an operator must be told that
// rather than left to infer it from the byte count.
var w: std.Io.Writer = .fixed(&buf);
renderShunStats(&w, .{
.artifacts = 12,
.deltas = 4,
.dropped = 4,
.shuns_recorded = 1,
.bytes_before = 8192,
.bytes_after = 4096,
});
try std.testing.expectEqualStrings(
"shunned: 1 hash recorded, 4 artifacts removed, 12 -> 8 remaining, 8192 -> 4096 bytes\n",
w.buffered(),
);
}
{
// THE RECORDED COUNT IS THE PACK'S, NOT THE CALLER'S. `shuns_recorded` is
// measured off the new generation's own shun table, so this line cannot
// over-report a takedown even if a caller's intent and the pack's result ever
// diverged. Two tombstones, and this rewrite reclaimed nothing.
var w: std.Io.Writer = .fixed(&buf);
renderShunStats(&w, .{
.artifacts = 12,
.deltas = 4,
.dropped = 0,
.shuns_recorded = 2,
.bytes_before = 8192,
.bytes_after = 8320,
});
try std.testing.expectEqualStrings(
"shunned: 2 hashes recorded, 0 artifacts removed, 12 -> 12 remaining, 8192 -> 8320 bytes\n",
w.buffered(),
);
}
{
// --defer promises no byte count: nothing on that path measured one.
var w: std.Io.Writer = .fixed(&buf);
renderShunDeferred(&w, 2, 2, null);
try std.testing.expectEqualStrings(
"shunned: 2 hashes recorded; run 'zit pack' to reclaim the space\n",
w.buffered(),
);
}
{
var w: std.Io.Writer = .fixed(&buf);
renderShunDeferred(&w, 1, 1, null);
try std.testing.expectEqualStrings(
"shunned: 1 hash recorded; run 'zit pack' to reclaim the space\n",
w.buffered(),
);
}
{
// On a bare store the hint names the store the run was given.
var w: std.Io.Writer = .fixed(&buf);
renderShunDeferred(&w, 1, 1, "forge/s.zit");
try std.testing.expectEqualStrings(
"shunned: 1 hash recorded; run 'zit pack -R forge/s.zit' to reclaim the space\n",
w.buffered(),
);
}
{
// Re-deferring a hash already deferred: no row to add, and yet content still
// to lose. "0 hashes recorded" would read as a no-op over live bytes.
var w: std.Io.Writer = .fixed(&buf);
renderShunDeferred(&w, 0, 1, null);
try std.testing.expectEqualStrings(
"shunned: no new hash to record; 1 artifact still holds content; run 'zit pack' to reclaim the space\n",
w.buffered(),
);
}
{
// The purely pre-emptive success line: no rewrite ran, so it claims no byte
// count AND does not claim a removal.
var w: std.Io.Writer = .fixed(&buf);
renderShunRecordedOnly(&w, 1);
try std.testing.expectEqualStrings(
"shunned: 1 hash recorded; none is held here, so nothing was removed\n",
w.buffered(),
);
}
}
test "renderShunList: persisted order, the recorded date, and the reason only when given" {
var buf: [512]u8 = undefined;
{
var w: std.Io.Writer = .fixed(&buf);
renderShunList(&w, &.{});
try std.testing.expectEqualStrings("the shun table is empty\n", w.buffered());
}
{
// 1753660800 = 2025-07-28T00:00:00Z; 1752192000 = 2025-07-11T00:00:00Z.
// A row with no reason prints no trailing separator at all.
var w: std.Io.Writer = .fixed(&buf);
renderShunList(&w, &.{
.{ .hash = "\x9f\x2a\x1c" ++ repeat("\x00", 29), .epoch = 1753660800, .reason = "legal takedown ref #4417" },
.{ .hash = "\x1c\x04\xb7" ++ repeat("\x00", 17), .epoch = 1753660800, .reason = "" },
.{ .hash = "\x7b\xd1\xe0" ++ repeat("\x00", 29), .epoch = 1752192000, .reason = "committed credential" },
});
try std.testing.expectEqualStrings(
"9f2a1c" ++ repeat("00", 29) ++ " 2025-07-28 legal takedown ref #4417\n" ++
"1c04b7" ++ repeat("00", 17) ++ " 2025-07-28\n" ++
"7bd1e0" ++ repeat("00", 29) ++ " 2025-07-11 committed credential\n",
w.buffered(),
);
}
}
/// How many rows the store in `dir` holds in its shun table.
fn shunRowsIn(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) !usize {
var fs: storage.FileStorage = undefined;
var log = try packOpenReadOnly(gpa, io, dir, &fs);
defer fs.file.close(io);
defer log.deinit(gpa);
return log.shunList().len;
}
test "shunAppendRows: the append aborts on a changed tail and on a held temp lock, recording nothing" {
// THE APPEND PATH'S TWO CONCURRENCY GUARDS, driven directly because neither is
// reachable from the CLI in one process: both windows open between the moment
// `runShun` classified its targets and the moment this function commits.
//
// The TAIL guard is what makes the append path's success lines honest. They are
// claims about STORE STATE — "none is held here, so nothing was removed" — and a
// `zit commit` landing a named hash in that window falsifies them: the tombstone
// would be recorded, exit 0, and an operator under a takedown order told nothing
// was held while the bytes were live and unreclaimed.
//
// The LOCK guard is what stops the row being written to an ORPHANED INODE. A
// `zit pack` renaming its new generation over `.zit` after our `openFile` takes
// the append with it, and the run would still report success — a deferred shun
// that silently does not exist, having just told the operator to run `zit pack`
// to finish it.
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var tip: [64]u8 = undefined;
{
var wfs: storage.FileStorage = undefined;
var wlog = try packOpenWritable(gpa, io, tmp.dir, &wfs);
defer wfs.file.close(io);
defer wlog.deinit(gpa);
try packSeedFullStore(gpa, &wlog, &tip);
}
const digest_a = @as([digest_len]u8, @splat(0xab));
const digest_b = @as([digest_len]u8, @splat(0xcd));
const rows_a = [_]logstore.ShunRecord{.{ .hash = &digest_a, .epoch = 1_753_660_800, .reason = "" }};
const rows_b = [_]logstore.ShunRecord{.{ .hash = &digest_b, .epoch = 1_753_660_800, .reason = "" }};
// The key the runner would have captured off its read-only snapshot.
var key_1: logstore.LogStore.LogKey = undefined;
{
var sfs: storage.FileStorage = undefined;
var src = try packOpenReadOnly(gpa, io, tmp.dir, &sfs);
defer sfs.file.close(io);
defer src.deinit(gpa);
key_1 = try src.logKey();
}
// Control: with a current key the append lands, so the guards below are failing
// for the reason under test rather than because this path never works.
try shunAppendRows(gpa, io, tmp.dir, key_1, &rows_a);
try std.testing.expectEqual(@as(usize, 1), try shunRowsIn(gpa, io, tmp.dir));
// No temp left behind: the lock file is removed on the success path too.
try std.testing.expectError(error.FileNotFound, tmp.dir.openFile(io, pack_tmp_filename, .{}));
// That append is itself the "concurrent writer": `key_1` is now stale.
const before = try tmp.dir.readFileAlloc(io, repo_filename, gpa, .limited(1 << 24));
defer gpa.free(before);
try std.testing.expectError(error.TailChanged, shunAppendRows(gpa, io, tmp.dir, key_1, &rows_b));
// NOTHING WRITTEN: the check precedes the first `putShun`.
try std.testing.expectEqual(@as(usize, 1), try shunRowsIn(gpa, io, tmp.dir));
{
const after = try tmp.dir.readFileAlloc(io, repo_filename, gpa, .limited(1 << 24));
defer gpa.free(after);
try std.testing.expectEqualSlices(u8, before, after);
}
var key_2: logstore.LogStore.LogKey = undefined;
{
var sfs: storage.FileStorage = undefined;
var src = try packOpenReadOnly(gpa, io, tmp.dir, &sfs);
defer sfs.file.close(io);
defer src.deinit(gpa);
key_2 = try src.logKey();
}
{
// Stand in for the concurrent rewrite with a rewrite lock naming a live
// process that is not this one (this test's parent), which makes this
// deterministic rather than a race.
var host_buf: [std.posix.HOST_NAME_MAX]u8 = undefined;
const host = try std.posix.gethostname(&host_buf);
const parent: i64 = if (@import("builtin").os.tag == .linux) std.os.linux.getppid() else std.c.getppid();
var rec_buf: [256]u8 = undefined;
const rec = try std.fmt.bufPrint(&rec_buf, "pid={d} host={s} time=1\n", .{ parent, host });
try tmp.dir.writeFile(io, .{ .sub_path = rewrite_lock_name, .data = rec });
defer tmp.dir.deleteFile(io, rewrite_lock_name) catch {};
try std.testing.expectError(error.RewriteBusy, shunAppendRows(gpa, io, tmp.dir, key_2, &rows_b));
try std.testing.expectEqual(@as(usize, 1), try shunRowsIn(gpa, io, tmp.dir));
const after = try tmp.dir.readFileAlloc(io, repo_filename, gpa, .limited(1 << 24));
defer gpa.free(after);
try std.testing.expectEqualSlices(u8, before, after);
}
// Released and current: the same call now lands.
try shunAppendRows(gpa, io, tmp.dir, key_2, &rows_b);
try std.testing.expectEqual(@as(usize, 2), try shunRowsIn(gpa, io, tmp.dir));
}