$ show hashicorp/raft
hashicorp/raft is an embedded Go library implementing the Raft consensus algorithm for production distributed systems. In operation it manages a replicated log across a cluster: it performs leader election with pre-vote and leadership transfer extensions, replicates log entries from leader to followers with a quorum-based commit rule, snapshots and restores the replicated state machine, and handles cluster membership changes (voters, nonvoters, staging servers) via log-based configuration entries. It is the consensus engine embedded in HashiCorp Consul, Nomad, and Vault. There is no main package; it is consumed as a library through api.go entry points such as NewRaft, BootstrapCluster, RecoverCluster, Apply, AddVoter, RemoveServer, and LeadershipTransfer. Architecturally it is an interface-driven library: consumers plug in an FSM, LogStore, StableStore, SnapshotStore, and Transport. The core state machine lives in raft.go (runFollower/runCandidate/runLeader, processRPC), replication is handled by replication.go, quorum commit tracking by commitment.go, and a Future-based async pattern wraps all public API calls. The network transport (net_transport.go) abstracts any StreamLayer with connection pooling, FSM pipelining, and a heartbeat fast-path; in-memory stores and transports are provided for testing and embedding. The data flow is: Apply enqueues a log future, the leader appends it, replication sends AppendEntries to peers, commitment.go advances the commit index once a quorum matches, and a dedicated runFSM loop applies committed entries to the FSM. Snapshots are periodically written and shipped to lagging followers via InstallSnapshot. External runtime dependencies are deliberately small: go-hclog for logging, go-msgpack/v2 for wire encoding, and go-metrics (the deprecated armon implementation by default, with hashicorp/go-metrics opt-in behind a build tag). The repository also contains a significant verification wing: a fuzzy/ fault-injection cluster framework that exercises partitions, slow voters, membership churn, and leadership transfer while verifying FSM/log consistency, plus a raft-compat/ package that runs rolling-upgrade and pre-vote migration tests against a pinned older version. This gives the repo a hybrid character of production library plus research-grade protocol verification harness, but the dominant identity is a reusable application library. The project is actively maintained: commits land frequently (last commit 2026-10-12), CI runs via GitHub Actions, dependabot is enabled with zero alerts, and issues are triaged (58 open). Technical drift is medium: legacy protocol versions 0/1 and deprecated AddPeer/RemovePeer/peers.json paths are retained for backward compatibility, the default metrics dependency (armon/go-metrics) is deprecated, and the README/Makefile lag reality (README claims Go 1.16 while go.mod requires Go 1.25, and the Makefile pins golangci-lint v1.19.0 which is very old). These are compatibility burdens and documentation lag rather than rot; the core protocol code is current and well-tested.
The LLM identified 4 files worth highlighting for reuse:
A self-contained quorum calculation component. The commitment type tracks the highest log index each peer has replicated and, on each match update, recomputes the largest index that is held by a quorum of peers. This is the subtle heart of Raft's commitment rule (never commit without a majority) isolated into a compact data structure with no meaningful coupling beyond raft's basic index types. It can be lifted directly into any replicated-log or replicated-state-machine project that needs a correct majority-index tracker.
A ring-buffer cache that decorates any LogStore implementation. It serves recently written log entries from memory while transparently falling back to the underlying persistent store on cache misses, and it keeps the first/last index bookkeeping correct even when entries arrive slightly out of order. Because it implements the same LogStore interface it wraps, it is a clean, drop-in performance layer for any log-like storage backend and a textbook example of a caching decorator.
A small instrumentation utility that measures event-loop utilization. saturationMetric accumulates active time and evaluates a moving window to determine whether a processing loop is saturated past a configurable threshold, then reports that utilization through go-metrics. It was written for the FSM apply loop but is entirely generic: it imports only time and metrics primitives and can be reused to gauge headroom in any queue consumer, worker, or event-processing loop.
A typed, filterable pub-sub notification layer for cluster lifecycle events such as leader changes, peer membership changes, and heartbeat failures. Consumers register an Observer with a filter function and receive observations asynchronously without any direct coupling to Raft internals. The Observer/Observation/filter design is a generic observer-pattern implementation that could be extracted into any system needing subscription with per-subscriber event filtering.