Skip to main content

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::StandaloneEngine;
use tokio::sync::watch;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (_shutdown_tx, shutdown_rx) = watch::channel(());
    StandaloneEngine::run("./data", 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::StandaloneEngine;
pub use api::EmbeddedClient;
pub use node::Node;
pub use node::NodeBuilder;
pub use storage::FileStateMachine;
pub use storage::FileStorageEngine;
pub use storage::RocksDBStateMachine;
pub use storage::RocksDBStorageEngine;
pub use storage::RocksDBUnifiedEngine;

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§

ApplyEntry
A decoded Raft log entry ready for state machine application.
ApplyResult
Result of applying a single log entry to the state machine
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
MembershipSnapshot
A point-in-time snapshot of committed cluster membership.
ScanResult
Prefix scan result: matching entries + revision anchor for watch deduplication All (key, value) pairs returned by a prefix scan, plus the revision anchor.
WatchEvent
Watch event types and handles — available when the watch feature is enabled.
WatcherHandle
Watch event types and handles — available when the watch feature is enabled.

Enums§

ClientApiError
Unified client operations trait (put/get/delete/CAS/watch). Re-exported here so embedded-mode users don’t need a separate d-engine-client dependency.
Command
Decoded KV operation — the unit of work delivered to a StateMachine.
Error
Unified error type for all d-engine operations
ErrorCode
Error code discriminator returned by ClientApiError::code(). Use this to pattern-match error categories without inspecting message strings: e.code() == ErrorCode::NotLeader Client-facing error codes — transport-agnostic, mirrors proto ErrorCode.
StorageError
Storage-specific error type
WatchError
Watch event types and handles — available when the watch feature is enabled.
WatchEventType
Watch event types and handles — available when the watch feature is enabled.

Traits§

ClientApi
Unified client operations trait (put/get/delete/CAS/watch). Re-exported here so embedded-mode users don’t need a separate d-engine-client dependency. Unified key-value store interface.
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

Type Aliases§

ClientApiResult
Unified client operations trait (put/get/delete/CAS/watch). Re-exported here so embedded-mode users don’t need a separate d-engine-client dependency. Result type for KV operations
Result
Unified result type (equivalent to Result<T, Error>)