raft-io 0.1.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 in v0.2)
  • Deterministic core — the state machine is pure and step-driven, so the whole protocol is testable without time or I/O (live in v0.2)
  • Pluggable transport — RaftTransport trait; in-memory for tests, real net for production (live in v0.2)
  • Pluggable log store — RaftLog trait; wal-db-backed under the persistence feature (trait in v0.2; durable backend in v0.4)
  • Log replication — append-entries pipeline with batching and flow control (v0.3)
  • Snapshotting — install-snapshot for log compaction and fast follower catch-up (v0.5)
  • Membership changes — single-server add/remove via joint-consensus-safe reconfiguration (v0.6)

Installation

[dependencies]
raft-io = "0.2"

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.

Two runnable examples show both paths 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

Status

This is v0.2.0: the deterministic protocol core. Leader election with full term and vote safety, the leader heartbeat, and single-node commit all work end to end over the in-memory drivers, and Election Safety is checked by a property-test suite. Multi-node log replication lands in v0.3, durable persistence (wal-db) in v0.4, and snapshots in v0.5, 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.