Crate d_engine_server

Crate d_engine_server 

Source
Expand description

§d-engine-server

Complete Raft server with gRPC and storage - batteries included

§When to use this crate directly

  • ✅ Embedding server in a larger Rust application
  • ✅ Need programmatic access to server APIs
  • ✅ Building custom tooling around d-engine
  • ✅ Already have your own client implementation

§When to use d-engine instead

Most users should use d-engine:

[dependencies]
d-engine = { version = "0.2", features = ["server"] }

It re-exports this crate plus optional client libraries with simpler dependency management.

§Quick Start

Embedded Mode (zero-overhead local client):

ⓘ
use d_engine_server::EmbeddedEngine;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = EmbeddedEngine::start_with("config.toml").await?;
    engine.wait_ready(Duration::from_secs(5)).await?;

    let client = engine.client();
    client.put(b"key".to_vec(), b"value".to_vec()).await?;

    engine.stop().await?;
    Ok(())
}

Standalone Mode (independent server):

ⓘ
use d_engine_server::StandaloneServer;
use tokio::sync::watch;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    std::env::set_var("CONFIG_PATH", "config.toml");
    let (_shutdown_tx, shutdown_rx) = watch::channel(());
    StandaloneServer::run(shutdown_rx).await?;
    Ok(())
}

§Features

This crate provides:

  • gRPC Server - Production-ready Raft RPC implementation
  • Storage Backends - File-based and RocksDB storage
  • Cluster Orchestration - Node lifecycle and membership management
  • Snapshot Coordination - Automatic log compaction
  • Watch API - Real-time state change notifications

§Custom Storage

Implement the StateMachine and StorageEngine traits:

ⓘ
use d_engine_server::{StateMachine, StorageEngine};

struct MyStateMachine;
impl StateMachine for MyStateMachine {
    // Apply committed entries to your application state
}

struct MyStorageEngine;
impl StorageEngine for MyStorageEngine {
    // Persist Raft logs and metadata
}

§Documentation

For comprehensive guides:

Re-exports§

pub use api::EmbeddedEngine;
pub use api::StandaloneServer;
pub use node::LocalClientError;
pub use node::LocalKvClient;
pub use node::Node;
pub use node::NodeBuilder;
pub use storage::FileStateMachine;
pub use storage::FileStorageEngine;
pub use storage::RocksDBStateMachine;
pub use storage::RocksDBStorageEngine;

Modules§

api
Public API layer for different deployment modes
client
Client protocol types
common
Common Raft protocol types
node
Node lifecycle management
server_storage
Server storage protocol types
storage
Storage layer implementations

Structs§

HardState
Hard state (Raft persistent state: term, voted_for, log)
LeaderInfo
Leader election information Used at: Application layer (internal Raft protocol notifications) Purpose: Notify applications about leader changes via watch channel Fields: Minimal - only what Raft protocol needs

Enums§

Error
Unified error type for all d-engine operations
ProstError
Protocol buffer error type Wrapper for prost encoding/decoding errors
SnapshotError
Snapshot operation error type
StorageError
Storage-specific error type

Traits§

LogStore
Log storage trait
MetaStore
Metadata storage trait Metadata storage operations
StateMachine
Storage trait for implementing custom storage backends
StorageEngine
Storage trait for implementing custom storage backends