v1.0.0 — Stable API

[jamesgober]

raft-io v1.0.0 — Stable

A complete, frozen Raft. From the first scaffold, raft-io was built to be the
consensus engine three projects could stake their correctness on. With 1.0 the
protocol is complete, every safety property is proven under adversarial fault
injection, the performance baseline is set, and the public API, wire format, and
durable log format are frozen — no backward-incompatible change before 2.0.

What is 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,
sans-I/O state machine: you feed a node events and it returns actions. Time,
networking, and storage are injected through trait seams, which is what makes the
core provable and reproducible from a seed. It is the consensus layer above
wal-db and the coordination substrate for Hive DB clustering.

The complete protocol

Everything Raft needs to run a real replicated system, and nothing it does not:

• Leader election with term and vote safety, randomized timeouts, leader
  stickiness, and pre-vote so a partitioned node cannot disrupt a healthy
  cluster when it rejoins.
• Log replication — batched AppendEntries, per-follower progress with
  optimistic pipelining, conflict-hint backtracking, and commit on a quorum.
• Durable crash recovery — term, vote, and log persisted before each RPC; a
  restarted node recovers and rejoins without violating safety (the WalLog,
  under the persistence feature).
• Snapshots with log compaction and InstallSnapshot catch-up for a
  far-behind follower, driven by a snapshot-policy hint.
• Membership changes — single-server add/remove with safe sequencing, and
  non-voting learners that catch up without affecting any quorum, then get
  promoted to voters.
• Leadership transfer — hand off to a caught-up peer with TimeoutNow.
• Linearizable reads — the ReadIndex protocol: a read that reflects every
  committed write, confirmed against a quorum, with no log append.

Proven, not just written

• A kitchen-sink adversarial suite turns every fault mode on at once —
  partitions, message loss, reordering, duplication, membership churn, and
  snapshotting under one randomised schedule — and asserts all five Raft safety
  properties continuously: Election Safety, Leader Append-Only, Log Matching,
  Leader Completeness / State Machine Safety, and apply ordering. Run sustained to
  PROPTEST_CASES=6000+.
• An application-level suite drives a replicated key-value store to identical
  state on every node — and serves stale-free linearizable reads — under the same
  faults.
• The decode path is fuzzed: arbitrary bytes off the wire or off disk decode
  to a valid value or fail cleanly, never panicking or over-allocating.
• Determinism: no wall clock, no I/O in the core; an entire cluster run is
  reproducible from a seed and a sequence of events.

Built to a standard

• #![forbid(unsafe_code)]; no unwrap/expect/panic/todo on any production
  path (enforced by deny lints); every fallible operation returns Result.
• Allocation-free steady-state hot paths; committed performance baselines for
  every shape of step in docs/BENCHMARKS.md (a follower tick
  is ~8 ns).
• A three-tier API: trivial single-node use needs no generic to name; a builder
  tunes timing; traits plug in real storage and transport.
• The full surface is documented item-by-item in docs/API.md, and the
  protocol is specified normatively in docs/PROTOCOL.md.

The freeze

As of 1.0, the public API, the Message set and its pack-io framing, the
WalLog record format, and the configuration encoding are frozen and will not
change incompatibly before 2.0. Future additions stay compatible through
#[non_exhaustive] enums and tagged encodings.

Breaking changes

None versus 0.10.1. This release is documentation, an added example, and the
final specification pass; behaviour is unchanged.

Verification

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo deny check
cargo audit
cargo build --examples --all-features
cargo bench

All green. At this tag: 122 unit + 22 integration / property tests + 60 doctests,
nine runnable examples, and the hardening suite soaked at PROPTEST_CASES=6000.
MSRV: Rust 1.85 (edition 2024). loom is not exercised: the core is a
single-threaded, owned state machine with no lock-free or shared-state path.

Installation

[dependencies]
raft-io = "1.0"

# Optional features:
raft-io = { version = "1.0", features = ["persistence"] } # durable wal-db-backed log
raft-io = { version = "1.0", features = ["framing"] }     # pack-io wire framing

Documentation

• README
• API Reference
• Protocol Specification
• Benchmarks
• CHANGELOG

---

Full diff: v0.10.1...v1.0.0.
Changelog: CHANGELOG.md.

---

This discussion was created from the release v1.0.0 — Stable API.