Skip to content

v0.7.0 — Hardening + API/Protocol Freeze

Pre-release
Pre-release

Choose a tag to compare

View all tags
@jamesgober jamesgober released this 08 Jun 13:01
· 6 commits to main since this release
v0.7.0
fcc6f65

raft-io v0.7.0 — Hardening + API/Protocol Freeze

Proven, and frozen. v0.7.0 adds no features — it proves the ones already
there. A single kitchen-sink test now turns every fault mode on at once and
asserts all five Raft safety properties under sustained, adversarial runs; the
decode path is fuzzed; and the public traits and the wire and WAL formats are
frozen behind a normative specification. From here to 1.0 it is alpha/beta
soak and bug fixes only.

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.

What's new in 0.7.0

One harness, every fault, every safety property

tests/hardening.rs is a jepsen-style nemesis: a single randomised schedule that
combines partitions, message loss, reordering, duplication, membership churn,
and snapshotting on one cluster, and after every step asserts the complete set
of Raft safety properties:

  1. Election Safety — at most one leader per term.
  2. Leader Append-Only — a leader never overwrites or deletes an entry in its
    own log; it only appends.
  3. Log Matching — if two logs hold an entry with the same index and term, the
    logs agree on every entry up through that index.
  4. Leader Completeness / State Machine Safety — no two nodes ever apply a
    different command at the same index, across leader changes, snapshots, and
    reconfiguration.
  5. Apply ordering — each node applies in strictly increasing index order.

The earlier suites each stressed one dimension and checked a subset of these; this
turns them all on together and adds the two properties they did not check
explicitly — Leader Append-Only and Log Matching. It has been run sustained
(PROPTEST_CASES=8000) with no violation.

The decode path is fuzzed

The only untrusted input a node sees is bytes off the wire. Both decoders —
framing::decode and the WalLog record decoder — are now covered by proptest
no-panic properties that run cross-platform in the default suite: arbitrary bytes
must decode to a valid value or fail cleanly, never panic, and anything that
decodes must re-encode to identical bytes (the wire format is canonical). A
cargo-fuzz target in fuzz/ provides coverage-guided fuzzing on nightly.

A normative protocol specification

docs/PROTOCOL.md specifies the protocol in RFC-2119 terms: the state model, the
message set and their semantics, the pack-io wire framing, the durable WAL
record format (byte-level), the snapshot and membership-change rules, and the five
safety invariants. It is the contract a second implementation would honour to
interoperate.

Freeze

The public traits (RaftLog, RaftTransport), the Message set and its framing,
and the WalLog record format are frozen as of v0.7 — no backward-incompatible
change before 2.0. Future additions stay compatible via the #[non_exhaustive]
enums and tagged encodings. Cross-platform verification of the persistent path
runs on the Linux / macOS / Windows CI matrix.

Breaking changes

None. This release is hardening, tests, and documentation; the public API is
unchanged from v0.6 and is now frozen.

Verification

Run on Windows x86_64, Rust stable; the same commands pass on Linux (WSL2 Ubuntu)
and via the CI matrix:

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. Test counts at this tag:

  • --all-features: 103 unit + 17 integration / property tests
    (safety.rs, replication.rs, recovery.rs, snapshot.rs, membership.rs,
    hardening.rs) + 52 doctests.

The hardening suite was additionally run at PROPTEST_CASES=8000 with no failures.
loom is not exercised: the core is a single-threaded, owned state machine with no
lock-free or shared-state path.

What's next

  • v0.8.0 → v0.9.x — Alpha / Beta → RC. Integrate against the first real
    consumers and fix what they surface (MINOR-compatible additions only; no
    breaking signatures), broaden testing, capture final benchmarks, and soak toward
    the 1.0 freeze.

Installation

[dependencies]
raft-io = "0.7"

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

MSRV: Rust 1.85 (edition 2024).

Documentation

Full diff: v0.6.0...v0.7.0.
Changelog: CHANGELOG.md.

Assets 2
Loading