From zero to a
replicating cluster

Add the package

moonraft lives on mooncakes.io under moonbitstack; the source is moonbitstack/moonraft.

# in your MoonBit project
moon add moonbitstack/moonraft

First cluster: elect a leader

A Cluster is the batteries-included path: it wires the consensus core to a deterministic, single-seed network so you can drive a whole cluster from one thread. Bring up five nodes and let them elect a leader.

// Bring up five nodes and let them elect a leader.
let cluster = @raft.Cluster::new(["n1", "n2", "n3", "n4", "n5"], seed=7)
let leader = cluster.run_until_leader(300).unwrap()
println("elected \{leader} in term \{cluster.node(leader).term()}")

Output - verbatim

elected n3 in term 1

Replicate and read

Propose a command and wait until every node has committed it. committed_agrees checks that all five logs share the same prefix up to the commit index - the one guarantee a replicated log exists to provide.

// Propose a command; wait until every node has committed it.
let ids = ["a", "b", "c"]
let cluster = @raft.Cluster::new(ids, seed=11)
let _ = cluster.run_until_leader(200)
let _ = cluster.propose(b"set x = 1")
let _ = cluster.run_until_committed(2, 300)
println("all nodes committed through index 2: \{cluster.committed_agrees()}")
for id in ids {
  println("  \{id}: commit_index = \{cluster.node(id).commit_index()}")
}

Output - verbatim

all nodes committed through index 2: true
  a: commit_index = 2
  b: commit_index = 2
  c: commit_index = 2

Survive a leader crash

Crash the leader and let a survivor take over. The two invariants that decide correctness under failure still hold: at most one leader per term, and every committed prefix agreed across the cluster.

// Crash the leader; a survivor takes over, and safety must still hold.
let ids = ["a", "b", "c", "d", "e"]
let cluster = @raft.Cluster::new(ids, seed=5)
let first = cluster.run_until_leader(200).unwrap()
let _ = cluster.propose(b"cmd-1")
let _ = cluster.run_until_committed(2, 200)
cluster.crash(first)
let second = cluster.run_until_leader(400).unwrap()
println("crashed \{first}; new leader \{second}")
println("one leader per term : \{cluster.one_leader_per_term()}")
println("committed agree     : \{cluster.committed_agrees()}")

Output - verbatim

crashed a; new leader b
one leader per term : true
committed agree     : true

Plug in your state machine

Raft only orders bytes; meaning comes from your state machine, which applys each committed entry in log order. Implement the StateMachine trait, propose encoded commands, and fold every replica's committed log into a fresh store - the results must be identical.

// A replicated key-value store on top of the consensus log.
struct KV {
  data : Map[String, String]
}
fn KV::new() -> KV { { data: Map([]) } }
fn KV::get(self : KV, key : String) -> String? { self.data.get(key) }

impl @raft.StateMachine for KV with fn apply(self, cmd : Bytes) {
  let s = cmd.to_unchecked_string()
  if s.has_prefix("s") {
    let body = s[1:].to_owned()
    let mut key = ""; let mut value = ""; let mut eq = false
    for c in body {
      if !eq && c == '=' { eq = true }
      else if eq { value = value + "\{c}" }
      else { key = key + "\{c}" }
    }
    self.data[key] = value
  } else if s.has_prefix("d") {
    self.data.remove(s[1:].to_owned())
  }
}

// Encode a command as the UTF-16LE bytes apply() reads back.
fn to_wire(s : String) -> Bytes {
  let arr : Array[Byte] = []
  for c in s {
    let code = c.to_int()
    arr.push((code & 0xff).to_byte())
    arr.push(((code >> 8) & 0xff).to_byte())
  }
  Bytes::from_array(arr)
}
fn kv_set(k : String, v : String) -> Bytes { to_wire("s" + k + "=" + v) }

fn main {
  let ids = ["a", "b", "c"]
  let cluster = @raft.Cluster::new(ids, seed=9)
  let _ = cluster.run_until_leader(200)
  let _ = cluster.propose(kv_set("service", "moonraft"))
  let _ = cluster.run_until_committed(2, 300)
  for id in ids {
    let kv = KV::new()
    cluster.node(id).node().apply_committed(kv)
    println("  \{id}: service = \{kv.get("service").unwrap()}")
  }
}

Output - verbatim

  a: service = moonraft
  b: service = moonraft
  c: service = moonraft

The full program - with kv_delete and a self-check that every replica holds the same commands - is src/examples/04-kvstore.