Skip to content
zit Artifact [541e3bd0e9]
Login

Artifact [541e3bd0e9]

Artifact 541e3bd0e9329ff47d4667b0703e01be5ad9d020f66ea2f043e1e17a400b4f7f:


//! 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) };
}