Struct KvStore 

pub struct KvStore { /* private fields */ }

Thread-safe, cloneable, in-memory key-value store.

Cloning yields a handle to the same underlying state (see module docs).

Implementations

impl KvStore

pub fn new() -> Self

Create a new store with default limits (1 MiB values, 10000 keys).

pub fn with_backend(self, backend: Arc<dyn KvBackend>) -> Self

Builder-style setter that installs a pluggable async KvBackend.

With a backend installed, the store runs in “cluster mode”: the *_async methods delegate their data operations to the backend instead of the local in-memory map. The synchronous methods are unaffected and continue to operate on the local map.

pub fn is_clustered(&self) -> bool

Whether this store is running in cluster mode (a backend is installed).

pub fn with_max_value_size(self, size: usize) -> Self

Builder-style setter for the maximum value size in bytes.

pub fn with_max_keys(self, count: usize) -> Self

Builder-style setter for the maximum number of keys.

pub fn set_max_value_size(&mut self, size: usize)

Set the maximum value size in bytes.

pub fn set_max_keys(&mut self, count: usize)

Set the maximum number of keys.

pub fn max_value_size(&self) -> usize

The configured maximum value size in bytes.

pub fn max_keys(&self) -> usize

The configured maximum number of keys.

pub fn validate_key(key: &str) -> Result<(), KvError>

Validate key format.

Keys must be non-empty, at most 1024 bytes, and contain only alphanumeric characters or one of -_./:.

Errors

Returns KvError::InvalidKey when the key fails validation.

pub fn clean_expired(&self)

Remove all expired entries from the store.

pub fn get(&self, key: &str) -> Result<Option<Vec<u8>>, KvError>

Get a value by key.

Returns None if the key is missing or expired.

Errors

Returns KvError::InvalidKey when the key is invalid.

pub fn get_string(&self, key: &str) -> Result<Option<String>, KvError>

Get a value as a UTF-8 string.

Errors

Returns KvError::InvalidKey when the key is invalid, or KvError::Storage when the stored bytes are not valid UTF-8.

pub fn set(&self, key: &str, value: &[u8]) -> Result<(), KvError>

Set a value.

Errors

Returns KvError::InvalidKey for an invalid key, KvError::ValueTooLarge when the value exceeds the configured limit, or KvError::QuotaExceeded when adding a new key would exceed the configured key count.

pub fn set_string(&self, key: &str, value: &str) -> Result<(), KvError>

Set a string value.

Errors

See KvStore::set.

pub fn set_with_ttl( &self, key: &str, value: &[u8], ttl_ns: u64, ) -> Result<(), KvError>

Set a value with a TTL in nanoseconds.

Errors

See KvStore::set.

pub fn delete(&self, key: &str) -> Result<bool, KvError>

Delete a key.

Returns true if the key existed and was deleted.

Errors

Returns KvError::InvalidKey when the key is invalid.

pub fn exists(&self, key: &str) -> bool

Check if a key exists (and has not expired).

pub fn list_keys(&self, prefix: &str) -> Result<Vec<String>, KvError>

List all non-expired keys with a given prefix.

Errors

This implementation never fails, but returns Result for parity with the WASM host interface and future backends.

pub fn increment(&self, key: &str, delta: i64) -> Result<i64, KvError>

Increment a numeric value atomically, returning the new value.

A missing or expired key is treated as 0. The arithmetic saturates.

Errors

Returns KvError::InvalidKey for an invalid key, KvError::Storage when the existing value is not a valid integer, or KvError::QuotaExceeded when adding a new key would exceed the quota.

pub fn compare_and_swap( &self, key: &str, expected: Option<&[u8]>, new_value: &[u8], ) -> Result<bool, KvError>

Compare-and-swap: set new_value only if the current value equals expected.

Returns true if the swap succeeded, false if the current value did not match expected.

Errors

Returns KvError::InvalidKey for an invalid key, KvError::ValueTooLarge when new_value exceeds the configured limit, or KvError::QuotaExceeded when adding a new key would exceed the quota.

pub async fn get_async(&self, key: &str) -> Result<Option<Vec<u8>>, KvError>

Async KvStore::get: delegates to the backend in cluster mode, otherwise runs the local sync logic.

Errors

Propagates errors from the backend, or KvError::InvalidKey for an invalid key on the local path.

pub async fn set_async(&self, key: &str, value: &[u8]) -> Result<(), KvError>

Async KvStore::set: delegates to the backend in cluster mode, otherwise runs the local sync logic.

Errors

Propagates errors from the backend, or the local KvStore::set errors.

pub async fn set_with_ttl_async( &self, key: &str, value: &[u8], ttl_ns: u64, ) -> Result<(), KvError>

Async KvStore::set_with_ttl: delegates to the backend in cluster mode, otherwise runs the local sync logic.

Errors

Propagates errors from the backend, or the local KvStore::set_with_ttl errors.

pub async fn delete_async(&self, key: &str) -> Result<bool, KvError>

Async KvStore::delete: delegates to the backend in cluster mode, otherwise runs the local sync logic.

Errors

Propagates errors from the backend, or KvError::InvalidKey for an invalid key on the local path.

pub async fn exists_async(&self, key: &str) -> Result<bool, KvError>

Async existence check: delegates to the backend in cluster mode, otherwise wraps the infallible local KvStore::exists.

Errors

Propagates errors from the backend. The local path never fails.

pub async fn list_keys_async( &self, prefix: &str, ) -> Result<Vec<String>, KvError>

Async KvStore::list_keys: delegates to the backend in cluster mode, otherwise runs the local sync logic.

Errors

Propagates errors from the backend. The local path never fails.

pub async fn increment_async( &self, key: &str, delta: i64, ) -> Result<i64, KvError>

Async KvStore::increment: delegates to the backend in cluster mode, otherwise runs the local sync logic.

Errors

Propagates errors from the backend, or the local KvStore::increment errors.

pub async fn compare_and_swap_async( &self, key: &str, expected: Option<&[u8]>, new: &[u8], ) -> Result<bool, KvError>

Async KvStore::compare_and_swap: delegates to the backend in cluster mode, otherwise runs the local sync logic.

Errors

Propagates errors from the backend, or the local KvStore::compare_and_swap errors.

pub fn clear(&self)

Remove all entries from the store.

pub fn subscribe(&self) -> Receiver<KvEvent>

Subscribe to all change events.

Returns a raw broadcast receiver. Slow consumers may observe broadcast::error::RecvError::Lagged.

pub fn watch_prefix( &self, prefix: impl Into<String>, ) -> impl Stream<Item = KvEvent>

Watch for change events whose key starts with prefix.

Returns a Stream that yields matching KvEvents. Lagged events (dropped because a slow consumer fell behind) are skipped.

Trait Implementations

impl Clone for KvStore

fn clone(&self) -> KvStore

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for KvStore

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

Formats the value using the given formatter.

impl Default for KvStore

fn default() -> Self

Returns the “default value” for a type.