Raft Simulator

A Raft consensus simulator

How it's built

A Raft simulator you can break on purpose — and the engineering that makes breaking it trustworthy.

A Raft simulator you can break on purpose. Deterministic discrete-event simulation, continuous safety-invariant checking, and an ablation mode that turns individual Raft rules off so you can watch the guarantee they protect actually fail.

Source on GitHub ↗Simulator

  1. A pure function, replayed exactly

    The simulation is a pure function of (config, seed, actions, flags). A virtual clock, a seeded PRNG and an explicit tiebreak on equal timestamps make every trace byte-identical on any machine. That is what makes time travel, shareable links and reproducible bug reports possible.

    lib/sim

  2. Figure 2, implemented literally

    Every rule in lib/raft cites the figure and rule it implements. Each rule has a conformance fixture, alongside suites for Figure 8, Figure 13 and §6. Raft is easy to get almost right, and almost right is wrong.

    lib/raft

  3. A checker that shares no code

    lib/invariants evaluates the five safety properties from their definitions over global state, and imports nothing from the algorithm except types. A checker that reused the implementation’s assumptions would validate its own bugs.

    lib/invariants

  4. Ablation that cannot lie

    All seven rules are named guards in one file, each consulted at exactly one call site. Every switch has a test proving its property breaks when it is off and holds when it is on — both directions.

    lib/raft/rules.ts

  5. Fuzzed before every deploy

    All five properties hold across 10,000 randomized runs under unmodified Raft, with log compaction and membership changes active. The suite gates every deploy, and a failing seed becomes a permanent regression test.

    tests/fuzz

Prior art and sources

Prior art

RaftScope exists, it is excellent, and it was written by the author of the Raft paper. It is the canonical Raft visualiser — if you want to watch Raft run, start there. The Secret Lives of Data is a fine explainer too.

RaftScope ↗

What this adds

Not a replacement for either. Its contribution is narrower: ablation and invariant checking. RaftScope shows you the mechanism; here you switch a rule off and watch the safety property it defends break, while five indicators tell you which one failed and why.

Normative source

Ongaro & Ousterhout, In Search of an Understandable Consensus Algorithm (USENIX ATC 2014), extended version — Figure 2 in particular. Every rule in lib/raft cites the figure and rule number it implements.

raft.pdf ↗