This directory contains example applications demonstrating different implementation approaches for OpenRaft components.
Start with raft-kv-memstore, the canonical example application: the getting-started guide follows it step by step. Every other row in the table below is that same application with one component swapped — storage, network interface, transport, or runtime.
- Log: LogStore implementation for storing raft logs
- State Machine: StateMachine implementation for application state
- RaftNetwork Impl: Transport protocol and client library used
- RaftNetwork: Interface version (RaftNetwork vs RaftNetworkV2)
- Client: HTTP/gRPC client library for application requests
- Server: HTTP server implementation for handling incoming requests
- Special Features: Unique characteristics of each example
| Example | Log | State Machine | RaftNetwork Impl | RaftNetwork | Client | Server | Special Features |
|---|---|---|---|---|---|---|---|
| raft-kv-memstore | log-mem | sm-mem | HTTP/reqwest(network-v2) | RaftNetworkV2 | app-http | app-http | Canonical example — start here |
| raft-kv-log-wal-sm-mem | log-wal | sm-mem | HTTP/reqwest(network-v2) | RaftNetworkV2 | app-http | app-http | Persistent WAL with state rebuilt from retained logs |
| raft-kv-rocksdb | log-rocks | sm-rocks | HTTP/reqwest(network-v2) + dir-transfer snapshots | RaftNetworkV2 | app-http | app-http | Persistent storage; snapshots are RocksDB checkpoints streamed as directories |
| raft-kv-memstore-network-v1 | log-mem | sm-mem | HTTP/reqwest(network-v1) | RaftNetwork | app-http | app-http | Legacy V1 network + chunked snapshot replication |
| multi-raft-kv | log-mem | sm-mem | HTTP/channel | GroupRouter | channel | in-memory | Multi-Raft groups |
| raft-kv-memstore-grpc | log-mem | in-memory | gRPC/tonic | RaftNetworkV2 sub-traits | tonic | tonic | gRPC transport |
| raft-kv-memstore-single-threaded | in-memory | in-memory | in-process channel | RaftNetworkV2 | channel | in-memory | Single-threaded runtime |
| raft-kv-memstore-opendal-snapshot-data | log-mem | in-memory+OpenDAL | in-process channel | RaftNetworkV2 | channel | in-memory | OpenDAL snapshot storage |
| raft-kv-memstore-weighted-membership | log-mem | sm-mem | HTTP/reqwest(network-v2) | RaftNetworkV2 | app-http | app-http | WeightedMembership; /init and /change-membership take weights |
- raft-kv-rkyv — Application-owned, archive-backed
Entry/Payloadtypes. A three-voter cluster sends rkyv payload bytes through a versioned in-process transport and reads archived data directly in the state machine, without rkyv derives on OpenRaft types. Optional persistent logs demonstrate atomic image publication, restart/replay, and recovery tests; applied state and snapshots remain volatile. The example documents durability boundaries and remaining copies.
- log-mem - In-memory Raft Log Store using
std::collections::BTreeMap - log-rocks - RocksDB-based persistent Raft Log Store
- log-fjall - Persistent Raft Log Store on fjall, an LSM-tree key-value store in Rust
- log-wal - Write-ahead-log Raft Log Store built on the raft-log crate
- sm-mem - In-memory KV State Machine implementation
- sm-rocks - RocksDB-based persistent state machine
- sm-fjall - fjall-based persistent state machine
Performance note: Raft log workloads are mostly append-only. General-purpose LSM stores such as RocksDB and fjall write every entry twice, to a journal and later to a table file, and reclaim purged entries through tombstones and compaction, so log-rocks and log-fjall are durable examples rather than optimal-performance log stores. log-wal shows the other approach: a log-shaped storage engine that appends records to chunk files and deletes a whole chunk once every entry in it is purged. A state machine, which reads and overwrites keys in any order, suits an LSM store well; Openraft keeps the two independent, so sm-fjall or sm-rocks can be paired with any log store.
The following symbolic links are provided for backward compatibility:
- mem-log → log-mem (renamed in 0.10)
- memstore → mem-log → log-mem (renamed in 0.9)
- rocksstore → sm-rocks (renamed in 0.10)
- network-v2 - HTTP-based RaftNetworkV2 interface using
reqwestcrate - network-v1 - HTTP-based RaftNetwork interface V1 using
reqwestcrate
- dir-transfer - Streams a directory of immutable files as frames over any ordered transport; raft-kv-rocksdb ships its RocksDB checkpoint snapshots with it
- app-http - JSON HTTP client and server used by the KV examples