# d-engine 🚀
[](https://crates.io/crates/d-engine)
[](https://docs.rs/d-engine)
[](https://codecov.io/gh/deventlab/d-engine)
[](https://github.com/deventlab/d-engine/actions/workflows/ci.yml)
[](https://deepwiki.com/deventlab/d-engine)
**d-engine** is a lightweight distributed coordination engine written in Rust,
designed for embedding into applications that need strong consistency—the consensus
layer for building reliable distributed systems.
**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.
---
## Features
### New in v0.2.3 🎉
- **CompareAndSwap (CAS)**: Atomic compare-and-swap for distributed locks, leader election, optimistic updates
- **Drain-based Batching**: Linearizable read +92%, lease/eventual read +62% vs v0.2.2 (embedded mode)
- **Client Auto-Recovery**: `Client::refresh()` rediscovers cluster after leader failover
- **Unified Client API**: Single `ClientApi` trait for KV and cluster operations (replaces `KvClient`)
### Core Features (v0.2+)
- **EmbeddedEngine**: Single-node start, scale to 3-node cluster when needed
- **EmbeddedClient**: Zero-overhead in-process access (<0.1ms latency)
- **Watch API**: Real-time key change notifications (config updates, service discovery)
- **TTL/Lease**: Automatic key expiration for distributed locks and session management
- **Modular Workspace**: Feature flags (`client`/`server`) - depend only on what you need
### Core Capabilities
- **Strong Consistency**: Full Raft protocol implementation for distributed consensus
- **Flexible Read Consistency**: Three-tier model (Linearizable/Lease-Based/Eventual)
- **Single-Node Start**: Begin with one node, expand to 3-node cluster when needed (zero downtime)
- **Tunable Persistence**: DiskFirst for durability or MemFirst for lower latency
- **Pluggable Storage**: Custom backends supported (RocksDB, Sled, Raw File)
---
## Quick Start (Embedded Mode)
Add d-engine to your `Cargo.toml`:
```toml
d-engine = "0.2"
```
Example code:
```rust
use d_engine::prelude::*;
use std::time::Duration;
#[tokio::main]
async fn main() {
let engine = EmbeddedEngine::start().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();
}
```
> **Note**: Release builds require explicit `db_root_dir` configuration. Set `CONFIG_PATH` env or use `EmbeddedEngine::with_config(...)`. See [Quick Start Guide](https://docs.rs/d-engine/latest/d_engine/docs/quick_start_5min/index.html).
**→ Full example:** [examples/quick-start-embedded](https://github.com/deventlab/d-engine/tree/main/examples/quick-start-embedded)
---
## Integration Modes
### Embedded Mode - In-Process Deployment
```toml
d-engine = "0.2"
```
**Use when**: Building Rust applications that need distributed coordination
**Why**: Zero-overhead (<0.1ms), single binary, zero network cost
> **Performance note**: Embedded mode on AWS EC2 3-node cluster achieves **64K writes/sec** and **181K linearizable reads/sec** under high concurrency, with sub-millisecond latency. See [benches/reports/v0.2.3/](https://github.com/deventlab/d-engine/tree/main/benches/reports/v0.2.3) for detailed benchmarks.
**→ Examples:**
- [Quick Start Embedded](https://github.com/deventlab/d-engine/tree/main/examples/quick-start-embedded) - Minimal setup
- [Service Discovery Embedded](https://github.com/deventlab/d-engine/tree/main/examples/service-discovery-embedded) - Watch API with sub-millisecond latency
---
### Standalone Mode - Separate Service Deployment
```toml
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 note**: Standalone mode achieves 36K writes/sec and 51K linearizable reads/sec via gRPC, suitable for multi-language environments. For maximum performance, use embedded mode (1.8x faster writes, 3.5x faster reads). See [benches/reports/v0.2.3/](https://github.com/deventlab/d-engine/tree/main/benches/reports/v0.2.3) for benchmarks.
**Note**: Rust apps can use both modes - embedded for performance, standalone for operational flexibility
**→ Example:** [Quick Start Standalone (Go client)](https://github.com/deventlab/d-engine/tree/main/examples/quick-start-standalone)
---
## Advanced: Custom Storage Backends
For specific storage requirements (Sled, memory-only, cloud storage):
```toml
d-engine = { version = "0.2", features = ["server"], default-features = false }
```
Implement custom storage engines and state machines by implementing the respective traits:
- **Custom Storage Engines**: [Implementation Guide](https://docs.rs/d-engine/latest/d_engine/docs/server_guide/index.html#implementing-custom-storage-engines)
- **Custom State Machines**: [Implementation Guide](https://docs.rs/d-engine/latest/d_engine/docs/server_guide/index.html#implementing-custom-state-machines)
- **Example**: [Sled Storage Backend](https://github.com/deventlab/d-engine/tree/main/examples/sled-cluster)
---
## Core Concepts
### Data Flow
```mermaid
sequenceDiagram
participant Client
participant Leader
participant Raft_Log as Raft Log
participant Followers
participant State_Machine as State Machine
Client->>Leader: Propose("SET key=value")
Leader->>Raft_Log: Append Entry (Uncommitted)
Leader->>Followers: Replicate via AppendEntries RPC
Followers-->>Leader: Acknowledge Receipt
Leader->>Raft_Log: Mark Entry Committed
Leader->>State_Machine: Apply Committed Entry
State_Machine-->>Client: Return Result
```
---
## Performance Comparison (d-engine v0.2.3 vs etcd)
### View Benchmarks Detailed Reports
```bash
open benches/reports/
```
---
## Maintainer Philosophy
d-engine is maintained by a single author with a clear vision.
We value quality over quantity:
- **PRs are not guaranteed to be merged** - even good code may be declined
if it conflicts with roadmap priorities
- **Response time varies** - active development takes precedence over PR reviews
- **Breaking changes are OK pre-1.0** - we prioritize getting it right over
backward compatibility
This approach keeps d-engine focused and maintainable.
---
## Contribution Guide
d-engine follows the 20/80 rule - solve real production problems, not experiments.
Read [Contributing Guide](https://github.com/deventlab/d-engine/blob/main/CONTRIBUTING.md) and open an issue before feature PRs.
Bug fixes are always welcome.
### Prerequisites
- Rust 1.88+
- Tokio runtime
- Protobuf compiler
### Development Workflow
```bash
# Run all tests (fast, parallel with nextest)
make test
```
---
## Code Style
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). 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 `StorageEngine` and `StateMachine` traits (see Custom Storage Implementations section).
**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](https://github.com/deventlab/d-engine/blob/main/MIGRATION_GUIDE.md)).
## Supported Platforms
- Linux: x86_64, aarch64
- macOS: x86_64, aarch64
## License
d-engine is licensed under the terms of the [MIT License](https://en.wikipedia.org/wiki/MIT_License#License_terms)
or the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0), at your choosing.