eliben/raft: An Instructional Raft Implementation in Go

What eliben/raft is built to teach

eliben/raft solves an educational problem: it presents Raft as a sequence of progressively expanded implementations rather than as one abstracted library. The repository is intended for Go developers who want to understand how distributed consensus is expressed in code, especially how the implementation changes as the blog series adds elections, commands, log replication, persistence, a key/value database, and exactly-once delivery.

The project does not position itself as a general service or a packaged client library. Its main unit of work is a directory such as `part1`, `part2`, or `part3`, with each directory described as a complete source tree for one blog post. This structure makes it possible to compare a smaller implementation with a later one without having to understand a shared abstraction designed for reuse. The README says the duplication between parts is deliberate: keeping each part independent makes it easier to read and understand in isolation.

That choice has a direct consequence for adoption. An engineer looking for one importable component may find the repository less convenient than a library with a stable public API. An engineer studying the algorithm may find the independent snapshots much easier to inspect, because each part can be read as a complete example. The project therefore serves learning and code study more directly than dependency selection.

The partN architecture and implementation sequence

The repository is organized around independently runnable Go modules. The README identifies `part1` as the code associated with the elections post, `part2` with commands and log replication, and `part3` with persistence and optimizations. Part 0 has no code because it is introductory. The two later examples are named differently: `part4kv` and `part5kv` contain a key/value database that uses `part3` as its Raft implementation.

That structure exposes the algorithm as a progression. In the early part, the focus is elections. The later part adds commands and replication. Persistence appears in part 3, where the Raft code is located under `part3/raft` so it can be imported by future parts. The key/value examples then demonstrate how a replicated state machine is attached to the Raft layer.

The repository also separates the core implementation from teaching tools. The `tools/raft-testlog-viz/main.go` program reads captured test output and emits an HTML visualization. The README recommends adding calls to `cm.dlog(...)` to inspect more state transitions. Based on the repository layout, the intended learning loop is to run a focused test, save its verbose output, visualize the log, and then change the code to study the resulting differences.

The main limitation is equally important: the parts duplicate code on purpose. This is useful for instruction, but it means that a change in one part does not automatically become a change in every later part. The repository is a set of readable snapshots, not a single dependency that evolves through one shared implementation.

Running the first election test and opening its visualization

The README does not provide a separate installation command or a packaged binary. It tells readers to enter a part directory and run the Go tests. For the first documented example, change into `part1`, run the focused election test with verbose output and the race detector, and save the output for the visualization tool.

The command captures the test output in `/tmp/raftlog`. The README says the test should pass, and the visualization program emits an HTML file whose name is based on the test name.

cd part1
go test -v -race -run TestElectionFollowerComesBack |& tee /tmp/raftlog
go run ../tools/raft-testlog-viz/main.go < /tmp/raftlog

After running the commands, open the generated `file:///tmp/TestElectionFollowerComesBack.html` file in a browser. The screenshot included in the repository illustrates the log browser. The documentation says to scroll through the output and notice state changes, which are highlighted with colors. Adding `cm.dlog(...)` calls is the documented way to print additional details.

The race detector is used in the example, but the README does not claim that this command is a substitute for a deployment validation process. It is a teaching workflow centered on observing state transitions. The test output is the input to a visualization tool, so the log is not merely incidental terminal noise.

Running independent partN modules

Each `partN` directory is described as its own Go module. To work on `part2`, the README gives the basic test command after changing into that directory. The command runs the complete package set with the race detector.

cd part2
go test -race ./...

The same general instructions apply to part 3, with one path difference. Its Raft implementation is under `part3/raft`, so the README says to move into `part3/raft` when working directly with the Raft code. Verbose logging can be enabled with `-v`, and the `dotest.sh` script is available in the relevant part for running selected tests with log visualization. The README warns that tests can take up to a minute, depending on the part and the machine.

There is no documented installation of the repository as a hosted service, no documented production configuration, and no documented command for deploying a cluster. The practical first use is therefore source-oriented: select the blog part that matches the concept being studied, run its tests, inspect the logs, and make a controlled code change. This is a clear fit for a tutorial repository, but a poor fit for an engineer expecting an out-of-the-box distributed database.

Raft guarantees and the limits of the instructional scope

The README names the relevant Raft topics, but it does not provide a formal API contract, deployment guide, supported platform matrix, rollback procedure, or production readiness checklist. It also does not document how a user would configure a real cluster, secure its network, monitor it, or operate it across failures.

The project is explicit that it is an instructional implementation. The self-contained layout is a deliberate trade-off: it makes each blog part readable and allows graphical diffs between stages, but it also means that abstractions are not the priority. The README does not state that the parts are interchangeable libraries or that the latest part is a stable public API.

The exactly-once delivery material is especially important for readers to interpret carefully. The repository documents a Part 5 post about exactly-once delivery, but the README does not summarize its operational preconditions, failure model, or limits. A reader should inspect that part's code and tests before treating the label as a general guarantee. The repository's educational framing is compatible with studying delivery semantics, but it is not evidence that the example is ready for production workloads.

There is also no GitHub release history. Consumers therefore cannot rely on release notes as a source of upgrade guidance. A change from one `partN` directory to another may introduce both algorithmic additions and duplicated implementation changes.

Comparing the tutorial with a production Raft dependency

The real alternative is an existing production-oriented Raft library or database that packages a consensus implementation behind a maintained public API. The difference is primarily in purpose and packaging. eliben/raft keeps each part self-contained so a learner can follow the algorithm without first navigating a shared framework. A production library typically centralizes shared code and exposes integration points for servers, storage, networking, and application state machines, although the README does not document a particular competing library's exact interface.

That does not make eliben/raft interchangeable with such a library. Its value comes from the progression between blog parts, its test-driven examples, and its log visualization. A production package is chosen for deployment support, compatibility, operational documentation, and an integration contract. None of those claims is made for eliben/raft by the README.

For a production service, the absence of a release series and the tutorial structure are concrete reasons to pause. For education or a controlled code-reading exercise, adding an abstraction layer would defeat the repository's stated design. The right comparison depends on whether the goal is to understand Raft or to operate a replicated system.

Maintenance, upgrades, and the Unlicense

The repository is not archived, and its last push was on 2026-09-11. That fact supports treating the project as recently touched, but it does not establish a release cadence or a production support commitment. The repository has no GitHub releases, so there is no documented release train or upgrade path based on tagged versions.

The code is duplicated across parts by design. An upgrade decision should therefore be made per directory rather than by assuming that moving from `part2` to `part3` is a package version change. Readers who modify a part should keep the change scoped and rerun the part's documented tests. The README does not document rollback, semantic versioning, compatibility promises, or migration instructions.

The project uses the Unlicense. That identifier describes the repository's licensing choice, but this review does not interpret its legal effect. Engineers should read the repository `LICENSE` file themselves before redistribution or incorporation into another codebase. The README does not provide additional licensing guidance.

Editorial conclusion

Adopt eliben/raft when you need a readable Go reference for studying Raft or experimenting with a replicated key/value database. Do not adopt it as a replacement for a maintained production consensus library without first checking its guarantees, operational behavior, persistence design, and deployment requirements. For the strongest first evaluation, run the documented tests in the selected `partN` directory and inspect the generated visualization.

Frequently asked questions

Official sources

1. eliben/raft on GitHub
2. Issues
3. License: Unlicense
4. README