Struct LocalKvClient 

pub struct LocalKvClient { /* private fields */ }

Zero-overhead KV client for embedded mode.

Directly calls Raft core without gRPC overhead.

Implementations

impl LocalKvClient

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

Store a key-value pair with strong consistency.

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

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 = node.local_client();
let value = client.get_linearizable(b"critical-config").await?;

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

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 = node.local_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>, LocalClientError>

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>>, LocalClientError>

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>>, LocalClientError>

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>>, LocalClientError>

Advanced: Get multiple keys with explicit consistency policy.

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

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

Trait Implementations

impl Clone for LocalKvClient

fn clone(&self) -> LocalKvClient

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LocalKvClient

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

Formats the value using the given formatter.

impl KvClient for LocalKvClient

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<(), KvClientError>> + Send + 'async_trait>>

where 'life0: 'async_trait, LocalKvClient: '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<(), KvClientError>> + Send + 'async_trait>>

where 'life0: 'async_trait, LocalKvClient: '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>, KvClientError>> + Send + 'async_trait>>

where 'life0: 'async_trait, LocalKvClient: '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>>, KvClientError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, LocalKvClient: '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<(), KvClientError>> + Send + 'async_trait>>

where 'life0: 'async_trait, LocalKvClient: 'async_trait,

Deletes a key-value pair with strong consistency.