raftpp

A modern C++ implementation of the RAFT consensus algorithm.

• Batteries-included orchestration: Raftor provides a single-threaded event loop, ready-processing, and thread-safe proposal / read APIs out of the box.
• Production-grade persistence & networking: Built-in segmented WAL with CRC32C and a pluggable Cap'n Proto RPC transport layer.
• Extensively tested: Unit tests, data-driven tests, and continuous ASan / TSan coverage on both x64 and ARM64.

Features

• Core consensus — Full state machine with Follower, Candidate, PreCandidate, and Leader roles.
• Log management — RaftLog combines an in-memory unstable buffer with a pluggable Storage interface (MemoryStorage, WALStorage, or custom).
• Dynamic membership — Safe cluster configuration changes via joint consensus (ConfChanger, JointConf, MajorityConf).
• Linearizable reads — ReadOnly queue and read-index support for consistent read operations.
• High-level orchestration — Raftor manages the Raft lifecycle, ready processing, proposal tracking (callbacks, futures, sync variants), and snapshot flow.
• Write-Ahead Log — Segmented log files with CRC32C checksums, fast index lookup, and snapshot-based compaction.
• Pluggable RPC — Abstract Transport interface with a Cap'n Proto implementation (CapnpTransport).
• Modern C++ — C++17, nonstd::expected error handling (Result<T, E>), and doctest test framework.

Quick Start

Prerequisites

• CMake >= 3.28
• Ninja
• C++17 compiler (Clang or GCC)
• Task (optional, for convenience commands)

Build

Using Task:

task cmake    # configure
task build    # build tests
task test     # build & run all tests

Or with CMake directly:

cmake --preset=Debug -B build
cmake --build build
./build/tests/raftpp-tests
./build/tests/datadriven/data-driven-tests

Experimental Seastar Integration

raftpp builds and runs without Seastar by default. Optional Seastar build support is opt-in with RAFTPP_WITH_SEASTAR=ON, for example:

cmake --preset=Debug-Seastar -B build-seastar

When enabled, CMake expects an installed Seastar package discoverable via the normal package search path, such as CMAKE_PREFIX_PATH; Seastar is not fetched as part of the default build. The non-Seastar public API remains the compatibility baseline, and Seastar integration is experimental until runtime and transport support lands.

Minimal Example

#include "raftpp/raftor/raftor.h"

class MyStateMachine : public raftpp::raftor::StateMachine {
 public:
  raftpp::Result<raftpp::raftor::ApplyResult> Apply(
      const raftpp::Entry& entry) override {
    return raftpp::raftor::ApplyResult{.response = "ok"};
  }
  // ... TakeSnapshot / RestoreSnapshot
};

int main() {
  raftpp::raftor::RaftorConfig config;
  config.node_id = 1;
  config.listen_addr = "127.0.0.1:9001";
  config.data_dir = "./data";
  config.tick_interval = std::chrono::milliseconds(100);

  auto raftor = raftpp::raftor::Raftor::Create(
      config, std::make_unique<MyStateMachine>());
  if (!raftor) { return 1; }

  if (auto result = (*raftor)->Start(); !result) { return 1; }

  // Drive the event loop...
  for (int i = 0; i < 20; ++i) {
    (*raftor)->Poll(config.tick_interval);
    if ((*raftor)->GetStatus().role == raftpp::StateRole::Leader) {
      (*raftor)->Stop();
      return 0;
    }
  }
  return 1;
}

See examples/minimal_node/ for the complete runnable version.

Examples

Example	Description
examples/minimal_node/	Single-node bootstrap that elects itself leader.
examples/kvstore/	Distributed key-value store with an HTTP frontend and multi-peer Raft cluster.

Architecture

┌─────────────────────────────────────────┐
│  Application (StateMachine, Proposals)  │
├─────────────────────────────────────────┤
│  Raftor  (event loop, ready processor,  │
│           proposal tracker)             │
├─────────────────────────────────────────┤
│  Core Raft  (RawNode → Raft → RaftLog)  │
├─────────────────────────────────────────┤
│  WAL + RPC Transport                    │
└─────────────────────────────────────────┘

• Core (include/raftpp/core/) — Low-level consensus primitives: RawNode, Raft, RaftLog, Storage, ProgressTracker, ReadOnly, and configuration changers.
• Orchestration (raftor/) — Raftor ties everything together with a tick-driven event loop, Ready processing, and user-friendly Propose / ReadIndex APIs.
• I/O & Persistence (raftor/wal/, raftor/rpc/) — Durable segmented WAL and a pluggable RPC layer (Cap'n Proto built-in).

Testing

• Unit tests — build/tests/raftpp-tests (15+ test files, doctest-based).
• Data-driven tests — build/tests/datadriven/data-driven-tests (text-based DSL for quorum and confchange scenarios).
• Sanitizers — AddressSanitizer and ThreadSanitizer runs on every PR via GitHub Actions.
• Coverage — llvm-cov reports uploaded to Codecov.

Documentation

Full documentation, guides, and API references are available at:

https://raftpp.cc

License

MIT License. See LICENSE.