Skip to content

Latest commit

 

History

History
 
 

examples

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

OpenRaft Examples

This directory contains example applications demonstrating different implementation approaches for OpenRaft components.

Complete Applications

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.

Component Overview

  • 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

Focused Examples

  • raft-kv-rkyv — Application-owned, archive-backed Entry/Payload types. 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.

Component Implementations

Storage Implementations

  • 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.

Backward Compatibility (since 0.10)

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 Implementations

  • network-v2 - HTTP-based RaftNetworkV2 interface using reqwest crate
  • network-v1 - HTTP-based RaftNetwork interface V1 using reqwest crate

Snapshot Transfer

  • dir-transfer - Streams a directory of immutable files as frames over any ordered transport; raft-kv-rocksdb ships its RocksDB checkpoint snapshots with it

Application HTTP

  • app-http - JSON HTTP client and server used by the KV examples

Utilities

  • types-kv - Shared KV request/response types for example crates
  • utils - Shared type declarations and utilities