Raft Simulator

The problem

Engineers learning distributed systems meet Raft early. It is the agreement algorithm behind etcd, Consul and CockroachDB. It keeps a group of servers agreeing on one shared record when machines crash or the network splits. It was designed to be teachable, yet the teaching tools stop in the same place.

The standard visualiser, RaftScope, was written by the paper's own author. It shows elections, messages and growing logs well. It doesn't show why each rule exists. Two gaps follow. Nothing checks Raft's five safety guarantees as a run unfolds. And nothing lets you switch a rule off to see what breaks. The paper's Figure 8 makes exactly that argument, as a static diagram most readers don't fully absorb.

I built Raft Simulator for engineers learning distributed systems, students working through the paper, and interviewers or teachers who need a live example.

What I built

The whole simulation is repeatable

The same settings, seed and user actions always produce the exact same run, on any machine. I use a virtual clock, so a thousand simulated seconds pass in microseconds. Each server is a self-contained state machine, and every number is a whole number. That one decision gives rewinding, shareable links, reproducible bug reports and large-scale random testing.

I built the rules from the paper and checked them separately

I implemented the server logic rule by rule from Figure 2 of the paper, with each rule citing the part it implements. A teaching tool that is slightly wrong teaches wrong Raft with good animations. The safety checker shares no code with the algorithm. It evaluates the five guarantees from their published definitions after every event, so it can't approve the algorithm's own bugs.

Each rule can be switched off, and the switch is enforced

Seven rules can be turned off. Each one is checked in exactly one place in the code, so no hidden second copy keeps enforcing it. Each has tests proving the guarantee breaks with it off and holds with it on. Once a rule is off, the run is marked "modified Raft" on screen and in any shared link, so nobody mistakes a broken run for the real algorithm.

Launch waited for three correctness checks

I didn't publish until three independent checks were green: the separate safety checker, random testing against the five guarantees, and one test case per Figure 2 rule. I also built two features the plan had left out of the first version: log compaction and changing cluster membership. Both changed the data model. Cluster size became a variable, so every majority check now works on configurations.

Twelve scenarios explain one thing each

Random runs are either dull or impossible to follow. So I wrote 12 scenarios by hand, each showing one named effect, such as a split vote, a stranded leader after a partition, or Figure 8 itself. Every scenario is covered by a determinism test.

Result

Raft Simulator is live and public, installable and fully offline. The main view is a log ledger. Every server's log sits in a column aligned by position, so divergence reads as a broken line and repair reads as the leader overwriting it. When a guarantee breaks, the app names the property, the position, the terms and the servers involved. Any run can be sent as a link.

All five safety properties held across 10,000 random runs with compaction and membership changes active. The app is in English with a complete Indonesian translation. It links RaftScope and the paper, and claims only the switches and the checking as new. I built it in two days in August 2026.