//! Why a blob a store names is not in it: purged, shunned, erased, elided
//! by the store's cone or horizon, or missing, and the operator-facing
//! wording for each policy absence. Shared by every reading verb.
const std = @import("std");
const ClientHoldings = @import("sync_session.zig").ClientHoldings;
const Repository = @import("../repo/repository.zig").Repository;
const classifyKeepRids = @import("../repo/sparse.zig").classifyKeepRids;
const cone_mod = @import("../repo/cone.zig");
const decodeWireName = @import("digest_name.zig").decodeWireName;
const digest_len = @import("digest_name.zig").digest_len;
const logstore = @import("../store/logstore.zig");
const repocache = @import("../repo/repocache.zig");
const storage = @import("../store/storage.zig");
const store_open = @import("store_open.zig");
const thinned = @import("../store/thinned.zig");
/// Sparse-cone RFC section 5.2 / horizon draft section 4.2 -- is the blob
/// named `name` (wire hex) deliberately absent under this store's cone? Null
/// when the store has no cone (a dense store elides nothing), false when the
/// cone keeps the blob or nothing names it (so an absence is missing or in
/// transit, never deliberate), true when every reference to it is an F card
/// the cone does not keep. Opens its own read handle and classifies the whole
/// store once; a refusal path pays that, a hot path never calls this.
pub const Elision = struct {
elided: bool,
/// How the cone is described to the operator: its path members and, when
/// present, the horizon.
path_members: usize,
horizon: ?struct { hash: [64]u8, hash_len: u8, rule: cone_mod.HorizonRule },
pub fn horizonHash(self: *const Elision) ?[]const u8 {
// By pointer: a copy of the optional would be a local, and the slice
// would outlive it.
const h = if (self.horizon) |*h| h else return null;
return h.hash[0..h.hash_len];
}
};
pub fn blobElision(gpa: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, name: []const u8) ?Elision {
var cone = repocache.readStoreCone(gpa, io, root_dir) orelse return null;
defer cone.deinit(gpa);
var out: Elision = .{ .elided = false, .path_members = cone.members.len, .horizon = null };
if (cone.horizon) |h| {
var hh: [64]u8 = undefined;
@memcpy(hh[0..h.hash.len], h.hash);
out.horizon = .{ .hash = hh, .hash_len = @intCast(h.hash.len), .rule = h.rule };
}
var holdings = ClientHoldings.open(gpa, io, root_dir) catch return out;
defer holdings.deinit(io);
var classification = classifyKeepRids(gpa, holdings.index.classifyStore(), &cone) catch return out;
defer classification.deinit(gpa);
const rid = holdings.store().lookup(name) orelse return out;
out.elided = classification.elided(rid);
return out;
}
/// The operator-facing name of a store cone: "sparse cone of N member(s)",
/// "horizon at HASH (RULE)", or both. Bounded by the buffer; the horizon hash
/// is printed in full because it is what a re-clone or deepen names.
pub fn describeCone(e: *const Elision, buf: []u8) []const u8 {
if (e.horizonHash()) |hh| {
if (e.path_members != 0) {
return std.fmt.bufPrint(buf, "sparse cone of {d} member{s} and horizon at {s} ({s})", .{ e.path_members, if (e.path_members == 1) "" else "s", hh, e.horizon.?.rule.name() }) catch "sparse cone with a horizon";
}
return std.fmt.bufPrint(buf, "horizon at {s} ({s})", .{ hh, e.horizon.?.rule.name() }) catch "horizon";
}
return std.fmt.bufPrint(buf, "sparse cone of {d} member{s}", .{ e.path_members, if (e.path_members == 1) "" else "s" }) catch "sparse cone";
}
/// Why a blob this store names is not here. Every class but `missing` is a
/// choice someone made -- the operator thinned it, shunned it, or cloned with
/// a cone or horizon that leaves it out -- and readers answer those with exit
/// status 8 and the remedy. `missing` alone is damage, exit 1.
pub const Absence = union(enum) {
thinned,
shunned,
/// Shunned by a signed erasure that verifies against the pinned key.
erased,
elided: Elision,
missing,
pub fn byPolicy(self: Absence) bool {
return self != .missing;
}
};
/// Classify the absence of `name` (a complete lowercase-hex blob name) from
/// `repo`. `root_dir` is the directory the caller already asks about cone
/// elision (the checkout root or the store). Each question is cheap and only
/// asked on a read that already failed.
pub fn absenceOf(gpa: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, repo: *Repository, name: []const u8) Absence {
// Shunned first: a name both purged and shunned is named by the
// stronger absence, the one no `purge undo` reverses.
shun: {
var buf: [digest_len]u8 = undefined;
const digest = decodeWireName(name, &buf) orelse break :shun;
const log = repo.logStore(gpa) catch break :shun;
if (shunAbsence(log, digest)) |a| return a;
}
if (thinned.contains(gpa, io, repo.root_dir, name)) return .thinned;
if (blobElision(gpa, io, root_dir, name)) |e| if (e.elided) return .{ .elided = e };
return .missing;
}
/// `absenceOf` for a verb that holds no `Repository` (update): resolves the
/// store beside `root_dir` and reads its shun table with a read-only open,
/// which is paid only on a read that already failed.
pub fn absenceAt(gpa: std.mem.Allocator, io: std.Io, root_dir: std.Io.Dir, name: []const u8) Absence {
var store_dir = root_dir;
const resolved = store_open.storeDirOf(io, root_dir) catch null;
defer if (resolved) |d| d.close(io);
if (resolved) |d| store_dir = d;
shun: {
var buf: [digest_len]u8 = undefined;
const digest = decodeWireName(name, &buf) orelse break :shun;
var file = store_open.openStoreRead(io, store_dir) catch break :shun;
defer file.close(io);
const st = file.stat(io) catch break :shun;
var fs = storage.FileStorage.init(io, file, st.size);
var log = logstore.LogStore.openReadOnly(gpa, fs.storageFile()) catch break :shun;
defer log.deinit(gpa);
if (shunAbsence(&log, digest)) |a| return a;
}
if (thinned.contains(gpa, io, store_dir, name)) return .thinned;
if (blobElision(gpa, io, root_dir, name)) |e| if (e.elided) return .{ .elided = e };
return .missing;
}
fn shunAbsence(log: *const logstore.LogStore, digest: []const u8) ?Absence {
return switch (log.shunStatus(digest).state) {
.shunned => .shunned,
.erased => .erased,
.none, .inert, .pending => null,
};
}
/// The two-line explanation of a policy absence: which class, and the remedy.
/// `what` is how the verb names the content ("content for 'a.txt'"). Writes
/// nothing for `missing`, whose wording each verb keeps as its own.
pub fn describeAbsence(err: *std.Io.Writer, verb: []const u8, what: []const u8, a: *const Absence) void {
switch (a.*) {
.thinned => err.print(
"zit {s}: {s} was purged from this store ('zit purge artifacts')\n" ++
"zit {s}: restore it with 'zit purge undo ID' while 'zit purge list' still holds its event\n",
.{ verb, what, verb },
) catch {},
.shunned => err.print(
"zit {s}: {s} is shunned in this repository and is never fetched\n" ++
"zit {s}: 'zit shun --list' shows the table\n",
.{ verb, what, verb },
) catch {},
.erased => err.print(
"zit {s}: {s} was erased by the repository owner and is never fetched\n" ++
"zit {s}: 'zit shun --list' shows the signed erasure\n",
.{ verb, what, verb },
) catch {},
.elided => |*e| {
var dbuf: [160]u8 = undefined;
err.print("zit {s}: {s} is elided by this store's {s}\n", .{ verb, what, describeCone(e, &dbuf) }) catch {};
if (e.horizon != null) {
err.print("zit {s}: deepen with 'zit update <that check-in>' (fetches from the saved remote), or re-clone with an earlier --horizon\n", .{verb}) catch {};
} else {
err.print("zit {s}: widen the cone with 'zit update --cone PATH' to fetch it\n", .{verb}) catch {};
}
},
.missing => {},
}
}