Raft Consensus Protocol

Mental Model

In a distributed system, consensus is the process of getting multiple independent servers (nodes) to agree on a single sequence of state transitions (a log). Raft is a consensus protocol designed to be understandable and easy to implement, commonly powering coordinate stores and configuration registries like etcd or Consul.

Raft works by electing a single, strong Leader who takes complete responsibility for managing the replicated log. Clients send write commands directly to the Leader. The Leader appends these commands to its log and replicates them to other nodes (Followers). The log is only considered committed once a majority of nodes have acknowledged receiving it, ensuring that even if some nodes crash, the committed history remains durable and consistent.

graph TD
    Client[Client Browser] -->|1. Write Command| Leader((Leader Node))
    Leader -->|2. AppendEntries RPC| Follower1((Follower Node))
    Leader -->|2. AppendEntries RPC| Follower2((Follower Node))
    Follower1 -->|3. Acknowledge| Leader
    Follower2 -->|3. Acknowledge| Leader
    Leader -->|4. Commit Log Entry| Leader
    Leader -->|5. Apply & Reply| Client

---

Components and Why They Exist

Raft Nodes (Consensus Members)

Raft nodes maintain redundant copies of the replicated state machine to guarantee fault tolerance. Each node operates in one of three roles at any time, reflected by its node color and status badge (Follower, Candidate, or Leader) as election timeouts and network recovery unfold:

• Follower: Passive listener that responds to incoming RPCs from leaders and candidates.
• Candidate: Temporary role assumed when a follower’s election timer expires, initiating a request for votes.
• Leader: Active coordinator that accepts client writes, drives log replication, and sends regular heartbeats to maintain authority.

Randomized Election Timers

Randomized election timers prevent split-vote stalemates where multiple followers campaign for leader simultaneously. Each node configures a randomized heartbeat timeout (typically 150–300ms) tracked by its surrounding progress ring; the node whose timer ring fills first transitions to Candidate, increments its term counter, and requests votes from peers.

RequestVote RPC

The RequestVote RPC allows candidates to solicit votes and prove log eligibility to lead a new term. Amber vote-request particles travel from the Candidate node to all peer nodes carrying the candidate ID, current term, and last log index/term so voters can enforce leader completeness before granting a vote.

AppendEntries RPC (Heartbeats)

The AppendEntries RPC keeps follower logs synchronized and asserts the leader’s authority. Blue heartbeat particles flow continuously from the Leader node to Followers to reset their election timers, while also carrying new log entries, predecessor log consistency checks, and the leader’s current commitIndex.

Replicated Log & Commit Index

The replicated log and commit index record the ordered sequence of state machine commands across cluster nodes. The leader appends client commands locally first, and once a majority quorum of nodes acknowledges writing an entry (such as T1 [SET x=1]), the log slot turns green to indicate it is committed and safe to apply to the state machine.

---

Edge Cases and Misconceptions

Network Partition (Split Brain)

A common misconception is that a network partition will immediately corrupt the database by allowing two leaders to commit conflicting entries. If a 5-node cluster is partitioned into a 2-node segment (with the old leader) and a 3-node segment, the 2-node segment can accept client writes but cannot commit them because it lacks a majority quorum (3 nodes). Meanwhile, the 3-node segment will elect a new leader and can commit writes. When the partition heals, the stale logs on the 2-node segment are rolled back and replaced by the new leader’s history.

Election Safety (Leader Completeness)

Raft guarantees that if a log entry is committed in a given term, that entry will be present in the logs of the leaders for all higher-numbered terms. During elections, followers reject a candidate’s vote request if the candidate’s log is less up-to-date than the follower’s own log. This ensures a node with stale data can never become leader and overwrite committed history.

Randomized Election Timer Collisions

If all nodes used the exact same election timeout (e.g., 200ms), they would all become candidates at the same millisecond. Each node would vote for itself, resulting in a split vote where no candidate wins a majority. The cluster would stall, term after term. Randomizing timeouts (e.g., 150-300ms) ensures one node’s timer almost always expires first, quickly winning the election.