Orleans.Lattice.Backup 9.9.0

Orleans.Lattice.Backup

Optional, opt-in causally-consistent backup and restore add-on for Orleans.Lattice. Captures a named, point-in-time backup of a selected scope of a lattice tree and restores it later without losing a single bit of causal metadata - zero runtime cost until AddLatticeBackup is registered.

Design

AddLatticeBackup() installs the storage and engine surface on top of the core snapshot, write-ahead-log, and merge machinery:

• Full capture - a scoped snapshot exported through the core zero-observable-writes cursor, with a self-describing manifest that records the consistency cut, shard topology, per-key shape and merge-mode map, per-origin provenance high-water marks, and an optional compression-dictionary reference.
• Incremental capture - a forward write-ahead-log differential layered on a base backup, resuming from the base's per-partition WAL offsets and falling back to a full capture when the resume point has been trimmed, a range delete surfaces in the delta window, or the base chain was captured on a different cluster.
• Restore - a mode-faithful replay that reinstalls every entry's hybrid-logical-clock, version vector, origin cluster id, expiry, and tombstone flag exactly as captured, either in place (bulk-load or last-writer-wins merge) or via an atomic shadow-cutover to a fresh tree.
• Scheduling and retention - opt-in recurring full and incremental schedules per scope, and a chain-aware retention policy that never prunes the base chain of a retained increment.

Every backup id is the SHA-256 content address of its captured payload (an incremental's id also folds in its base backup id), so a retried capture that produces identical bytes re-registers the same backup rather than a duplicate, and a restore is idempotent under retry. Artifact ids are per-capture, not content-addressed. Backups are written to a pluggable ILatticeBackupSink, defaulting to an in-cluster dogfooded tree, with a durable Azure Blob Storage sink shipped as a sibling package.

Security

Every capture and restore authorizes its scope through the same access gate the data path uses, against a dedicated Backup (capture) or Restore (author / bulk-load) capability, before touching data; the list, describe, and delete operations of the Orleans.Lattice.Api.Backup control facade authorize each manifest's scope the same way. The engine's catalog-store and sink seams themselves perform no authorization check. The catalog and store live in reserved sys-backup-* trees that inherit the core sys- catalog-hiding filter.

Registration

siloBuilder
    // Not durable: use a durable grain storage provider and a durable WAL in production.
    .AddLattice((silo, name) => silo.AddMemoryGrainStorage(name))
    .AddLatticeBackup();

With the in-memory grain storage above and the in-memory WAL that core registration installs by default, the default in-cluster sink's backups and the backup catalog - both ordinary reserved sys-backup-* trees - do not survive a restart. A durable deployment registers durable grain storage and a durable WAL provider, and for disaster recovery a durable external sink.

For operator-facing backup and restore, the API facade offers accept-then-poll operations with durable progress and cancellation. Engine service interfaces in this package remain current; the facade's older blocking verbs are deprecated and will be removed in the next major version. Migration guide: https://nsta1.github.io/Orleans.Lattice/docs/lattice.api.backup/operations.html#migrating-from-the-blocking-verbs.

Must be registered after AddLattice(...). For a remotely-drivable control plane, add the Orleans.Lattice.Api.Backup facade and its gRPC binding.

See the Backup documentation for the full guide.