Struct EmbeddedClient 

pub struct EmbeddedClient { /* private fields */ }

Zero-overhead KV client for embedded mode.

Directly calls Raft core without gRPC overhead.

Implementations

impl EmbeddedClient

pub async fn put( &self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>, ) -> Result<(), ClientApiError>

Store a key-value pair with strong consistency.

pub async fn get_linearizable( &self, key: impl AsRef<[u8]>, ) -> Result<Option<Bytes>, ClientApiError>

Strongly consistent read (linearizable).

Guarantees reading the latest committed value by querying the Leader. Use for critical reads where staleness is unacceptable.

Performance

• Latency: ~1-5ms (network RTT to Leader)
• Throughput: Limited by Leader capacity

Raft Protocol

Implements linearizable read per Raft §8.

Example

let client = engine.client();
let value = client.get_linearizable(b"critical-config").await?;

pub async fn get_eventual( &self, key: impl AsRef<[u8]>, ) -> Result<Option<Bytes>, ClientApiError>

Eventually consistent read (stale OK).

Reads from local state machine without Leader coordination. Fast but may return stale data if replication is lagging.

Performance

• Latency: ~0.1ms (local memory access)
• Throughput: High (no Leader bottleneck)

Use Cases

• Read-heavy workloads
• Analytics/reporting (staleness acceptable)
• Caching scenarios

Example

let client = engine.client();
let cached_value = client.get_eventual(b"user-preference").await?;

pub async fn get_with_consistency( &self, key: impl AsRef<[u8]>, consistency: ReadConsistencyPolicy, ) -> Result<Option<Bytes>, ClientApiError>

Advanced: Read with explicit consistency policy.

For fine-grained control over read consistency vs performance trade-off.

Consistency Policies

• LinearizableRead: Read from Leader (strong consistency, may be slower)
• EventualConsistency: Read from local node (fast, may be stale)
• LeaseRead: Optimized Leader read using lease mechanism

Example

use d_engine_proto::client::ReadConsistencyPolicy;

let value = client.get_with_consistency(
    b"key",
    ReadConsistencyPolicy::LeaseRead,
).await?;

pub async fn get_multi_linearizable( &self, keys: &[Bytes], ) -> Result<Vec<Option<Bytes>>, ClientApiError>

Get multiple keys with linearizable consistency.

Reads multiple keys from the Leader with strong consistency guarantee.

Example

let keys = vec![Bytes::from("key1"), Bytes::from("key2")];
let values = client.get_multi_linearizable(&keys).await?;

pub async fn get_multi_eventual( &self, keys: &[Bytes], ) -> Result<Vec<Option<Bytes>>, ClientApiError>

Get multiple keys with eventual consistency.

Reads multiple keys from local state machine (fast, may be stale).

Example

let keys = vec![Bytes::from("key1"), Bytes::from("key2")];
let values = client.get_multi_eventual(&keys).await?;

pub async fn get_multi_with_consistency( &self, keys: &[Bytes], consistency: ReadConsistencyPolicy, ) -> Result<Vec<Option<Bytes>>, ClientApiError>

Advanced: Get multiple keys with explicit consistency policy.

pub async fn delete(&self, key: impl AsRef<[u8]>) -> Result<(), ClientApiError>

Delete a key-value pair.

pub fn client_id(&self) -> u32

Returns the client ID assigned to this local client

pub fn timeout(&self) -> Duration

Returns the configured timeout duration for operations

pub fn node_id(&self) -> u32

Returns the node ID for testing purposes

pub fn watch( &self, key: impl AsRef<[u8]>, ) -> Result<WatcherHandle, ClientApiError>

Watch for changes to a specific key

Returns a WatcherHandle that yields watch events when the key’s value changes. The stream will continue until explicitly dropped or a connection error occurs.

Arguments

• key - The key to watch

Returns

A WatcherHandle that can be used to receive watch events

Errors

Returns error if watch feature is not enabled or WatchRegistry not initialized

Example

let client = engine.client();
let mut watcher = client.watch(b"config/timeout").await?;
while let Some(event) = watcher.next().await {
    println!("Value changed: {:?}", event);
}

Trait Implementations

impl ClientApi for EmbeddedClient

fn put<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, value: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<(), ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Stores a key-value pair with strong consistency.

fn put_with_ttl<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, value: impl AsRef<[u8]> + Send + 'async_trait, ttl_secs: u64, ) -> Pin<Box<dyn Future<Output = Result<(), ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Stores a key-value pair with time-to-live (TTL).

fn get<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<Option<Bytes>, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Retrieves the value associated with a key.

fn get_multi<'life0, 'life1, 'async_trait>( &'life0 self, keys: &'life1 [Bytes], ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<Bytes>>, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, EmbeddedClient: 'async_trait,

Retrieves multiple keys in a single request.

fn delete<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<(), ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Deletes a key-value pair with strong consistency.

fn compare_and_swap<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, expected_value: Option<impl AsRef<[u8]> + Send + 'async_trait>, new_value: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<bool, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Atomically compare and swap a key’s value

fn list_members<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<NodeMeta>, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Lists all cluster members with metadata

fn get_leader_id<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Option<u32>, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Get the current leader ID

fn get_multi_with_policy<'life0, 'life1, 'async_trait>( &'life0 self, keys: &'life1 [Bytes], consistency_policy: Option<ReadConsistencyPolicy>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<Bytes>>, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, EmbeddedClient: 'async_trait,

Retrieves multiple keys with explicit consistency policy

fn get_linearizable<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<Option<Bytes>, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Retrieves a key with linearizable (strong) consistency

fn get_lease<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<Option<Bytes>, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Retrieves a key with lease-based consistency

fn get_eventual<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<Option<Bytes>, ClientApiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EmbeddedClient: 'async_trait,

Retrieves a key with eventual consistency

impl Clone for EmbeddedClient

fn clone(&self) -> EmbeddedClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EmbeddedClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.