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)

Maintains redundant copies of the replicated state machine to ensure fault tolerance. Operates in one of three roles:

• 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: Manages client writes, drives log replication, and issues regular heartbeats to maintain authority.

In the demo, observe how nodes transition roles (colors change, and status badges like Follower, Candidate, or Leader update) during election timeouts and network recovery.

Randomized Election Timers

Prevents split-brain scenarios where multiple followers attempt to run for leader simultaneously (split vote). Configures each node with a randomized heartbeat timeout (typically 150-300ms) before it initiates an election. In the demo, note the progress rings around each node. The node whose ring fills first becomes a candidate, increments its term, and requests votes.

RequestVote RPC

Allows candidates to safely solicit votes and prove eligibility to lead. Carries candidate ID, current term, and details of the candidate’s last log entry so voters can enforce leader completeness. In the demo, observe the vote request particles (amber dots) traveling from a Candidate node to all other nodes in the cluster.

AppendEntries RPC (Heartbeats)

Keeps followers in sync and asserts the leader’s active authority. Carries log entries for replication, previous log indexes, and the leader’s commit index. In the demo, observe heartbeats (blue particles) flowing continuously from the Leader node to Followers to keep election timers from expiring.

Replicated Log & Commit Index

Records the ordered sequence of state machine operations across nodes. Stores client commands locally first. Once replicated to a majority quorum of nodes, the entry is committed and applied to the state machine. In the demo, watch log entries (e.g. T1 [SET x=1]) turn green (committed) once a majority of nodes successfully write them.

---

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.