Crate openraft_surrealkv 

OpenRaft + SurrealKV distributed consensus KV storage.

Overview

Build a production-oriented distributed KV system by combining:

• OpenRaft 0.10.0-alpha.15 (default) or openraft-legacy 0.10.0-alpha.15 for consensus
• SurrealKV 0.20+ as the LSM-based storage engine

Architecture

Organize the system into modular layers:

• Types (types.rs): OpenRaft TypeConfig and KV operation types
• Storage (storage.rs): unified RaftLogStorage + RaftStateMachine implementation
• State (state.rs): persistent metadata management
• Snapshot (snapshot.rs): snapshot build/install pipeline
• Network (network.rs): tonic gRPC transport for Raft RPCs
• Merge (merge.rs): hybrid delta-merge strategy

Storage Layout

All data is persisted in a single SurrealKV engine with organized key prefixes:

raft_log:{term}:{index}      → Log entries (postcard-serialized)
raft_vote                     → Voting state (immediate persistence)
raft_applied                  → Applied log position
raft_meta:*                   → Raft metadata
raft_snapshot_meta            → Snapshot chain state
app_data:*                    → Application state machine data

Quick Start

use openraft_surrealkv::storage::SurrealStorage;
use openraft_surrealkv::types::{RaftTypeConfig, NodeId};
use std::sync::Arc;
use surrealkv::Engine;

#[tokio::main]
async fn main() {
    // Initialize SurrealKV engine
    let engine = Arc::new(Engine::new("./data").unwrap());

    // Create unified storage
    let storage = SurrealStorage::new(engine).await.unwrap();

    // Ready to use with OpenRaft
}

Re-exports

pub use error::RaftError;

pub use error::Result;

pub use raft_adapter::RaftConfig;

pub use types::DeltaEntry;

pub use types::DeltaMetadata;

pub use types::KVRequest;

pub use types::KVResponse;

pub use types::NodeId;

pub use types::RaftTypeConfig;

pub use types::SnapshotData;

pub use types::SnapshotFormat;

pub use app::RaftNode;

pub use config::Config;

pub use shutdown::ShutdownSignal;

Modules

api

HTTP REST API module.

app

Raft Node management and initialization.

config

error

Unified error types for the Raft system.

merge

Hybrid snapshot merge strategy (Phase 4).

metrics

Prometheus metrics export module (Phase 5.3 + existing Phase 4 capabilities)

network

Tonic gRPC network layer and Raft RPC implementation.

proto

Protobuf definitions and generated code for Raft communication.

raft_adapter

OpenRaft version abstraction layer

shutdown

Graceful shutdown signal management

snapshot

Snapshot modules for checkpoint, delta, compression, and restore workflows.

state

Persistent metadata state management for Raft.

storage

SurrealKV-based Raft storage layer - OpenRaft 0.10.0-alpha.15 Compatible Implementation

types

Core OpenRaft type definitions and configuration.

Constants

VERSION

Expose crate version from Cargo metadata.