Struct Storage

pub struct Storage { /* private fields */ }

Anda DB storage layer implementation based on object_store.

Implementations

impl Storage

pub async fn connect( path: String, object_store: Arc<dyn ObjectStore>, config: StorageConfig, ) -> Result<Storage, DBError>

Connects to or initializes the storage at the given path.

Attempts to load existing metadata. If not found, initializes with the provided config.

Arguments

• path - The base path for this storage instance within the object store.
• object_store - The underlying object store implementation.
• config - The configuration for the storage layer.

Errors

Returns DBError if metadata loading fails (other than NotFound) or initialization fails.

pub async fn store_metadata( &self, check_point: u64, now_ms: u64, ) -> Result<(), DBError>

Stores the current storage metadata (config and stats) to the object store.

This operation is rate-limited by last_saved timestamp to avoid frequent writes. It increments the internal version counter upon successful save.

Arguments

• check_point - The current checkpoint value, used for check_point.
• now_ms - The current timestamp in milliseconds, used for last_saved.

Errors

Returns DBError if writing the metadata fails.

pub fn metadata(&self) -> StorageMetadata

Returns a copy of the current storage metadata.

pub fn base_path(&self) -> &Path

Returns the base path of this storage instance.

pub fn object_chunk_size(&self) -> usize

Returns the configured object chunk size.

pub fn stats(&self) -> StorageStats

Returns a copy of the current storage statistics.

pub async fn fetch<T>( &self, doc_path: &str, ) -> Result<(T, ObjectVersion), DBError>

where T: DeserializeOwned,

Fetches and deserializes a document directly from the object store, bypassing the cache.

Arguments

• doc_path - The relative path of the document within the storage base path.

Errors

Returns DBError if the object is not found, fetching fails, or deserialization fails.

pub async fn fetch_bytes( &self, doc_path: &str, ) -> Result<(Bytes, ObjectVersion), DBError>

Fetches the raw bytes of a document directly from the object store, bypassing the cache.

Arguments

• doc_path - The relative path of the document within the storage base path.

Errors

Returns DBError if the object is not found or fetching fails.

pub async fn get<T>( &self, doc_path: &str, ) -> Result<(T, ObjectVersion), DBError>

where T: DeserializeOwned,

Gets and deserializes a document, potentially using the cache.

If the cache is enabled and the object is found and considered “small”, it will be served from the cache. Otherwise, it fetches from the object store and potentially caches it if small enough.

Arguments

• doc_path - The relative path of the document within the storage base path.

Errors

Returns DBError if the object is not found, fetching fails, or deserialization fails.

pub async fn stream_reader( &self, doc_path: &str, ) -> Result<Pin<Box<dyn AsyncRead>>, DBError>

Creates an asynchronous reader (AsyncRead) for streaming a document’s content. Handles decompression automatically if enabled.

Arguments

• doc_path - The relative path of the document.

Errors

Returns DBError if fetching the object metadata fails.

pub async fn create<T>( &self, doc_path: &str, doc: &T, ) -> Result<ObjectVersion, DBError>

where T: Serialize,

Creates a new document in the object store. Fails if the document already exists.

Serializes the document using ciborium and compresses it if enabled. This method is suitable only for objects smaller than max_small_object_size.

Arguments

• doc_path - The relative path for the new document.
• doc - The document to serialize and store.

Errors

Returns DBError if serialization fails, the object is too large, or the put operation fails (e.g., object already exists).

pub async fn put<T>( &self, doc_path: &str, doc: &T, version: Option<ObjectVersion>, ) -> Result<ObjectVersion, DBError>

where T: Serialize,

Puts (creates or overwrites/updates) a document in the object store.

Serializes the document using ciborium and compresses it if enabled. This method is suitable only for objects smaller than max_small_object_size. Use stream_writer for larger objects.

Arguments

• doc_path - The relative path of the document.
• doc - The document to serialize and store.
• version - If Some, performs a conditional update based on the provided ObjectVersion (e.g., ETag match). If None, overwrites unconditionally.

Errors

Returns DBError if serialization fails, the object is too large, or the put operation fails (e.g., conditional update fails).

pub async fn put_bytes( &self, doc_path: &str, data: Bytes, mode: PutMode, ) -> Result<ObjectVersion, DBError>

Puts raw bytes into the object store.

Compresses the data if enabled. This method is suitable only for data smaller than max_small_object_size. Use stream_writer for larger data.

Arguments

• doc_path - The relative path of the object.
• data - The raw bytes to store.
• mode - The PutMode (Create, Overwrite, Update).

Errors

Returns DBError if the data is too large or the put operation fails.

pub fn to_writer(&self, doc_path: &str, mode: PutMode) -> SingleWriter

Creates an asynchronous writer (AsyncWrite) for writing small objects (< max_small_object_size).

Data is buffered in memory and written in a single put operation on poll_flush or poll_close. Use stream_writer for large objects.

Arguments

• doc_path - The relative path of the object.
• mode - The PutMode (Create, Overwrite, Update).

pub fn stream_writer(&self, doc_path: &str) -> Pin<Box<dyn AsyncWrite>>

Creates an asynchronous writer (AsyncWrite) for streaming large objects.

Data is written in chunks using the underlying object store’s multipart upload or equivalent. Handles compression automatically if enabled.

Arguments

• doc_path - The relative path of the object.

pub async fn delete(&self, doc_path: &str) -> Result<(), DBError>

Deletes a document from the object store and removes it from the cache if present.

Arguments

• doc_path - The relative path of the document to delete.

Errors

Returns DBError if the delete operation fails.

pub fn list<T>( &self, prefix: Option<&str>, offset: Option<&str>, ) -> BoxStream<'_, Result<(T, ObjectVersion), DBError>>

where T: DeserializeOwned + Send,

Lists documents in the storage, optionally filtering by prefix and starting from an offset.

Fetches and deserializes each listed object. This can be inefficient for large listings. Consider using object_store.list directly if only metadata is needed.

Arguments

• prefix - Optional path prefix to filter the listing.
• offset - Optional path to start the listing after.

Returns

A stream of Result<(T, ObjectVersion), DBError>.

Trait Implementations

impl Clone for Storage

fn clone(&self) -> Storage

Returns a duplicate of the value.

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

Performs copy-assignment from source.