Module replication 

Replication Module

Implements single-primary, multi-replica replication via WAL streaming.

Architecture

• Primary: accepts writes and streams WAL records to replicas
• Replica: read-only, connects to primary for WAL streaming
• Initial sync via snapshot transfer, then incremental WAL

Usage

// Primary
let options = RedDBOptions::persistent("./primary-data")
    .with_replication(ReplicationConfig::primary());

// Replica
let options = RedDBOptions::persistent("./replica-data")
    .with_replication(ReplicationConfig::replica("http://primary:50051"));

Modules

cdc

Change Data Capture (CDC) — stream of database change events.

commit_policy

Primary commit policies (PLAN.md Phase 11.4).

commit_waiter

Synchronous commit waiter (PLAN.md Phase 11.4 — ack_n).

lease

Serverless writer lease (PLAN.md Phase 5 / W6).

logical

Logical replication helpers shared by replica apply and point-in-time restore.

primary

Primary-side replication: WAL record production and snapshot serving.

quorum

Quorum-based commit coordination (Phase 2.6 multi-region PG parity).

replica

Replica-side replication: connects to primary, consumes WAL records.

scheduler

Backup Scheduler — automatic periodic snapshots with optional remote upload.

topology_advertiser

Server-side TopologyAdvertiser (issue #167).

Structs

CommitWaiter

LagConfig

Knobs for the lag/health computation. Kept as a small struct so the call sites (gRPC topology RPC, RedWire HelloAck builder) thread the same defaults without each one redeclaring constants.

LeaseStore

Wraps an AtomicRemoteBackend with lease primitives. The lease object is stored under a deterministic key derived from database_key; the store reads/writes that one key.

QuorumConfig

Quorum configuration stored alongside ReplicationConfig.

QuorumCoordinator

Tracks per-replica region bindings and pairs them with the primary’s ack map. PrimaryReplication owns the WAL buffer + ReplicaState list; this coordinator adds the region dimension and the wait-for- quorum logic without duplicating the ack table.

ReplicationConfig

Configuration for replication.

TopologyAdvertiser

Server-side advertiser. Zero-sized — all state is threaded through advertise()’s arguments so callers control the snapshot semantics.

TopologyAuthGate

Predicate over the caller’s auth context — answers “does this principal have cluster:topology:read?”.

WriterLease

One snapshot of who owns the writer lease for a database key.

Enums

AwaitOutcome

CommitPolicy

LeaseError

QuorumError

Errors raised by the quorum coordinator. The write itself succeeded on the primary WAL — these errors signal that replica acknowledgement did not reach quorum and the caller must decide whether to surface the failure or continue anyway.

ReplicationRole

Role of this RedDB instance in a replication cluster.

Constants

DEFAULT_REPLICA_TIMEOUT_MS

Default replica heartbeat timeout used when an operator hasn’t configured one explicitly. Matches the order of the poll_interval_ms default in ReplicationConfig (100 ms) multiplied by a generous fudge factor — five seconds without an ack flips a replica to healthy: false. Operators tune this via LagConfig.

TOPOLOGY_READ_CAPABILITY

Capability name from ADR 0008 §1.