Skip to main content

Kv

alien_bindings::traits

Trait Kv 

Source 
pub trait Kv: Binding {
    // Required methods
    fn get<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<KvEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn put<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        value: Vec<u8>,
        options: Option<PutOptions>,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn delete<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        if_version: Option<&'life2 str>,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn exists<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn scan_prefix<'life0, 'life1, 'async_trait>(
        &'life0 self,
        prefix: &'life1 str,
        limit: Option<usize>,
        cursor: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<ScanResult>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
}
Expand description

A trait for key-value store bindings that provide minimal, platform-agnostic KV operations. This API is designed to work consistently across DynamoDB, Firestore, Azure Table Storage, and the local provider.

Required Methods§

Source

fn get<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<KvEntry>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get an entry by key. Returns None if the key doesn’t exist or has expired.

TTL Behavior: TTL is a soft hint for automatic cleanup. If now >= expires_at, implementations SHOULD behave as if the key is absent, even if the item still exists physically in the backend. Physical deletion is eventual and not guaranteed.

Validation: Keys are validated against MAX_KEY_BYTES and portable charset. Invalid keys return KvError::InvalidKey immediately.

Source

fn put<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, value: Vec<u8>, options: Option<PutOptions>, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Put a value with optional options. Conditional writes return false when their precondition does not match. Unconditional writes return true.

Size Limits:

  • Keys: ≤ MAX_KEY_BYTES (512 bytes) with portable ASCII charset
  • Values: ≤ MAX_VALUE_BYTES (24,576 bytes = 24 KiB)

Validation: Size and charset constraints are enforced before backend calls. Invalid inputs return KvError::InvalidKey or KvError::InvalidValue immediately.

TTL Behavior: TTL is a soft hint for automatic cleanup. If TTL is specified, item expires at put_time + ttl. Expired items SHOULD appear absent on subsequent reads, but physical deletion is eventual and not guaranteed.

Conditional Logic: PutCondition::Absent uses each backend’s atomic create primitive, with a version-guarded takeover when an expired row still exists physically. PutCondition::Version uses DynamoDB conditions, Firestore update-time preconditions, Azure entity tags, or the local database’s conditional update.

Source

fn delete<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, key: &'life1 str, if_version: Option<&'life2 str>, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Delete a key. No error if key doesn’t exist.

Validation: Keys are validated against MAX_KEY_BYTES and portable charset. Invalid keys return KvError::InvalidKey immediately. When if_version is supplied, delete only if the key still has that opaque version. Returns false when a conditional delete finds the key absent, expired, or changed. Unconditional deletes return true, including when the key is already absent.

Source

fn exists<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Check if a key exists without retrieving the value.

TTL Behavior: TTL is a soft hint for automatic cleanup. If now >= expires_at, SHOULD return false even if physically present. Physical deletion is eventual and not guaranteed.

Validation: Keys are validated against MAX_KEY_BYTES and portable charset. Invalid keys return KvError::InvalidKey immediately.

Source

fn scan_prefix<'life0, 'life1, 'async_trait>( &'life0 self, prefix: &'life1 str, limit: Option<usize>, cursor: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<ScanResult>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Scan keys with a prefix, with pagination support.

Scan Contract:

  • Returns an arbitrary, unordered subset in backend-natural order
  • No ordering guarantees across backends (for example, Azure partition fan-out)
  • May return ≤ limit items (not guaranteed to fill even if more data exists)
  • Clients MUST de-duplicate keys across pages (backends may return duplicates)
  • No completeness guarantee under concurrent writes (may miss or duplicate)
  • Without concurrent changes, following every returned cursor until None visits every matching, unexpired key visible to the backend

Cursor Behavior:

  • Opaque string, implementation-specific format
  • Bound to the prefix that created it; using it with another prefix is invalid
  • May become invalid after backend state changes
  • No TTL guarantees - can expire without notice
  • Passing invalid cursor should return error, not partial results

TTL Behavior: TTL is a soft hint for automatic cleanup. Expired items SHOULD be filtered out from results, but physical deletion is eventual and not guaranteed.

Validation: Prefix follows same key validation rules. Invalid prefix returns KvError::InvalidKey immediately.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§