esraft

A small, deterministic toy Raft implementation for learning and review.

Consensus lives in esraft/. Virtual time, the network, and cluster helpers live in simulation/. See PROJECT.md for architecture and scope, and TESTING.md for the scenario list.

pytest

How I used AI for this project

I used AI throughout, but not as a substitute for understanding Raft.

I started by discussing consensus algorithms with AI — what they are, how they differ, and which one would fit a small teaching implementation. From there I focused on Raft: I read and worked through the algorithm until I understood leader election, logs, commit, and recovery well enough to decide how this repo should be structured.

I then wrote markdown files (PROJECT.md, TESTING.md, AGENTS.md, REVIEW.md) so the project had an explicit design, test plan, and workflow before much code existed. AI used that scaffolding. I asked it to implement changes in small batches so I could read each diff and check that the new behavior matched what I expected.

Most of the simulator (simulation/) and the tests were written by AI. I did not do much of that work myself. For the demo in particular, I pointed AI at the official Raft visualization and asked it to follow that style, then to fix issues as they came up. The UI is where AI stumbled most often.

The Raft core is the part I treated as mine to own. I reviewed esraft/node.py and the files around it against my understanding of the algorithm. When the agent chose a design I would have done differently — for example keeping the log on the node instead of a separate log module — I questioned it and talked through the trade-off before accepting the change.

Overall it was smooth. The useful pattern was: I set the structure and verified consensus; AI generated the environment, tests, and a lot of the mechanical code in small, reviewable steps.

Interactive Demo

The browser UI visualizes the existing Python simulator. It does not reimplement Raft. The main view is an SVG cluster: timeout rings and RPC packets follow simulated time (election_started / deliver_time), not a separate frontend clock. Click a node for Stop / Resume / Restart / Time Out / Request.

python -m demo

Then open http://127.0.0.1:8000.

Optional: python -m demo --port 8000. Changing cluster size (3 or 5) creates a new simulation; it is not Raft membership change. The same seed replays the same randomized election timeouts.

Controls

Cluster-wide:

• Reset Cluster — new Cluster with the chosen size and seed
• Pause / Resume — stop or continue automatic virtual-time playback
• Step Event — run exactly the next scheduler event
• Speed — wall-clock pacing only; logical event order does not change

Per node (click a circle; actions appear in the compact bar):

• Stop — node is unavailable; persistent state is kept
• Resume — same in-memory node becomes available again
• Restart — crash/restart: new RaftNode, same PersistentState
• Time Out — fire that node's election timeout through the simulator
• Request — send SET <key> <value> to that node (non-leaders reject)

Scenarios

Leader election

1. Reset a 3-node cluster and leave it running, or click a follower and press time out.
2. Slow to 0.25x or use Pause + Step Event.
3. Watch FOLLOWER → CANDIDATE → RequestVote → majority → LEADER.

Follower catch-up

1. Wait for a leader.
2. Stop a follower.
3. Submit several Request SETs to the leader.
4. Resume the follower.
5. Click the leader and watch next index / match index in the peers table.

Loss of quorum

1. In a 3-node cluster, Stop two nodes.
2. Request a SET on the remaining leader.
3. The entry is appended but stays uncommitted.
4. Resume one node and watch it commit.

Leader failure

1. Wait for a leader.
2. Stop the leader.
3. Slow the simulation to 0.25x.
4. Watch the remaining nodes elect a new leader.
5. Resume the old leader and observe it become a follower.

Restart

1. Replicate a SET so a follower has a log and applied state.
2. Restart that follower.
3. Persistent term, vote, and log survive; commit_index / state machine reset until the node hears the leader again.