raft-io 0.5.0

Raft consensus and replicated-log engine for Rust. Leader election, log replication, membership changes, and snapshotting over a pluggable transport and a pluggable log store. The consensus layer above wal-db and the coordination substrate for Hive DB clustering.
Documentation
  • Leader election — randomized-timeout election with term and vote safety; one leader per term (live)
  • Log replication — batched append-entries with per-follower progress, optimistic pipelining, conflict-hint backtracking, and commit on a quorum (live in v0.3)
  • Deterministic core — the state machine is pure and step-driven, so the whole protocol is testable without time or I/O (live)
  • Pluggable transport — RaftTransport trait; in-memory for tests, real net for production (live)
  • Pluggable log store — RaftLog trait; wal-db-backed WalLog under the persistence feature (live in v0.4)
  • Crash recovery — term, vote, and log persisted before each RPC; a restarted node recovers and rejoins without violating safety (live in v0.4)
  • Snapshotting — install-snapshot for log compaction and fast follower catch-up, driven by a snapshot-policy hint (live in v0.5)
  • Typed framing — pack-io wire encoding for messages under the framing feature (live in v0.5)
  • Membership changes — single-server add/remove via joint-consensus-safe reconfiguration (v0.6)

Installation

[dependencies]
raft-io = "0.5"

# Optional features:
raft-io = { version = "0.5", features = ["persistence"] } # durable wal-db-backed `WalLog`
raft-io = { version = "0.5", features = ["framing"] }     # pack-io wire framing for messages

Quick Start

A node is a deterministic state machine. You hand it events with step and it hands back actions to carry out. The single-node path needs nothing else — no transport, no storage to wire up:

use raft_io::{Action, Event, RaftConfig, RaftNode};

// One node, no peers: it reaches quorum (itself) the moment it times out.
let mut node = RaftNode::new(RaftConfig::single(1));

// Drive logical ticks until it elects itself leader.
while !node.is_leader() {
    let _ = node.step(Event::Tick).expect("tick never fails in memory");
}
assert_eq!(node.leader(), Some(1));

// A leader commits its own proposals immediately (quorum of one).
for action in node.step(Event::Propose(b"set x = 1".to_vec())).unwrap() {
    if let Action::Apply { index, command, .. } = action {
        // hand `command` to your state machine, in log order
        assert_eq!(index, 1);
        assert_eq!(command, b"set x = 1");
    }
}
assert_eq!(node.commit_index(), 1);

A multi-node cluster works the same way: you route each Action::Send to the target node's step through a transport of your choosing, and feed every node logical ticks. The protocol is sans-I/O — when to tick and how to deliver messages are yours to decide, which is what makes the whole thing testable without a clock or a network.

Runnable examples show each path end to end:

cargo run --example single_node         # elect + propose + apply, one node
cargo run --example in_memory_cluster   # a 3-node cluster electing a leader
cargo run --example replicated_log      # propose + replicate; all nodes agree
cargo run --example partition_recovery  # minority stalls, majority commits, heal
cargo run --example snapshot_catchup    # leader compacts; lagging node catches up via snapshot
cargo run --example persistent_node --features persistence  # log survives a restart

Status

This is v0.5.0: the protocol is feature-complete bar membership changes. On top of election, the replication pipeline, and durable crash recovery, this release adds snapshots with log compaction — a configurable policy hint asks the application to snapshot, the log compacts behind it, and a follower too far behind to replicate is caught up with an InstallSnapshot then tail replication. The framing feature adds pack-io wire encoding for messages. Adversarial property tests drive 3- and 5-node clusters through reordered, dropped, duplicated, and partitioned schedules — with node crashes and snapshots interleaved — and assert that committed entries never diverge. Membership changes land in v0.6, per the ROADMAP (development copy). The full public surface is documented in docs/API.md.

Where It Fits

raft-io is the consensus engine. It is consumed by:

  • wal-db — durable Raft log persistence (under persistence)
  • pack-io — typed RPC message framing (under framing)
  • Hive DB — cluster coordination and replicated metadata

It stays foreign-compatible: usable standalone in any system that needs replicated, fault-tolerant state.

Cross-Platform Support

Tier 1 Support:

  • Linux (x86_64, aarch64)
  • macOS (x86_64, Apple Silicon)
  • Windows (x86_64)

Behavior is verified on each target by the CI matrix.

Contributing

Before opening a PR, cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean. Hot-path changes require a criterion benchmark; correctness-critical paths require property and/or loom tests.