raftlab

Raft consensus with a live cluster visualizer · 2026
raftlab visualizer during a network partition: five Raft nodes in a pentagon, two of them marked leader, with dashed red links where messages are dropped between the old leader and the rest
Network partition: two nodes believe they lead[term 2 vs 3]

Raft consensus implemented from scratch in Go — leader election, log replication, snapshots and crash recovery — with a linearizable key-value store on top and a browser UI where you can kill nodes, cut the network and watch the cluster recover.

Go code
5.1k lines
Of which tests
2.2k lines
Dependencies
1

Problem: Raft is the algorithm behind etcd, Consul and CockroachDB, and it is easy to nod along to the paper and hard to trust your own implementation. A consensus bug does not crash. It shows up as two nodes disagreeing after one specific sequence of crashes, partitions and reordered packets. I wanted to implement all of it, including the parts tutorials skip (persistence, log compaction, InstallSnapshot, exactly-once clients), and to see it behave rather than trust it.

Solution: A complete Raft implementation in Go: leader election, log replication with conflict repair, the election restriction, commitment of prior-term entries, a checksummed write-ahead log with crash recovery, and log compaction with InstallSnapshot for followers that fell far behind. A replicated key-value store sits on top. Reads go through the log, so they are linearizable, and client sessions make a retried write apply at most once. raftnode runs one member per process over HTTP. raftlab runs five in one process over a fault-injecting network and streams every message to the browser as an animated dot, where you can kill nodes, partition the network and dial in latency, loss and duplication.

Technical Approach: The core raft.Node is a pure state machine with no goroutines, sockets or wall-clock time. Everything it touches goes through four interfaces: Transport, Clock, Storage and StateMachine. Because time and I/O are injected, a five-node cluster runs on a fake clock inside a single-threaded test, and a run is a pure function of its random seed. A chaos test crashes and restarts nodes, partitions the network and injects loss, duplication and delay for 40 virtual seconds while four clients write and read, checking election safety and committed-prefix agreement every 10 ms. At the end it checks that replicas converge, that every acknowledged write survived and that every read returned the last acknowledged write. A failure prints its seed, and CHAOS_SEED=17 go test -run Chaos ./internal/kv replays it exactly. The core uses only the standard library; the single dependency is a WebSocket library for the visualizer.

Results & Learnings: About 5,100 lines of Go, around 2,200 of them tests, with CI running go test -race and golangci-lint. The bugs found along the way are the real lesson: stale timer callbacks that start a spurious election and depose a healthy leader, a delayed AppendEntries erasing newer entries, reordered replies moving nextIndex backwards, and a Windows-only crash where the WAL could not rename over an open file during its first compaction. The limits are written down too: a read costs a full replication round, snapshots are a single message and the client API is unauthenticated. PreVote, CheckQuorum, joint-consensus membership changes and ReadIndex reads are on the roadmap. The write-up covers how the fake clock works and the one bug it could not reproduce.

Stack
Go · WebSocket · SVG · GitHub Actions
Role
Full implementation