//! The pull, push and sync runs: each drives a sync client to convergence
//! over a transport through the sync driver, and records what the run moved
//! for `ZIT_SYNC_STATS`.
const std = @import("std");
const HorizonUrl = zit.sync_session.HorizonUrl;
const PeerErrorCopy = zit.sync_session.PeerErrorCopy;
const PostClassify = zit.sync_session.PostClassify;
const PullOutcome = zit.sync_session.PullOutcome;
const RepoAdmission = zit.sync_session.RepoAdmission;
const RepoElidedSet = zit.sync_session.RepoElidedSet;
const RepoSyncIdentity = zit.sync_session.RepoSyncIdentity;
const ServerNotes = @import("sync_dialogue.zig").ServerNotes;
const classifyKeepRids = zit.sparse.classifyKeepRids;
const clusterindex = @import("zit").clusterindex;
const coneMode = zit.sync_session.coneMode;
const max_stalled_sync_rounds = zit.sync_session.max_stalled_sync_rounds;
const repostate = zit.repostate;
const syncClient = zit.sync_session.syncClient;
const sync_driver = @import("../net/sync_driver.zig");
const transport = @import("../net/transport.zig");
const zit = @import("zit");
/// Evidence seam: what the last sync run moved over the wire and
/// what its cluster index cost — bounded announcement is a claim about bytes
/// per round, and this is where it is measured. `ZIT_SYNC_STATS` at exit.
pub var sync_rounds: u64 = 0;
pub var sync_sent_bytes: u64 = 0;
pub var sync_received_bytes: u64 = 0;
fn recordSyncStats(stats: sync_driver.RunStats) void {
sync_rounds = stats.rounds;
sync_sent_bytes = stats.sent_bytes;
sync_received_bytes = stats.received_bytes;
}
/// Drives a pull client (§3.2/§3.3) to convergence over `tr`, filling `ms` with
/// the artifacts the peer holds and this side lacked; returns the round count.
/// The client announces `ms`'s holdings via igot and requests the rest via
/// gimme (receive-only — §3.3 r24: pull obtains content but never uploads).
/// Sans-IO on this side of `tr.exchange`. Its closed error set is the driver's
/// own causes unioned with the transport's, so `runPull` switches it exhaustively.
pub fn pullRun(
gpa: std.mem.Allocator,
tr: *transport.Transport,
holdings: repostate.ArtifactStore,
identity: RepoSyncIdentity,
credential: ?zit.sync.Credential,
admission: RepoAdmission,
sink: ?sync_driver.RoundSink,
clusters: ?*const clusterindex.Resolved,
truncated_out: *u64,
post: ?PostClassify,
/// Where a refusal's text is copied, as `pushRun` copies it.
peer_error_out: ?*PeerErrorCopy,
) sync_driver.RunError(*transport.Transport)!PullOutcome {
var client = syncClient(.pull, &identity, credential, admission);
defer client.deinit(gpa);
defer truncated_out.* = client.payloads_truncated;
errdefer if (peer_error_out) |p| p.set(client.peerErrorText());
if (clusters) |c| {
client.clustered = &c.clustered;
try client.seedClusterPhantoms(gpa, holdings, c.missing);
}
const stats = try sync_driver.runSyncProgress(gpa, &client, holdings, tr, max_stalled_sync_rounds, sink, null);
recordSyncStats(stats);
if (admission.erasure_latch) |l| try l.take(gpa, client.peerShunRows());
const seed = client.seed_bytes;
client.seed_bytes = null; // moved to the outcome
var out: PullOutcome = .{
.rounds = stats.rounds,
.unresolved = client.unresolvedPhantoms(holdings),
.cluster_gaps = client.clusterGaps(holdings),
// submanifests §7.3/§9.4 — the DEPENDENT-keyed half of the verdict: how
// many received check-ins still have a recorded S-reference gap.
.deferred_trees = client.deferredTrees(),
.cone_mode = coneMode(&client),
.uv_skipped = client.uv_skipped,
.seed = seed,
.peer_cursor = client.peer_cursor,
.horizon_served = client.horizon_served,
.horizon_url = .of(&client),
.mergebase_answered = client.mergebase_answered,
.mergebase_len = client.mergebase_answer_len,
};
@memcpy(out.mergebase_buf[0..client.mergebase_answer_len], client.mergebase_answer_buf[0..client.mergebase_answer_len]);
if (post) |p| {
if (p.out.*) |*old| old.deinit(gpa); // an earlier run's, superseded
p.out.* = null;
p.out.* = if (p.cached) |c|
try zit.sparse.classifyCached(gpa, c.io, c.root_dir, &c.holdings.index.log, c.holdings.index.classifyStore(), p.cone, .{}, .parse)
else
try classifyKeepRids(gpa, holdings, p.cone);
if (p.settle_nodes) {
// A new check-in's out-of-cone sub-manifests were never sent
// (section 6.2) and could not be classified until its tree had
// arrived: they are elided phantoms, not an unmet expectation.
var elided: RepoElidedSet = .{ .classification = &p.out.*.?, .store = holdings };
out.unresolved = client.unresolvedPhantomsExcept(holdings, elided.shunSet());
out.deferred_trees = try client.deferredTreesExcept(gpa, elided.shunSet());
}
}
return out;
}
/// What one push run reports: the number of artifacts uploaded and the round
/// count it took. `sent` reads the client's own upload counter, so it is the
/// exact count of `file` cards emitted — never an estimate.
/// submanifests §7.2 — `refused` counts artifacts the §7.2 gate declined to
/// upload because the peer never sent `send-submanifests`.
/// Carried alongside `sent` so a run that withheld an artifact can never be
/// reported as a success: the draft rules out silent omission.
const PushOutcome = struct { rounds: usize, sent: usize, refused: usize = 0, uv_skipped: u64 = 0 };
/// Drives a push client (§3.2/§3.3) to convergence over `tr`, uploading the
/// artifacts the peer lacks; returns the upload count and round count. The client
/// announces `ms`'s holdings via igot and uploads what the peer gimme's (§3.3
/// r24: push sends content but never obtains it). Sans-IO on this side of
/// `tr.exchange`. Its closed error set is the driver's own causes unioned with
/// the transport's, so `runPush` switches it exhaustively.
pub fn pushRun(
gpa: std.mem.Allocator,
tr: *transport.Transport,
holdings: repostate.ArtifactStore,
identity: RepoSyncIdentity,
credential: ?zit.sync.Credential,
admission: RepoAdmission,
/// A server that REFUSED states why in its error card. Copied out
/// here because the client owns the buffer and is deinit'd on the way out,
/// so the caller cannot reach it afterwards; the clone path does the same
/// for the sparse-origin refusal.
peer_error_out: *PeerErrorCopy,
notes: *ServerNotes,
sink: ?sync_driver.RoundSink,
clusters: ?*const clusterindex.Resolved,
truncated_out: *u64,
) sync_driver.RunError(*transport.Transport)!PushOutcome {
// A push client still RECEIVES — §3.3 answers the server's gimme-driven
// `file` cards in the same session — so `admission` is load-bearing here too.
var client = syncClient(.push, &identity, credential, admission);
defer client.deinit(gpa);
defer truncated_out.* = client.payloads_truncated;
defer notes.adopt(&client);
if (clusters) |c| {
client.clustered = &c.clustered;
try client.seedClusterPhantoms(gpa, holdings, c.missing);
}
errdefer peer_error_out.set(client.peerErrorText());
const stats = try sync_driver.runSyncProgress(gpa, &client, holdings, tr, max_stalled_sync_rounds, sink, null);
recordSyncStats(stats);
// Read the upload counter before `deinit` runs (the return expression is
// evaluated first): the exact number of `file` cards this session emitted.
return .{ .rounds = stats.rounds, .sent = client.content_sent, .refused = client.submanifests_refused, .uv_skipped = client.uv_skipped };
}
/// What one sync run reports: uploads (`sent`) and the round count. Received is
/// measured by the caller as the persisted-count growth (as pull does), so it is
/// not carried here.
/// submanifests §7.2 — see `PushOutcome.refused`.
const SyncOutcome = struct { rounds: usize, sent: usize, refused: usize = 0, uv_skipped: u64 = 0, peer_cursor: ?u64 = null, horizon_served: ?zit.sync.HorizonLevel = null, horizon_url: HorizonUrl = .{} };
/// Drives a bidirectional sync client (§3.2 round structure — both directions on
/// ONE §3.7 session) to convergence over `tr`; returns the upload count and round
/// count.
/// The received count is the caller's persisted-count growth. Sans-IO on this
/// side of `tr.exchange`; its closed error set is switched exhaustively by
/// `runSync`. The sibling of `pullRun`/`pushRun`, differing only in the
/// operation tag (`.sync`, which drives igot + gimme + upload on one session).
pub fn syncRun(
gpa: std.mem.Allocator,
tr: *transport.Transport,
holdings: repostate.ArtifactStore,
identity: RepoSyncIdentity,
credential: ?zit.sync.Credential,
admission: RepoAdmission,
peer_error_out: *PeerErrorCopy,
notes: *ServerNotes,
sink: ?sync_driver.RoundSink,
clusters: ?*const clusterindex.Resolved,
truncated_out: *u64,
) sync_driver.RunError(*transport.Transport)!SyncOutcome {
var client = syncClient(.sync, &identity, credential, admission);
defer client.deinit(gpa);
defer truncated_out.* = client.payloads_truncated;
defer notes.adopt(&client);
if (clusters) |c| {
client.clustered = &c.clustered;
try client.seedClusterPhantoms(gpa, holdings, c.missing);
}
errdefer peer_error_out.set(client.peerErrorText());
const stats = try sync_driver.runSyncProgress(gpa, &client, holdings, tr, max_stalled_sync_rounds, sink, null);
recordSyncStats(stats);
if (admission.erasure_latch) |l| try l.take(gpa, client.peerShunRows());
return .{ .rounds = stats.rounds, .sent = client.content_sent, .refused = client.submanifests_refused, .uv_skipped = client.uv_skipped, .peer_cursor = client.peer_cursor, .horizon_served = client.horizon_served, .horizon_url = .of(&client) };
}