smartdb/rust/crates/rustdb-storage/src/adapter.rs

use std::collections::HashSet;

use async_trait::async_trait;
use bson::Document;

use crate::error::StorageResult;

/// Core storage adapter trait that all backends must implement.
#[async_trait]
pub trait StorageAdapter: Send + Sync {
    // ---- lifecycle ----

    /// Initialize the storage backend (create directories, open files, etc.).
    async fn initialize(&self) -> StorageResult<()>;

    /// Gracefully shut down the storage backend.
    async fn close(&self) -> StorageResult<()>;

    // ---- database operations ----

    /// List all database names.
    async fn list_databases(&self) -> StorageResult<Vec<String>>;

    /// Create a new database.
    async fn create_database(&self, db: &str) -> StorageResult<()>;

    /// Drop a database and all its collections.
    async fn drop_database(&self, db: &str) -> StorageResult<()>;

    /// Check whether a database exists.
    async fn database_exists(&self, db: &str) -> StorageResult<bool>;

    // ---- collection operations ----

    /// List all collection names in a database.
    async fn list_collections(&self, db: &str) -> StorageResult<Vec<String>>;

    /// Create a new collection inside a database.
    async fn create_collection(&self, db: &str, coll: &str) -> StorageResult<()>;

    /// Drop a collection.
    async fn drop_collection(&self, db: &str, coll: &str) -> StorageResult<()>;

    /// Check whether a collection exists.
    async fn collection_exists(&self, db: &str, coll: &str) -> StorageResult<bool>;

    /// Rename a collection within the same database.
    async fn rename_collection(
        &self,
        db: &str,
        old_name: &str,
        new_name: &str,
    ) -> StorageResult<()>;

    // ---- document write operations ----

    /// Insert a single document. Returns the `_id` as hex string.
    async fn insert_one(
        &self,
        db: &str,
        coll: &str,
        doc: Document,
    ) -> StorageResult<String>;

    /// Insert many documents. Returns the `_id` hex strings.
    async fn insert_many(
        &self,
        db: &str,
        coll: &str,
        docs: Vec<Document>,
    ) -> StorageResult<Vec<String>>;

    /// Replace a document by its `_id` hex string.
    async fn update_by_id(
        &self,
        db: &str,
        coll: &str,
        id: &str,
        doc: Document,
    ) -> StorageResult<()>;

    /// Delete a single document by `_id` hex string.
    async fn delete_by_id(
        &self,
        db: &str,
        coll: &str,
        id: &str,
    ) -> StorageResult<()>;

    /// Delete multiple documents by `_id` hex strings.
    async fn delete_by_ids(
        &self,
        db: &str,
        coll: &str,
        ids: &[String],
    ) -> StorageResult<()>;

    // ---- document read operations ----

    /// Return all documents in a collection.
    async fn find_all(
        &self,
        db: &str,
        coll: &str,
    ) -> StorageResult<Vec<Document>>;

    /// Return documents whose `_id` hex is in the given set.
    async fn find_by_ids(
        &self,
        db: &str,
        coll: &str,
        ids: HashSet<String>,
    ) -> StorageResult<Vec<Document>>;

    /// Return a single document by `_id` hex.
    async fn find_by_id(
        &self,
        db: &str,
        coll: &str,
        id: &str,
    ) -> StorageResult<Option<Document>>;

    /// Count documents in a collection.
    async fn count(
        &self,
        db: &str,
        coll: &str,
    ) -> StorageResult<u64>;

    // ---- index operations ----

    /// Persist an index specification for a collection.
    async fn save_index(
        &self,
        db: &str,
        coll: &str,
        name: &str,
        spec: Document,
    ) -> StorageResult<()>;

    /// Return all saved index specs for a collection.
    async fn get_indexes(
        &self,
        db: &str,
        coll: &str,
    ) -> StorageResult<Vec<Document>>;

    /// Drop a named index.
    async fn drop_index(
        &self,
        db: &str,
        coll: &str,
        name: &str,
    ) -> StorageResult<()>;

    // ---- snapshot / conflict detection ----

    /// Create a logical snapshot timestamp for a collection. Returns a timestamp (ms).
    async fn create_snapshot(
        &self,
        db: &str,
        coll: &str,
    ) -> StorageResult<i64>;

    /// Check if any of the given document ids have been modified after `snapshot_time`.
    async fn has_conflicts(
        &self,
        db: &str,
        coll: &str,
        ids: &HashSet<String>,
        snapshot_time: i64,
    ) -> StorageResult<bool>;

    // ---- optional persistence (for in-memory backends) ----

    /// Persist current state to durable storage. Default: no-op.
    async fn persist(&self) -> StorageResult<()> {
        Ok(())
    }

    /// Restore state from durable storage. Default: no-op.
    async fn restore(&self) -> StorageResult<()> {
        Ok(())
    }
}