mqdb_core/storage/
backend.rs

1// Copyright 2025-2026 LabOverWire. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4use crate::error::Result;
5use std::future::Future;
6
7/// Storage backend trait for key-value operations.
8pub trait StorageBackend: Send + Sync {
9    /// Gets a value by key.
10    ///
11    /// # Errors
12    /// Returns an error if the storage operation fails.
13    fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>>;
14
15    /// Inserts a key-value pair.
16    ///
17    /// # Errors
18    /// Returns an error if the storage operation fails.
19    fn insert(&self, key: &[u8], value: &[u8]) -> Result<()>;
20
21    /// Removes a key.
22    ///
23    /// # Errors
24    /// Returns an error if the storage operation fails.
25    fn remove(&self, key: &[u8]) -> Result<()>;
26
27    /// Scans all keys with the given prefix.
28    ///
29    /// # Errors
30    /// Returns an error if the storage operation fails.
31    fn prefix_scan(&self, prefix: &[u8]) -> Result<Vec<(Vec<u8>, Vec<u8>)>>;
32
33    /// Counts entries matching the given prefix without materializing values.
34    ///
35    /// # Errors
36    /// Returns an error if the storage operation fails.
37    fn prefix_count(&self, prefix: &[u8]) -> Result<usize>;
38
39    /// Returns only keys matching the given prefix, without loading values.
40    ///
41    /// # Errors
42    /// Returns an error if the storage operation fails.
43    fn prefix_scan_keys(&self, prefix: &[u8]) -> Result<Vec<Vec<u8>>>;
44
45    /// Scans entries matching prefix in batches, starting after `after_key`.
46    ///
47    /// Returns at most `batch_size` entries. Pass `None` for `after_key` to start
48    /// from the beginning of the prefix range.
49    ///
50    /// # Errors
51    /// Returns an error if the storage operation fails.
52    fn prefix_scan_batch(
53        &self,
54        prefix: &[u8],
55        batch_size: usize,
56        after_key: Option<&[u8]>,
57    ) -> Result<Vec<(Vec<u8>, Vec<u8>)>>;
58
59    /// Scans keys in the given range.
60    ///
61    /// # Errors
62    /// Returns an error if the storage operation fails.
63    fn range_scan(&self, start: &[u8], end: &[u8]) -> Result<Vec<(Vec<u8>, Vec<u8>)>>;
64
65    /// Creates a new batch for atomic operations.
66    fn batch(&self) -> Box<dyn BatchOperations>;
67
68    /// Flushes pending writes to storage.
69    ///
70    /// # Errors
71    /// Returns an error if the flush operation fails.
72    fn flush(&self) -> Result<()>;
73}
74
75/// Batch operations for atomic writes.
76pub trait BatchOperations: Send {
77    /// Queues an insert operation.
78    fn insert(&mut self, key: Vec<u8>, value: Vec<u8>);
79
80    /// Queues a remove operation.
81    fn remove(&mut self, key: Vec<u8>);
82
83    /// Sets an expected value for optimistic concurrency.
84    fn expect_value(&mut self, key: Vec<u8>, expected_value: Vec<u8>);
85
86    /// Commits all queued operations atomically.
87    ///
88    /// # Errors
89    /// Returns an error if the commit fails or expected values don't match.
90    fn commit(self: Box<Self>) -> Result<()>;
91}
92
93pub trait AsyncStorageBackend {
94    type Batch: AsyncBatchOperations;
95
96    fn get(&self, key: &[u8]) -> impl Future<Output = Result<Option<Vec<u8>>>>;
97    fn insert(&self, key: &[u8], value: &[u8]) -> impl Future<Output = Result<()>>;
98    fn remove(&self, key: &[u8]) -> impl Future<Output = Result<()>>;
99    fn prefix_scan(&self, prefix: &[u8]) -> impl Future<Output = Result<Vec<(Vec<u8>, Vec<u8>)>>>;
100    fn prefix_count(&self, prefix: &[u8]) -> impl Future<Output = Result<usize>>;
101    fn prefix_scan_keys(&self, prefix: &[u8]) -> impl Future<Output = Result<Vec<Vec<u8>>>>;
102    fn prefix_scan_batch(
103        &self,
104        prefix: &[u8],
105        batch_size: usize,
106        after_key: Option<&[u8]>,
107    ) -> impl Future<Output = Result<Vec<(Vec<u8>, Vec<u8>)>>>;
108    fn range_scan(
109        &self,
110        start: &[u8],
111        end: &[u8],
112    ) -> impl Future<Output = Result<Vec<(Vec<u8>, Vec<u8>)>>>;
113    fn batch(&self) -> Self::Batch;
114    fn flush(&self) -> impl Future<Output = Result<()>>;
115}
116
117pub trait AsyncBatchOperations {
118    fn insert(&mut self, key: Vec<u8>, value: Vec<u8>);
119    fn remove(&mut self, key: Vec<u8>);
120    fn expect_value(&mut self, key: Vec<u8>, expected_value: Vec<u8>);
121    fn commit(self) -> impl Future<Output = Result<()>>;
122}
mqdb_core/storage/backend.rs

mqdb_core/storage/
backend.rs
