amaters_core/
traits.rs

1//! Core trait definitions for AmateRS
2//!
3//! This module defines the fundamental traits that all storage engines must implement.
4
5use crate::error::Result;
6use crate::types::{CipherBlob, Key};
7use async_trait::async_trait;
8
9/// Core storage engine trait
10///
11/// All storage implementations (in-memory, LSM-Tree, etc.) must implement this trait.
12/// Operations are async and guarantee durability (fsync) on success.
13#[async_trait]
14pub trait StorageEngine: Send + Sync + 'static {
15    /// Write data with fsync guarantee
16    ///
17    /// # Errors
18    /// Returns `IoError` if write fails or `StorageIntegrity` if corruption detected
19    async fn put(&self, key: &Key, value: &CipherBlob) -> Result<()>;
20
21    /// Read data, returns None if key doesn't exist
22    ///
23    /// # Errors
24    /// Returns `IoError` if read fails or `StorageIntegrity` if data corrupted
25    async fn get(&self, key: &Key) -> Result<Option<CipherBlob>>;
26
27    /// Atomic update operation (Read-Modify-Write)
28    ///
29    /// Strictly eliminates race conditions by holding a lock during the operation.
30    ///
31    /// # Errors
32    /// Returns error if read/write fails or if update function returns error
33    async fn atomic_update<F>(&self, key: &Key, f: F) -> Result<()>
34    where
35        F: Fn(&CipherBlob) -> Result<CipherBlob> + Send + Sync;
36
37    /// Delete a key
38    ///
39    /// # Errors
40    /// Returns `IoError` if deletion fails
41    async fn delete(&self, key: &Key) -> Result<()>;
42
43    /// Range scan from start (inclusive) to end (exclusive)
44    ///
45    /// # Errors
46    /// Returns `IoError` if scan fails
47    async fn range(&self, start: &Key, end: &Key) -> Result<Vec<(Key, CipherBlob)>>;
48
49    /// Check if a key exists
50    ///
51    /// # Errors
52    /// Returns `IoError` if check fails
53    async fn contains(&self, key: &Key) -> Result<bool> {
54        Ok(self.get(key).await?.is_some())
55    }
56
57    /// Get all keys in the storage (for debugging/admin)
58    ///
59    /// # Errors
60    /// Returns `IoError` if scan fails
61    async fn keys(&self) -> Result<Vec<Key>>;
62
63    /// Flush all pending writes to disk
64    ///
65    /// # Errors
66    /// Returns `IoError` if flush fails
67    async fn flush(&self) -> Result<()>;
68
69    /// Close the storage engine gracefully
70    ///
71    /// # Errors
72    /// Returns `IoError` if close fails
73    async fn close(&self) -> Result<()>;
74}
amaters_core/traits.rs

amaters_core/
traits.rs
