Add storage abstraction layer for metadata persistence

Author: ekkolon

Cargo.lock

@@ -15,6 +15,8 @@ categories = ["database", "network-programming"]
 
 [workspace.dependencies]
 thiserror = "2"
+tracing = "0.1"
+
 base64 = "0.22"
 blake3 = "1.8"
 dashmap = "6.1"

Cargo.toml

@@ -12,6 +12,7 @@ categories.workspace = true
 
 [dependencies]
 thiserror.workspace = true
+tracing.workspace = true
 base64 = { workspace = true }
 blake3 = { workspace = true }
 dashmap = { workspace = true }

minikv-core/Cargo.toml

@@ -0,0 +1,5 @@
+use thiserror::Error;
+
+/// Unified error type for minikv.
+#[derive(Debug, Error)]
+pub enum Error {}

minikv-core/src/error.rs

@@ -1,3 +1,7 @@
+pub mod error;
 pub mod hashing;
 pub mod locking;
+pub mod storage;
 pub mod volumes;
+
+pub use error::Error;

minikv-core/src/lib.rs

@@ -0,0 +1,95 @@
+//! Storage abstraction layer for metadata persistence.
+//!
+//! All interactions with LevelDB or in-memory stores go through the
+//! `MetadataStore` trait. This isolates storage concerns from business logic
+//! and allows swapping backends in tests or future implementations.
+
+use crate::error::Error;
+
+/// A single key-value pair in a metadata store.
+///
+/// - The first element (`Vec<u8>`) is the key.
+/// - The second element (`Vec<u8>`) is the associated value.
+///
+/// This type is used throughout `MetadataStore` APIs for operations that
+/// return or manipulate multiple entries, such as `scan_prefix` or `scan_all`.
+pub type KeyValuePair = (Vec<u8>, Vec<u8>);
+
+/// Trait defining the interface for all metadata stores.
+///
+/// Implementors must be `Send + Sync` to allow sharing via `Arc<dyn MetadataStore>`
+/// across async tasks.
+pub trait MetadataStore: Send + Sync {
+    /// Retrieve the value associated with `key`. Returns `None` if the key is absent.
+    fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, Error>;
+
+    /// Insert or update a key-value pair.
+    fn put(&self, key: &[u8], value: &[u8]) -> Result<(), Error>;
+
+    /// Delete the given key. Succeeds silently if the key does not exist.
+    fn delete(&self, key: &[u8]) -> Result<(), Error>;
+
+    /// Return all key-value pairs with keys starting with `prefix`,
+    /// ordered lexicographically by key.
+    fn scan_prefix(&self, prefix: &[u8]) -> Result<Vec<KeyValuePair>, Error>;
+
+    /// Return all key-value pairs in the store.
+    fn scan_all(&self) -> Result<Vec<KeyValuePair>, Error>;
+
+    /// Remove all entries in the store.
+    /// Primarily used by `rebuild_all` to regenerate the database from scratch.
+    fn delete_all(&self) -> Result<(), Error>;
+}
+
+/// In-memory `MetadataStore` backed by a `BTreeMap`.
+///
+/// Useful for unit and integration tests that do not require persistent storage.
+#[cfg(debug_assertions)]
+pub mod mem {
+    use super::*;
+    use std::collections::BTreeMap;
+    use std::sync::Mutex;
+
+    #[derive(Default)]
+    pub struct MemStore {
+        inner: Mutex<BTreeMap<Vec<u8>, Vec<u8>>>,
+    }
+
+    impl MetadataStore for MemStore {
+        fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, Error> {
+            Ok(self.inner.lock().unwrap().get(key).cloned())
+        }
+
+        fn put(&self, key: &[u8], value: &[u8]) -> Result<(), Error> {
+            self.inner
+                .lock()
+                .unwrap()
+                .insert(key.to_vec(), value.to_vec());
+            Ok(())
+        }
+
+        fn delete(&self, key: &[u8]) -> Result<(), Error> {
+            self.inner.lock().unwrap().remove(key);
+            Ok(())
+        }
+
+        fn scan_prefix(&self, prefix: &[u8]) -> Result<Vec<KeyValuePair>, Error> {
+            let store = self.inner.lock().unwrap();
+            Ok(store
+                .iter()
+                .filter(|(k, _)| k.starts_with(prefix))
+                .map(|(k, v)| (k.clone(), v.clone()))
+                .collect())
+        }
+
+        fn scan_all(&self) -> Result<Vec<KeyValuePair>, Error> {
+            let store = self.inner.lock().unwrap();
+            Ok(store.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
+        }
+
+        fn delete_all(&self) -> Result<(), Error> {
+            self.inner.lock().unwrap().clear();
+            Ok(())
+        }
+    }
+}