Overview
Concord is an embedded, strongly consistent key-value store for Elixir. Its replicated runtime uses Viewstamped Replication (VSR) with one through six ordered members. A strict majority quorum commits each operation, so a minority partition cannot acknowledge writes.
Components
Concord.Applicationsupervises the VSR runtime, TTL cleanup, Watch dispatch, telemetry, and optional node-local engines.Concord.Engine.VSR.Supervisorbuilds one replica, one client session, and the Concord VSR engine from the explicit membership configuration.ViewstampedReplication.Replicaserializes protocol transitions and interprets transport, storage, timer, and state-machine effects.Concord.Engine.VSR.StateMachineadapts committed VSR operations toConcord.StateMachine.Core.Concord.StateMachine.Coreowns the deterministic KV, MVCC, index, lease, transaction, and backup state.ViewstampedReplication.Storage.Filepersists the VSR log and atomic checkpoints.
Concord.Local and Concord.Turso are explicit node-local alternatives. They
do not participate in VSR membership or replication.
Membership and primary selection
Membership is explicit and ordered. Every replica must use the same group_id
and member list. The current view selects a deterministic primary from that
order. A view change elects the next primary when the current primary becomes
unavailable.
Fresh multi-node clusters must start once with bootstrap: true. Durable
restarts use bootstrap: false; replicas recover their hard state, log,
commit/applied positions, client table, and latest state-machine checkpoint
from storage.
Write path
- Any Concord node accepts a public API command.
- The local VSR client routes the request to its believed primary.
- The primary appends the operation and sends prepare messages to backups.
- A quorum makes the operation committed.
- Replicas apply committed operations in order to
Concord.StateMachine.Core. - The client receives the deterministic state-machine result.
Client identifiers and monotonically increasing request numbers provide duplicate suppression across retries and primary changes.
Read path
Concord queries use quorum-confirmed read barriers. The current primary
confirms its view with a quorum, then evaluates the query against its applied
state without appending the read to the replicated log. The public
:eventual, :leader, and :strong option names are retained for API
compatibility, but currently use the same linearizable VSR read path.
Persistence and recovery
File storage uses a checksummed write-ahead log plus an atomically replaced checkpoint. Recovery truncates a partial or corrupt WAL tail to the last valid record, restores the latest state-machine snapshot, and replays committed operations after it. Snapshots compact the replicated prefix without changing the logical Concord state.
Failure model
VSR configurations tolerate failures while a majority remains available:
- one member tolerates no failure;
- two members tolerate no failure;
- three members tolerate one failure;
- four members tolerate one failure;
- five members tolerate two failures.
- six members tolerate two failures.
During a partition, only a quorum can continue committing operations. Nodes that fall behind recover through state transfer or snapshot installation before serving the current view.