Struct RemoteKvStoreClient 

pub struct RemoteKvStoreClient { /* private fields */ }

Remote KV-store client. Holds a worker thread that owns the SHM ring endpoints; drop the client to stop the worker.

Implementations

impl RemoteKvStoreClient

pub fn connect(prefix: &str) -> Result<Self, RemoteError>

Connect to a daemon running with the given prefix. Uses the default ring depth (DEFAULT_RING_DEPTH) and call timeout (DEFAULT_CALL_TIMEOUT).

pub fn connect_with_depth( prefix: &str, depth: usize, ) -> Result<Self, RemoteError>

Connect with an explicit ring depth (must match the daemon’s). Equivalent to connect_with_options(prefix, ClientOptions { depth, ..Default::default() }).

pub fn connect_with_options( prefix: &str, opts: ClientOptions, ) -> Result<Self, RemoteError>

Connect with custom options.

pub fn is_dead(&self) -> bool

Returns true if the client has timed out and stopped serving new requests. Engine code should drop the handle and reconnect.

pub fn put_kv( &self, namespace: &str, key: &str, payload: Bytes, ) -> Result<(), RemoteError>

PUT a single key/value blob. Idempotent on (namespace, key).

pub fn get_kv( &self, namespace: &str, key: &str, ) -> Result<RemoteGetOutcome, RemoteError>

GET a single key/value blob. Returns Miss only on absence; transient daemon errors come back as Err.

pub fn get_many_kv_batch( &self, namespace: &str, keys: &[String], ) -> Result<Option<Bytes>, RemoteError>

Batched GET for one engine transfer. Returns an encoded bytes batch preserving keys order, or None when any key is missing.

pub fn exists(&self, namespace: &str, key: &str) -> Result<bool, RemoteError>

EXISTS, same path as GET but the daemon does not transfer the payload bytes back over the wire.

pub fn list_keys_batch(&self, namespace: &str) -> Result<Bytes, RemoteError>

List namespace-relative keys as an encoded key batch.

pub fn restore_from_s3(&self, namespace: &str) -> Result<usize, RemoteError>

Hydrate the daemon’s foyer cache from S3 for the given namespace. Returns the number of keys restored.

pub fn clear_foyer(&self) -> Result<(), RemoteError>

Drop the daemon’s foyer state. Test/admin only.

pub fn ping(&self) -> Result<(), RemoteError>

Round-trip ping for liveness checks.

pub fn stats(&self) -> Result<String, RemoteError>

Daemon-side metrics snapshot, JSON lines.

pub fn lookup_block_prefix( &self, namespace: &str, block_hashes_hex: &[String], ) -> Result<usize, RemoteError>

Block-shaped: count leading hashes present in the daemon’s metadata index. Mirrors wmbt_kv_lookup_block_prefix semantics: returns the number of hashes, counted from index 0 of block_hashes_hex, that the daemon’s metadata index recognized before the first miss. A leading miss returns 0.

Each entry of block_hashes_hex MUST be exactly 64 lower-hex characters (32-byte blake3 hash); the daemon rejects malformed input with RemoteError::DaemonStatus.

pub fn get_kv_blocks_batch( &self, namespace: &str, block_hashes_hex: &[String], ) -> Result<Option<Vec<Bytes>>, RemoteError>

Block-shaped: parallel batched GET for content-addressed blocks. On full hit returns Some(per-block bytes in input order); on any miss returns None (all-or-nothing, matches the cabi wmbt_kv_get_kv_blocks_borrowed contract).

pub fn put_kv_blocks_batch( &self, namespace: &str, block_hashes_hex: &[String], payloads: &[&[u8]], ) -> Result<u64, RemoteError>

Block-shaped: parallel batched PUT for content-addressed blocks. The daemon writes each block, then updates its in-process metadata index so a subsequent Self::lookup_block_prefix sees the new presence. Returns total bytes written across all blocks.

block_hashes_hex.len() MUST equal payloads.len(). The caller’s payload slices are copied into the daemon transport (rkyv-encoded inside the request frame).

pub fn ping_with_timeout(&self, timeout: Duration) -> Result<(), RemoteError>

Health-check ping with a custom (typically short) timeout. Useful for liveness probes that want to fail faster than the default call_timeout. Marks the client dead on timeout, same as any other call.

Trait Implementations

impl Drop for RemoteKvStoreClient

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.