raft-moonbit

Raft keeps a cluster of nodes agreeing on the order of a command log even when nodes crash and the network drops, delays and reorders messages — the foundation of the replicated state machines behind systems such as etcd, TiKV and Consul. This library ports the Go etcd-io/raft (Apache-2.0) to MoonBit, carrying over its protocol core, storage model and test suite; see NOTICE for what is derived and what is new.

It ships two ways to drive one consensus core:

• a synchronous driver (run_election, replicate) that composes the RPC handlers into whole rounds — small and easy to read or embed; and
• a message-driven server (RaftNode) that speaks only in Messages through tick and step, so a real transport — or the bundled deterministic simulator — can drive it exactly the way etcd separates protocol logic from I/O.

Install

moon add Lfan-ke/raft-moonbit

Quick example

// Drive a five-node cluster through the deterministic simulator.
let cluster = @raft.Cluster::new(["a", "b", "c", "d", "e"], seed=1)
let leader = cluster.run_until_leader(200)          // elect a leader
let _ = cluster.propose(b"set x = 1")               // replicate a command
let _ = cluster.run_until_committed(2, 200)         // wait for commit

cluster.crash(leader.unwrap())                       // inject a fault
let _ = cluster.run_until_leader(400)               // a new leader takes over
assert_true(cluster.one_leader_per_term())          // safety still holds
assert_true(cluster.committed_agrees())

Or run the bundled example — a five-node cluster elects, replicates, loses its leader and re-elects, printing the safety invariants at each step:

git clone https://github.com/Lfan-ke/raft-moonbit && cd raft-moonbit
moon run cmd/example

cluster of 5 nodes, seed 1
elected leader: b
committed 'set x = 1' on a majority
crashed the leader
new leader: c
one leader per term : true
committed prefixes agree : true
safety invariants hold : true

New to the library? examples/ is a guided tour in five short, runnable programs - from a first election up to a replicated key-value store:

moon run examples/00-helloworld     # elect a leader
moon run examples/01-replicate      # propose commands, confirm every node commits
moon run examples/02-fault-tolerance # crash, partition, drop packets - safety holds
moon run examples/03-operations     # progress, leadership transfer, compaction
moon run examples/04-kvstore        # a replicated key-value store on a StateMachine

Correctness

This is a line-by-line port, and it is verified as one. The porting census (PORTING.md) tracks every upstream Test* function and has no PARTIAL or TODO rows left — every test that does not depend on Go’s runtime is ported assertion-for-assertion, with no simplified cases, no skipped table rows and no weakened assertions; each remaining N/A (a goroutine/channel shell, a benchmark, or a Go struct-memory-layout assert) states its MoonBit equivalent.

Three independent methods cross-check behaviour against etcd-io/raft@26647d5:

Together they surfaced 24 correctness defects in the consensus, log and storage layers — safety, liveness, behavioural and accounting — plus 2 default-configuration mismatches, each fixed under a red-then-green regression test that is still in the suite. Several defect classes were then made unrepresentable: narrowing a storage error to a single-variant type turned a whole class of mistaken catch into a compile error, and exhaustive matching flags any never-constructed variant at build time.

Live demo — real consensus in your browser

▶ https://lfan-ke.github.io/raft-moonbit/demo.html

Five nodes, five Web Workers. Each worker instantiates its own copy of this consensus core compiled to WebAssembly, ticks on its own wall-clock timer, and talks to peers only by postMessage. The main thread is the network — drop packets, add delay, split the cluster, isolate or crash the leader — and it holds no Raft state of its own. Elections race, messages reorder, nothing about the schedule is deterministic; a panel re-checks the safety invariants (one leader per term, committed prefixes agree) on every frame.

Click Split 2 | 3 and you can watch two nodes lead different terms at once - and Election Safety still holds, because two leaders only contradict Raft if they share a term, and the stale one cannot reach a majority, so it cannot commit. Heal the partition and it steps down.

It is not a JavaScript re-implementation — messages cross the boundary as flat integers, node state is a JSON string read straight out of the wasm module’s linear memory, and every transition happens inside the same MoonBit code the tests exercise (worker_driver.mbt). Honest scope: five workers on one machine model concurrency, not a distributed deployment, and a restarted node catches up from the leader since the workers have no persistent storage.

moon build --target wasm --release              # -> _build/wasm/release/build/demo/demo.wasm
cp _build/wasm/release/build/demo/demo.wasm docs/raft-moonbit.wasm
python3 -m http.server 8099 --directory docs    # then open http://localhost:8099/

Features

Architecture

The code follows the upstream etcd-io/raft package layout so a reader can audit the port package-by-package. The root raft.mbt is a pure facade that re-exports the public surface, so consumers write @raft.X regardless of where a symbol lives.

License

Apache-2.0. See LICENSE and NOTICE. A MoonBit port of etcd-io/raft (Copyright 2015 The etcd Authors); the protocol core, storage model and test suite are derived from it. What this port adds is the MoonBit data model — algebraic data types and exhaustive matching in place of Go structs and switches — a deterministic simulation harness with built-in safety-invariant checks, and a WebAssembly browser demo that runs each node in its own Web Worker.

Mirrored on GitLink (heke1228/raft-moonbit) — same author, same history. The differential-testing harness lives on the difftest branch.