openraft_surrealkv/
lib.rs

1//! OpenRaft + SurrealKV distributed consensus KV storage.
2//!
3//! # Overview
4//!
5//! Build a production-oriented distributed KV system by combining:
6//! - **OpenRaft 0.10.0-alpha.15** (default) or **openraft-legacy 0.10.0-alpha.15** for consensus
7//! - **SurrealKV 0.20+** as the LSM-based storage engine
8//!
9//! # Architecture
10//!
11//! Organize the system into modular layers:
12//! - **Types** (`types.rs`): OpenRaft TypeConfig and KV operation types
13//! - **Storage** (`storage.rs`): unified RaftLogStorage + RaftStateMachine implementation
14//! - **State** (`state.rs`): persistent metadata management
15//! - **Snapshot** (`snapshot.rs`): snapshot build/install pipeline
16//! - **Network** (`network.rs`): tonic gRPC transport for Raft RPCs
17//! - **Merge** (`merge.rs`): hybrid delta-merge strategy
18//!
19//! # Storage Layout
20//!
21//! All data is persisted in a single SurrealKV engine with organized key prefixes:
22//! ```text
23//! raft_log:{term}:{index}      → Log entries (postcard-serialized)
24//! raft_vote                     → Voting state (immediate persistence)
25//! raft_applied                  → Applied log position
26//! raft_meta:*                   → Raft metadata
27//! raft_snapshot_meta            → Snapshot chain state
28//! app_data:*                    → Application state machine data
29//! ```
30//!
31//! # Quick Start
32//!
33//! ```ignore
34//! use openraft_surrealkv::storage::SurrealStorage;
35//! use openraft_surrealkv::types::{RaftTypeConfig, NodeId};
36//! use std::sync::Arc;
37//! use surrealkv::Engine;
38//!
39//! #[tokio::main]
40//! async fn main() {
41//!     // Initialize SurrealKV engine
42//!     let engine = Arc::new(Engine::new("./data").unwrap());
43//!
44//!     // Create unified storage
45//!     let storage = SurrealStorage::new(engine).await.unwrap();
46//!
47//!     // Ready to use with OpenRaft
48//! }
49//! ```
50
51pub mod error;
52pub mod merge;
53pub mod metrics;
54pub mod network;
55pub mod raft_adapter;
56pub mod snapshot;
57pub mod state;
58pub mod storage;
59mod storage_raft_impl;
60pub mod types;
61
62pub mod proto;
63
64// HTTP and runtime-facing modules.
65pub mod api;
66pub mod app;
67pub mod config;
68pub mod shutdown;
69
70// Re-export commonly used types.
71pub use error::{RaftError, Result};
72pub use raft_adapter::RaftConfig;
73pub use types::{
74    DeltaEntry, DeltaMetadata, KVRequest, KVResponse, NodeId, RaftTypeConfig, SnapshotData,
75    SnapshotFormat,
76};
77
78// Re-export runtime entry points.
79pub use app::RaftNode;
80pub use config::Config;
81pub use shutdown::ShutdownSignal;
82
83/// Expose crate version from Cargo metadata.
84pub const VERSION: &str = env!("CARGO_PKG_VERSION");
openraft_surrealkv/lib.rs

openraft_surrealkv/
lib.rs
