BREAKING CHANGE(core): replace the TypeScript database engine with a Rust-backed embedded server and bridge

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

@@ -0,0 +1,185 @@
+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(())
+    }
+}