d-engine 🚀

d-engine is a lightweight, embeddable distributed coordination engine for Rust — strong-consistency KV, watch streams, and leader election, running inside your process.

Built with a simple vision: make distributed coordination accessible - cheap to run, simple to use. Built on a core philosophy: choose simple architectures over complex ones.

d-engine's Raft core uses a single-threaded event loop to guarantee strong consistency and strict ordering while keeping the codebase clean and performant. Production-ready Raft implementation with flexible read consistency (Linearizable/Lease-Based/Eventual) and pluggable storage backends. Start with one node, scale to a cluster when needed.

New in v0.2.4 🎉

• Async IO Architecture: Raft event loop is fully non-blocking — WAL writes, state machine apply, and replication all run off the hot path. AppendEntries uses a persistent bidirectional stream per peer; replication is pipelined across followers.
• Cluster Membership Streaming: EmbeddedEngine::watch_membership() / GrpcClient::watch_membership() — subscribe to real-time membership changes in both embedded and standalone modes
• Simpler Startup: EmbeddedEngine::start(data_dir) and StandaloneEngine::run(data_dir, shutdown_rx) — no config file required for common cases
• Jepsen Validated: 5 workloads + 6-hour soak test under combined kill/partition/pause faults — see Correctness Guarantees

Features

• Single-Node Start: Begin with one node, scale to a 3-node cluster with zero downtime
• EmbeddedEngine: Zero-overhead in-process access (<0.1ms latency)
• Strong Consistency: Full Raft protocol — linearizable writes, configurable read consistency
• Flexible Read Consistency: Three-tier model (Linearizable/Lease-Based/Eventual) per request
• Watch API: Real-time key change notifications for configuration updates, state changes, and cluster events
• TTL: Automatic key expiration for session management and short-lived entries
• Pluggable Storage: Custom backends supported (RocksDB default; Sled, Raw File, or your own)
• Modular: Feature flags (client/server) — depend only on what you need

Quick Start (Embedded Mode)

d-engine = "0.2"

use d_engine::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() {
    let engine = EmbeddedEngine::start("./data").await.unwrap();
    engine.wait_ready(Duration::from_secs(5)).await.unwrap();

    let client = engine.client();
    client.put(b"hello".to_vec(), b"world".to_vec()).await.unwrap();
    let value = client.get_linearizable(b"hello".to_vec()).await.unwrap();

    println!("Retrieved: {}", String::from_utf8_lossy(&value.unwrap()));
    engine.stop().await.unwrap();
}

→ Full example: examples/quick-start-embedded

Integration Modes

Embedded Mode — In-Process

d-engine = "0.2"

Use when: Building Rust applications that need distributed coordination
Why: Zero-overhead (<0.1ms), single binary, zero network cost

Performance: AWS EC2 3-node cluster — 110K writes/sec, 327K linearizable reads/sec, sub-millisecond latency. See benches/reports/v0.2.4/ for details.

→ Examples:

• Quick Start Embedded — Minimal setup
• Service Discovery Embedded — Watch API

Standalone Mode — Separate Service

d-engine = { version = "0.2", features = ["client"], default-features = false }

Use when: Application and d-engine run as separate processes
Why: Language-agnostic (Go/Python/Java/Rust), independent scaling, easier operations

Performance: 59K writes/sec, 77K linearizable reads/sec via gRPC. For maximum throughput, embedded mode is 1.9× faster on writes and 4.2× on reads. See benches/reports/v0.2.4/.

→ Example: Quick Start Standalone (Go client)

Custom Storage Backends

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

Implement the StorageEngine and StateMachine traits for custom backends:

• Storage Engine Guide
• State Machine Guide
• Sled Storage Example

Performance

d-engine v0.2.4 vs etcd

d-engine v0.2.4 vs v0.2.3

open benches/reports/

Maintainer Philosophy

d-engine has a focused roadmap maintained by a single author. We welcome bug fixes unconditionally. For feature PRs, please open an issue first — new features are evaluated against roadmap fit, not just code quality. Breaking changes before v1.0 are documented in MIGRATION_GUIDE.md.

Contributing

d-engine follows the 20/80 rule — solve real production problems, not experiments. Read CONTRIBUTING.md and open an issue before feature PRs. Bug fixes are always welcome.

Prerequisites: Rust 1.89+, Tokio runtime, Protobuf compiler

# Run all tests (fast, parallel with nextest)
make test

Follow Rust community standards (rustfmt, clippy). Write unit tests for all new features.

FAQ

Why 3 nodes for HA?
Raft requires majority quorum (N/2 + 1). A 3-node cluster tolerates 1 failure.

Can I start with 1 node?
Yes. Scale to 3 nodes later with zero downtime (see examples/single-node-expansion/).

How do I customize storage?
Implement the StorageEngine and StateMachine traits (see Custom Storage Backends above).

Production-ready?
Core Raft engine is production-grade (1000+ tests, Jepsen validated). API is stabilizing toward v1.0. Pre-1.0 versions may introduce breaking changes (documented in MIGRATION_GUIDE.md).

Migrating from etcd?
d-engine is not a drop-in replacement. See API compatibility and migration gaps before porting — lease keepalive, multi-key transactions, and auth are not supported; built-in distributed lock requires DIY via CAS.

Supported Platforms

• Linux: x86_64, aarch64
• macOS: x86_64, aarch64

License

Licensed under MIT or Apache 2.0, at your option.