Crate raft_io 

raft-io

A from-scratch implementation of the Raft consensus algorithm, built as a clean, embeddable library rather than a framework.

The protocol core is a deterministic state machine: you feed it Events (logical ticks, inbound Messages, client proposals) and it returns Actions (send these messages, apply this committed command). Time, networking, and storage are your concern, injected through the RaftLog and RaftTransport trait seams. That separation is exactly what makes the consensus core provable: it contains no wall clock and no I/O, so an entire cluster’s behaviour can be reproduced from a seed and a sequence of events.

Status

This is v0.8: alpha — feature complete, hardened, in consumer integration. The full protocol — election (with pre-vote disruption protection), replication, durable crash recovery (persistence), snapshots, membership changes, and leadership transfer — is in place and verified by a kitchen-sink adversarial test suite that asserts all five Raft safety properties under combined partitions, message loss/reorder/duplication, membership churn, and snapshotting, plus an application-level suite that drives a replicated key-value store to convergence under the same faults. The public traits and the wire and WAL formats are frozen (see docs/PROTOCOL.md); the decode path is fuzzed. Additions in this line stay MINOR-compatible — the pre-vote messages, for instance, are new #[non_exhaustive] enum variants that leave every existing wire and WAL encoding untouched. See docs/API.md for the full surface.

The three tiers

• Tier 1 — the common case in a handful of calls, no builder and no generic to name: RaftNode::new with a RaftConfig and the default in-memory MemoryLog.
• Tier 2 — RaftConfig’s builder for tuning election and heartbeat timing.
• Tier 3 — the RaftLog / RaftTransport traits for plugging in a durable store or a real transport.

Example — a single-node cluster elects itself and commits

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 the node becomes 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).
let actions = node.step(Event::Propose(b"set x = 1".to_vec())).unwrap();
assert!(actions.iter().any(|a| matches!(a, Action::Apply { .. })));
assert_eq!(node.commit_index(), 1);

Modules

framingframing

Typed wire framing for protocol messages.

prelude

The everyday surface, for use raft_io::prelude::*;.

Structs

AppendEntries

The leader’s replicate-and-heartbeat RPC.

AppendEntriesReply

A follower’s response to an AppendEntries.

HardState

The state Raft must persist before responding to any RPC.

InstallSnapshot

A leader’s transfer of a Snapshot to a follower too far behind to replicate entry by entry.

InstallSnapshotReply

A follower’s response to an InstallSnapshot.

LogEntry

A single entry in the replicated log.

MemoryLog

An in-memory RaftLog backed by a Vec.

MemoryTransport

An in-memory RaftTransport that records outgoing messages.

PreVote

A candidate’s pre-vote probe, sent before it commits to a real election.

PreVoteReply

A peer’s response to a PreVote.

RaftConfig

Configuration for a single RaftNode.

RaftNode

A node in a Raft cluster: the deterministic consensus state machine.

RequestVote

A candidate’s request for a vote in an election.

RequestVoteReply

A peer’s response to a RequestVote.

Snapshot

A point-in-time capture of the application’s state machine, with the log position it covers.

TimeoutNow

A leader’s signal telling target to start an election immediately.

WalLogpersistence

A durable RaftLog whose entries and hard state survive a process restart.

Enums

Action

An instruction RaftNode::step returns for the caller to carry out.

EntryKind

What a LogEntry carries.

Error

Everything that can go wrong while driving a RaftNode.

Event

An input handed to RaftNode::step.

Message

Any message a node can send or receive.

Role

The role a node currently plays in the consensus protocol.

Traits

RaftLog

Storage for a node’s persistent state: its log entries and its HardState.

RaftTransport

Delivers protocol messages to peers.

Type Aliases

Index

Position of an entry in the replicated log.

NodeId

Identifier for a node in the cluster.

Result

A specialised Result for raft-io operations.

Term

A Raft term: a monotonically increasing logical clock.