feat: merge develop → main (v0.2.3) — CAS, unified client API, Raft correctness & performance

.github/workflows/commit-message-check.yml

@@ -8,6 +8,7 @@ on:
 
 jobs:
   validate-commits:
+    if: github.head_ref != 'develop'
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/dependency-audit.yml

@@ -12,6 +12,8 @@ on:
 jobs:
   audit:
     runs-on: ubuntu-latest
+    env:
+      RUSTUP_TOOLCHAIN: stable
     steps:
       - uses: actions/checkout@v4
 

CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [Unreleased v0.2.3]
+
+### Added
+
+- **CompareAndSwap (CAS) Operation** (#258): Atomic compare-and-swap primitive for distributed coordination
+  - Use cases: Distributed locks, leader election, optimistic updates
+  - API: `client.compare_and_swap(key, expected_value, new_value)`
+  - Performance: No additional protocol round-trips; latency is comparable to regular writes in most workloads
+
+### Changed
+
+- **Unified Client API** (#258): Merged KV and cluster operations into single `ClientApi` trait
+  - **Breaking**: `KvClient` → `ClientApi`, `KvError` → `ClientApiError`
+  - Simplifies developer experience (single trait for all operations)
+  - Both `GrpcClient` and `EmbeddedClient` implement unified interface
+
+- **WriteResult Message** (#258): Replaced `bool succeeded` with `WriteResult` message
+  - Improves API extensibility (reserved fields for version tracking)
+  - Better type safety for future features
+
+- **Simplified Error Handling** (#258): Removed `LocalClientError`, use `ClientApiError` directly
+  - Unified error type across embedded and standalone clients
+  - Less boilerplate (no intermediate error type conversion)
+  - Clearer error semantics for users
+
+- **Drain-based batch architecture** (#266): Replaced timeout-driven batching with drain-on-arrival pattern
+  - Low load: near-zero wait (eliminated ~1ms timeout penalty)
+  - High load: natural batching, significant throughput improvement
+  - Embedded: linearizable read +92%, lease/eventual read +62% vs v0.2.2
+  - See [bench report v0.2.3](benches/reports/v0.2.3/bench_report_v0.2.3.md)
+
+- **Default PersistenceStrategy changed: `MemFirst` → `DiskFirst`** (#268): Raft protocol compliance
+  - **Breaking**: Add `persistence_strategy = "MemFirst"` to `[raft.persistence]` config to restore prior behavior
+
+### Migration Notes
+
+- Replace `KvClient` with `ClientApi` in trait bounds
+- Replace `KvError` with `ClientApiError` in error handling
+- Update imports: `use d_engine::client::ClientApi;`
+
+---
+
 ## [v0.2.2] - 2026-01-12 [✅ Released]
 
 ### 🎯 Key Improvements
@@ -71,7 +113,7 @@ while let Some(event) = watcher.next().await {
 
 **Performance**: Lock-free, <0.1ms notification latency
 
-#### StandaloneServer - One-Line Deployment
+#### StandaloneEngine - One-Line Deployment
 
 **Use Case**: Independent server process (production deployment)  
 **API**: `run(shutdown_rx)` uses env config, `run_with(config_path, shutdown_rx)` uses explicit config  
@@ -81,9 +123,9 @@ while let Some(event) = watcher.next().await {
 
 **Use Case**: Embed d-engine in your Rust application  
 **API**: `start()` uses env config, `start_with(config_path)` uses explicit config, `start_custom(...)` for advanced usage  
-**Benefit**: Zero gRPC overhead via LocalKvClient (<0.1ms latency)
+**Benefit**: Zero gRPC overhead via EmbeddedClient (<0.1ms latency)
 
-#### LocalKvClient - Zero-Overhead Embedded Access
+#### EmbeddedClient - Zero-Overhead Embedded Access
 
 **When**: Your app and d-engine in same process  
 **Benefit**: Skip gRPC serialization, direct memory access (<0.1ms)  
@@ -95,7 +137,7 @@ while let Some(event) = watcher.next().await {
 
 - `examples/quick-start/` - 5-minute single-node setup
 - `examples/single-node-expansion/` - Dynamic 1→3 node scaling
-- `examples/service-discovery-embedded/` - LocalKvClient zero-overhead access
+- `examples/service-discovery-embedded/` - EmbeddedClient zero-overhead access
 - `examples/service-discovery-standalone/` - Watch API pattern
 
 ---

CONTRIBUTING.md

@@ -75,7 +75,17 @@ make test  # Run all tests with nextest (fast, parallel)
 
 - Features: `feature/<ticket-number>_<short-description>`
 - Bug fixes: `bug/<ticket-number>_<short-description>`
-- Target `develop` branch for all PRs
+- Target `main` branch for all PRs
+
+### Keeping Your PR Up-to-Date
+
+If `main` has moved forward since you created your branch, rebase before requesting review:
+
+```bash
+git fetch upstream
+git rebase upstream/main
+git push --force-with-lease
+```
 
 ### Code Quality
 

Cargo.toml

@@ -31,6 +31,7 @@ authors = ["Joshua Chi <joshokn@gmail.com>"]
 homepage = "https://github.com/deventlab/d-engine"
 repository = "https://github.com/deventlab/d-engine"
 license = "MIT OR Apache-2.0"
+rust-version = "1.88"
 
 [workspace.dependencies]
 d-engine-proto = { path = "./d-engine-proto", version = "0.2.2" }

README.md

@@ -27,7 +27,7 @@ and pluggable storage backends. Start with one node, scale to a cluster when nee
 ### New in v0.2 🎉
 
 - **EmbeddedEngine**: Single-node start, scale to 3-node cluster when needed
-- **LocalKvClient**: Zero-overhead in-process access (<0.1ms latency)
+- **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

benches/embedded-bench/Makefile

@@ -202,6 +202,7 @@ all-tests: build
 	$(BENCH_BIN) \
 		--mode local \
 		--batch \
+		--clients 1000 \
 		--key-size $(KEY_SIZE) \
 		--value-size $(VALUE_SIZE) \
 		$(SEQUENTIAL) \

benches/embedded-bench/README.md

@@ -32,7 +32,7 @@ make all-tests
 
 `embedded-bench` tests d-engine in embedded mode with three operation modes:
 
-- **`local`**: Direct in-process benchmark using `LocalKvClient` (zero-copy, baseline performance)
+- **`local`**: Direct in-process benchmark using `EmbeddedClient` (zero-copy, baseline performance)
 - **`server`**: HTTP server exposing KV operations via REST API
 - **`client`**: HTTP client for testing with load balancer (e.g., HAProxy)
 
@@ -60,7 +60,7 @@ This design mirrors how `standalone-bench` (Standalone) distributes requests via
 
 ### Test A: Embedded Pure Mode (Baseline)
 
-Direct in-process benchmark measuring `LocalKvClient` performance without network overhead.
+Direct in-process benchmark measuring `EmbeddedClient` performance without network overhead.
 
 ```
 
@@ -72,7 +72,7 @@ Direct in-process benchmark measuring `LocalKvClient` performance without networ
 │ │ embedded- │ │ embedded- │ │ embedded- │ │
 │ │ bench n1 │ │ bench n2 │ │ bench n3 │ │
 │ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
-│ │ LocalKvClient│ │ LocalKvClient│ │ LocalKvClient│ │
+│ │EmbeddedClient│ │EmbeddedClient│ │EmbeddedClient│ │
 │ │ (internal │ │ (internal │ │ (internal │ │
 │ │ benchmark) │ │ benchmark) │ │ benchmark) │ │
 │ └──────────────┘ └──────────────┘ └──────────────┘ │
@@ -279,7 +279,7 @@ Expected performance comparison chain:
 
 ```
 Standalone < Embedded+HAProxy < Embedded Pure Mode
-   (gRPC)    (HTTP+HAProxy)      (LocalKvClient)
+   (gRPC)    (HTTP+HAProxy)      (EmbeddedClient)
 ```
 
 | Mode               | Overhead                     | Use Case                    |

benches/embedded-bench/config/n1.toml

@@ -9,8 +9,13 @@ initial_cluster = [
 db_root_dir = "./data/n1"
 log_dir = "./logs"
 
-[raft]
-general_raft_timeout_duration_in_ms = 10000  # 10 sec
+[raft.batching]
+# Maximum number of commands to accumulate in a single batch during drain operations
+max_batch_size = 500
+
+[raft.metrics]
+enable_backpressure = false
+enable_batch = false
 
 [raft.snapshot]
 enable = false

benches/embedded-bench/config/n2.toml

@@ -9,9 +9,13 @@ initial_cluster = [
 db_root_dir = "./data/n2"
 log_dir = "./logs"
 
+[raft.batching]
+# Maximum number of commands to accumulate in a single batch during drain operations
+max_batch_size = 500
 
-[raft]
-general_raft_timeout_duration_in_ms = 10000  # 10 sec
+[raft.metrics]
+enable_backpressure = false
+enable_batch = false
 
 [raft.snapshot]
 enable = false

benches/embedded-bench/config/n3.toml

@@ -9,9 +9,13 @@ initial_cluster = [
 db_root_dir = "./data/n3"
 log_dir = "./logs"
 
+[raft.batching]
+# Maximum number of commands to accumulate in a single batch during drain operations
+max_batch_size = 500
 
-[raft]
-general_raft_timeout_duration_in_ms = 10000  # 10 sec
+[raft.metrics]
+enable_backpressure = false
+enable_batch = false
 
 [raft.snapshot]
 enable = false

benches/embedded-bench/src/main.rs

@@ -463,6 +463,9 @@ async fn run_local_benchmark(cli: Cli) {
     println!("Leader elected: {}", leader_info.leader_id);
     println!("Node ID: {}", engine.node_id());
 
+    // Signal file used to coordinate follower auto-shutdown in batch mode
+    let done_signal_path = "/tmp/embedded-bench-done";
+
     // Setup Ctrl+C handler
     let (shutdown_tx, mut shutdown_rx) = tokio::sync::watch::channel(());
 
@@ -474,14 +477,31 @@ async fn run_local_benchmark(cli: Cli) {
 
     // Check if running in batch mode
     if cli.batch {
+        // Clean up any leftover signal file from a previous run
+        let _ = std::fs::remove_file(done_signal_path);
+
         if engine.is_leader() {
             run_batch_tests(&engine, &cli).await;
+            // Signal followers to auto-shutdown
+            if let Err(e) = std::fs::write(done_signal_path, "done") {
+                eprintln!("Failed to write done signal: {e}");
+            }
         } else {
             println!(
                 "This node is Follower, keeping cluster membership alive during batch tests..."
             );
-            println!("Press Ctrl+C to shutdown.");
-            let _ = shutdown_rx.changed().await;
+            println!("Will auto-shutdown when leader completes benchmarks.");
+            loop {
+                tokio::select! {
+                    _ = shutdown_rx.changed() => break,
+                    _ = tokio::time::sleep(Duration::from_secs(1)) => {
+                        if std::path::Path::new(done_signal_path).exists() {
+                            println!("Benchmark completed, shutting down follower.");
+                            break;
+                        }
+                    }
+                }
+            }
         }
     } else {
         // Single test mode (original behavior)