Skip to main content

Store

nucleation::store

Trait Store 

Source 
pub trait Store: Send + Sync {
    // Required methods
    fn get(&self, key: &str) -> Result<Option<Vec<u8>>>;
    fn put(&self, key: &str, bytes: &[u8]) -> Result<()>;
    fn exists(&self, key: &str) -> Result<bool>;
    fn delete(&self, key: &str) -> Result<()>;
    fn list(&self, prefix: &str) -> Result<Vec<String>>;
    fn health(&self) -> Result<()>;

    // Provided methods
    fn put_if_absent(&self, key: &str, bytes: &[u8]) -> Result<bool> { ... }
    fn list_paginated(
        &self,
        prefix: &str,
        after: Option<&str>,
        limit: usize,
    ) -> Result<(Vec<String>, Option<String>)> { ... }
    fn reader(&self, key: &str) -> Result<Box<dyn Read + '_>> { ... }
    fn writer(&self, key: &str) -> Result<Box<dyn Write + '_>> { ... }
}
Expand description

A location-agnostic byte store keyed by /-delimited UTF-8 paths.

Semantics every backend must honour (enforced by the shared contract suite in [contract]):

  • put overwrites an existing key.
  • get on a missing key returns Ok(None); reader returns StoreError::NotFound.
  • delete of a missing key is idempotent (Ok).
  • list(prefix) returns every key for which key.starts_with(prefix).

Required Methods§

Source

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

Fetch the bytes at key, or None if absent.

Source

fn put(&self, key: &str, bytes: &[u8]) -> Result<()>

Store bytes at key, overwriting any existing object.

Source

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

Whether an object exists at key.

Source

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

Remove key. Removing a missing key succeeds (idempotent).

Source

fn list(&self, prefix: &str) -> Result<Vec<String>>

Every key under prefix (i.e. key.starts_with(prefix)). Order is unspecified.

Source

fn health(&self) -> Result<()>

Cheap reachability/credentials check. Ok(()) means usable.

Provided Methods§

Source

fn put_if_absent(&self, key: &str, bytes: &[u8]) -> Result<bool>

Atomically write bytes at key only if no object exists there. Returns true if it was written, false if the key already existed.

The default is a non-atomic exists-then-put, safe only without concurrent writers. Networked backends override it with a genuinely atomic operation (S3 If-None-Match, Redis SET NX, Postgres ON CONFLICT DO NOTHING).

Source

fn list_paginated( &self, prefix: &str, after: Option<&str>, limit: usize, ) -> Result<(Vec<String>, Option<String>)>

A keyset page of keys under prefix, sorted ascending, starting strictly after after (exclusive), at most limit keys. Returns the page plus a cursor to pass as the next after when more keys may remain (None once exhausted). limit == 0 yields an empty page.

The default lists everything and slices in memory; S3 and Postgres override it with native keyset pagination (start-after / key > $after).

Source

fn reader(&self, key: &str) -> Result<Box<dyn Read + '_>>

Streaming read of key. The default buffers via Store::get; backends with native streaming may override.

Source

fn writer(&self, key: &str) -> Result<Box<dyn Write + '_>>

Streaming write of key. The default buffers in memory and commits via Store::put on flush/drop; backends with native streaming may override. Object-safe: callable on &dyn Store.

Dyn Compatibility§

This trait is dyn compatible.

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

Implementors§