Replication and Snapshots

Purpose

Policy-aware strand vault with sessions, permissions, storage backends, WAL, fsck, snapshots, and replication.

This page follows the real source shape for Strand Vault and explains the workflow a developer is likely to use first.

Network contract

Document peer identity, topic selection, message framing, session lifetime, retry behavior, metrics, and what must be stable between releases. Any change here can strand peers, so examples should be exercised with at least two real processes.

Primary types to know

• AgentPermissions — libs/strand-vault/src/permissions.rs
• AppendGuard — libs/strand-vault/src/vault.rs
• Atom — libs/strand-vault/src/vault.rs
• CreateOptions — libs/strand-vault/src/config.rs
• DefaultPolicy — libs/strand-vault/src/policy.rs
• FileMetadataStorage — libs/strand-vault/src/storage/filesystem.rs
• FileSystemStorage — libs/strand-vault/src/storage/filesystem.rs
• FileSystemStorageFactory — libs/strand-vault/src/storage/filesystem.rs
• FileStrandStorage — libs/strand-vault/src/storage/filesystem.rs
• FsckReport — libs/strand-vault/src/fsck.rs
• IndexingConfig — libs/strand-vault/src/config.rs
• LruStoragePool — libs/strand-vault/src/storage/mod.rs

Example shape

use strand_vault::{ReplicationMode, ReplicationOptions, StrandId};

fn main() {
    // ReplicationOptions describes a replication session against one or more
    // strands. The vault hosts the schedule; mode picks Push / Pull / Sync.
    let strands = vec![
        StrandId::Name("audit-log".into()),
        StrandId::Name("metrics".into()),
    ];

    let live_pull = ReplicationOptions {
        strands: strands.clone(),
        mode: ReplicationMode::Pull,
        live: true,
        encrypted: true,
        bandwidth_limit: Some(2 * 1024 * 1024), // 2 MiB/s cap
        capability: Some(b"cap.v1.subscriber".to_vec()),
        start_from: Some(vec![(strands[0].clone(), 0), (strands[1].clone(), 12)]),
    };

    let bulk_sync = ReplicationOptions {
        strands,
        mode: ReplicationMode::Sync,
        live: false,
        ..ReplicationOptions::default()
    };

    println!(
        "live_pull={:?} bulk_sync_streams={} encrypted_pull={}",
        live_pull.mode,
        bulk_sync.strands.len(),
        live_pull.encrypted,
    );
}