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

bookmark

Causal bookmark token helpers.

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).

failover

Coordinated zero-RPO failover (issue #833, PRD #819).

flow_control

Write-admission flow control keyed on in-quorum replica lag (issue #826).

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.

swap_db

Stay-readable re-bootstrap with an atomic dataset swap (issue #837, PRD #819).

topology_advertiser

Server-side TopologyAdvertiser (issue #167).

Structs

CausalBookmark

CommitWaiter

FailoverCoordinator

The coordinated zero-RPO failover state machine.

FailoverNode

A node participating in a failover.

FailoverOutcome

The result of a completed handover.

FailoverRequest

A request to hand the primary role from old_primary to target.

FlowController

Ticket-based write-admission flow controller.

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.

RebootstrapInProgress

A causal read was requested while the node is re-bootstrapping.

ReplicationConfig

Configuration for replication.

RoleAssignment

Post-handover roles of the two nodes, used to assert that the new primary advertises the new term and the old primary streams as a replica (issue #833 criterion 3).

SwapDb

A dataset that stays readable across an atomic re-bootstrap swap.

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

Admission

Outcome of a write-admission attempt.

AwaitOutcome

BookmarkDecodeError

CommitPolicy

FailoverError

Why a coordinated failover could not complete without losing writes.

FailoverMode

How a failover should be executed.

LeaseError

NodeRole

The replication role a node plays after a failover step.

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_REPLICATION_TERM

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.

DEFAULT_SLOT_IDLE_TIMEOUT_MS

DEFAULT_SLOT_RETENTION_MAX_LAG_LSN

TOPOLOGY_READ_CAPABILITY

Capability name from ADR 0008 §1.

Traits

FailoverTransport

Cluster mutations and the clock the coordinator drives, injected so the state machine stays pure and deterministically testable.