Deep Dive into Raft Consensus Algorithm with Code

Raft operates by electing a single distinguished Leader node among a cluster of servers (typically 3 or 5 nodes). The leader has complete responsibility for managing the replicated log: it accepts client requests, appends commands to its log, propagates log entries to Follower nodes, and tells followers when it is safe to commit entries to their state machines. If a leader fails or becomes disconnected, a Candidate node initiates an election to select a new leader.

Time in Raft is divided into arbitrary Terms, represented by monotonically increasing integer term numbers. Terms act as a logical clock in distributed systems, allowing nodes to detect obsolete information such as stale leaders. Every node stores its current term number on stable storage. Whenever nodes communicate via RPC, they exchange their term numbers. If a node discovers its term is smaller than another node's term, it immediately updates its term and transitions to Follower state.

This strong leader approach simplifies data flow compared to leaderless consensus algorithms. Clients only communicate with the leader. If a client contacts a follower, the follower redirects the client to the current leader. For context on how Raft powers modern infrastructure, see our analysis of Redis Redlock vs etcd vs ZooKeeper.

Raft uses a heartbeat mechanism to trigger elections. When servers start up, they begin as Followers. A follower remains in the follower state as long as it receives periodic AppendEntries RPCs (heartbeats) from a Leader or Candidate. If a follower receives no communication within a configurable Election Timeout (typically 150ms–300ms), it assumes there is no viable leader and begins an election.

To start an election, the follower increments its current term, transitions to Candidate state, votes for itself, and issues RequestVote RPCs in parallel to all other cluster nodes. A candidate remains in Candidate state until one of three events occurs: (1) it wins the election by receiving votes from a majority of cluster nodes, (2) another server establishes itself as leader, or (3) a time period elapses with no winner (split vote).

To prevent split votes where candidates continuously split votes equally, Raft uses Randomized Election Timeouts. Election timeouts are chosen randomly from a fixed interval (e.g., 150–300ms) for each node. This random spread ensures that one node will time out before the others, win the majority of votes, and broadcast heartbeats before competing nodes time out.

Once a Leader is elected, it handles all incoming client requests. Each client request contains a command to be executed by the replicated state machine. The leader appends the command to its own log as a new entry, containing the log index, the term number, and the command payload. The leader then issues AppendEntries RPCs in parallel to all followers to replicate the entry.

An entry is considered Committed once it has been safely replicated on a majority of cluster nodes by the leader of the current term. Committing an entry guarantees that it is durable and will eventually be executed by all reachable state machines. Raft maintains strict log invariants: Log Matching Property dictates that if two logs contain an entry with the same index and term, they are identical in all entries up through the given index.

To enforce safety during leader elections, Raft includes the Election Restriction: a follower will deny its vote in RequestVote if the candidate's log is less up-to-date than its own. A candidate's log is more up-to-date if its last entry has a higher term, or if terms are equal, if its log contains more entries. This guarantees that an elected leader already contains all committed entries from previous terms.

In production environments, servers must occasionally be replaced or added to scale capacity. Changing the cluster configuration (the set of servers participating in consensus) directly is dangerous because two independent majorities could be formed if two nodes adopt different configurations simultaneously.

To perform configuration changes safely, Raft uses a two-phase transition known as Joint Consensus. When changing from configuration $C_{\text{old}}$ to $C_{\text{new}}$, the leader first logs and commits a configuration entry for $C_{\text{old,new}}$. During Joint Consensus, log entries are replicated to nodes in both configurations, and agreement requires separate majorities from both $C_{\text{old}}$ and $C_{\text{new}}$.

Once $C_{\text{old,new}}$ is committed, the leader writes and commits a final configuration entry for $C_{\text{new}}$. From this point forward, decisions only require a majority from $C_{\text{new}}$. This two-phase transition eliminates the risk of split-brain decisions during cluster reconfiguration. For broader theoretical context on system partitions, consult our guide on the CAP theorem.