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

Stable (1.0). The protocol is complete: leader election with pre-vote disruption protection, log replication, durable crash recovery (the persistence feature), snapshots with log compaction, single-server membership changes with non-voting learners (Event::AddLearner / Event::PromoteLearner), leadership transfer, and linearizable reads (Event::Read → Action::ReadReady, the ReadIndex protocol). All five Raft safety properties are asserted continuously by a kitchen-sink adversarial test suite under combined partitions, message loss/reorder/duplication, membership churn, and snapshotting; an application-level suite drives a replicated key-value store to convergence — and serves stale-free linearizable reads — under the same faults; and the decode path is fuzzed. The public API, the wire format, and the durable log format are frozen and will not change incompatibly before 2.0 (see the normative docs/PROTOCOL.md). The full surface is documented in docs/API.md, with performance baselines in docs/BENCHMARKS.md.

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.

ReadProbe

A leader’s read-confirmation probe, the network half of a linearizable read.

ReadProbeReply

A follower’s acknowledgement of a ReadProbe.

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.