Raft: Understandable Distributed Consensus

1// Raft AppendEntries RPC — used for both log replication AND heartbeats
2// Heartbeat = AppendEntries with empty Entries slice
3
4// ── Arguments ────────────────────────────────────────────────────
5type AppendEntriesArgs struct {
6    Term         int        // leader's current term
7    LeaderID     int        // so followers can redirect clients
8    PrevLogIndex int        // index of log entry immediately before new ones
9    PrevLogTerm  int        // term of PrevLogIndex entry (log matching check)
10    Entries      []LogEntry // entries to replicate (empty = heartbeat)
11    LeaderCommit int        // leader's commitIndex
12}
13
14// ── Results ──────────────────────────────────────────────────────
15type AppendEntriesReply struct {
16    Term    int  // current term of follower (so leader can update itself)
17    Success bool // true if follower contained matching entry at PrevLogIndex
18}
19
20// ── Log Entry ────────────────────────────────────────────────────
21type LogEntry struct {
22    Term    int         // term when entry was received by leader
23    Command interface{} // state machine command
24}
25
26// ── Safety check (Log Matching Property) ─────────────────────────
27// Follower rejects AppendEntries if:
28//   1. args.Term < currentTerm  (stale leader)
29//   2. log[PrevLogIndex].Term != args.PrevLogTerm  (log diverged)
30//
31// On rejection: leader decrements nextIndex for this follower and retries.
32// This "walks back" until a matching prefix is found.
33
34// ── Commit rule ───────────────────────────────────────────────────
35// Leader commits entry at index N if:
36//   - N > commitIndex
37//   - log[N].Term == currentTerm   ← CRITICAL: never commit prior terms directly
38//   - A majority of matchIndex[i] >= N