RaftKV

A replicated key-value store on a from-scratch Raft in Go: 1,000 randomized fault schedules and 180,000 operations with zero linearizability violations, a checker proven by injecting real consensus bugs, and the same code running live in your browser as WebAssembly.

Built with Go, Raft, WebAssembly, Porcupine, GitHub Actions.

RaftKV implements Raft as a pure state machine (Tick, Step, Propose, Ready, Advance) with no disk, network, clock or goroutines inside the algorithm. Keeping I/O out is what makes it testable, because three drivers run the identical code. A seeded simulator puts five-node clusters through partitions, crashes and restarts from disk, message loss, reordering and duplication; it checks Raft's safety invariants (election safety, log matching, leader completeness, state-machine safety) after every step and checks client histories for linearizability with Porcupine, and any failure replays exactly from its seed. A real-process driver serves an HTTP key-value API with leader redirects (421 plus an X-Raft-Leader header), a checksummed write-ahead log with group commit and torn-write recovery, and exactly-once client sessions. A third driver compiles the same Raft to WebAssembly for an interactive visualizer where you can crash the leader, cut a node off and watch the election happen message by message. On top of the core algorithm it implements PreVote, CheckQuorum, the conflict-term fast log backup, pipelined appends, the §5.4.2 rule of committing only current-term entries, and snapshots with log compaction and InstallSnapshot. The committed results: 1,000 fault schedules and 180,000 checked operations with zero violations, with 74% of operations overlapping an active fault; 10 of 11 deliberately injected consensus bugs caught; and on a 3-node cluster with fsync on, throughput rising from 602 to 2,233 writes/s as clients go from 32 to 128 (23,454 writes/s with fsync off), measured on one laptop over localhost. Membership is fixed, reads go through the log rather than leases, and the randomized harness covers the consensus core rather than the real server's disk ordering. Built by Archit with Claude as the AI coding assistant.

• Raft core as a pure state machine (Tick / Step / Propose / Ready / Advance): no I/O, no clock, no goroutines, so one implementation drives the simulator, real servers and the browser
• Leader election with randomized timeouts, PreVote (a rejoining partitioned node can't depose a healthy leader) and CheckQuorum (an isolated leader steps down)
• Log replication with conflict-term fast backup, pipelined appends, and commit only by current-term entries (Raft §5.4.2)
• Snapshots with log compaction and InstallSnapshot for followers that fall behind
• Seeded fault simulator: partitions, crash/restart from disk, message loss, reordering and duplication, safety invariants after every step, Porcupine linearizability checks, exact replay from any seed
• Real-process mode: HTTP transport, CRC-checked write-ahead log with group commit, a KV API with 421 leader redirects, exactly-once client sessions
• WebAssembly visualizer: a live five-node cluster in the browser where you crash, isolate and write to nodes
• CI on every push: lint, the race detector, an 85% coverage gate and a 200-schedule linearizability run

Every project hits walls. Here's what nearly broke RaftKV — and how it shipped anyway.

• The first fault harness caught only 2 of 7 injected bugs; a harsher fault injector plus scripted "Figure 8" scenarios brought it to 10 of 11, each reproducible from a seed
• Throughput: an early trial managed about 29 writes/s; moving state into the log and batching fsyncs (group commit) raised it to roughly 600-2,200 writes/s with durability on
• An installed snapshot left stale log entries on disk that a crash could splice back in; found in review, fixed, and added to the injected-bug suite
• Crash recovery that truncates only a torn final record and refuses to start on corruption in the middle of the log
• A linearizability-checker timing bug treated operations in the same tick as concurrent; fixing the checker mattered as much as fixing Raft

Every build leaves residue. The takeaways from RaftKV that carry forward.

• Separating the algorithm from I/O is what makes a distributed system testable: the same code runs under a deterministic simulator, real processes and WebAssembly
• A test harness has to be tested too: injecting known consensus bugs is the only way to know that "0 violations" means anything
• Durability is a throughput problem: group commit, not cleverness in the algorithm, delivered the speed
• Honest limits belong in the write-up: fixed membership, reads through the log instead of leases, and one machine's throughput numbers