xz-memory-core 0.2.0

Core abstractions for the xz-memory storage engine: EntryStore, IndexSearcher, and shared types
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

use async_trait::async_trait;

use crate::error::StoreError;
use crate::types::entry::{Entry, QueryOptions, TimeRange};

/// Generic entry storage trait.
///
/// Provides append / query / evict / delete / clear-partition operations
/// on partition-organised entries, suitable for short-term memory windows,
/// log segments, or any ordered entry collection.
///
/// Implementors must be `Send + Sync` so they can be used across `async` boundaries.
///
/// # Examples
///
/// ```
/// use async_trait::async_trait;
/// use xz_memory_core::types::entry::{Entry, QueryOptions, SortOrder, TimeRange};
/// use xz_memory_core::traits::store::EntryStore;
/// use xz_memory_core::StoreError;
///
/// struct MockStore;
///
/// #[async_trait]
/// impl EntryStore for MockStore {
///     async fn append(&self, entry: Entry) -> Result<(), StoreError> {
///         Ok(())
///     }
///     async fn query(
///         &self,
///         partition: &str,
///         range: &TimeRange,
///         opts: &QueryOptions,
///     ) -> Result<Vec<Entry>, StoreError> {
///         Ok(vec![])
///     }
///     async fn evict(&self, partition: &str, keep: usize) -> Result<usize, StoreError> {
///         Ok(0)
///     }
///     async fn delete(&self, id: &str) -> Result<(), StoreError> {
///         Ok(())
///     }
///     async fn clear_partition(&self, partition: &str) -> Result<(), StoreError> {
///         Ok(())
///     }
/// }
///
/// let rt = tokio::runtime::Builder::new_current_thread().build().unwrap();
/// rt.block_on(async {
///     let store = MockStore;
///     let entry = Entry {
///         id: "test-1".into(),
///         partition: "default".into(),
///         body: "hello".into(),
///         recorded_at: 1000,
///     };
///     let opts = QueryOptions {
///         limit: 10,
///         sort: SortOrder::Descending,
///     };
///     let range = TimeRange {
///         start: None,
///         end: None,
///     };
///
///     assert!(store.append(entry).await.is_ok());
///     let results = store.query("default", &range, &opts).await.unwrap();
///     assert!(results.is_empty());
/// });
/// ```
#[async_trait]
pub trait EntryStore: Send + Sync {
    /// Append a new entry to the partition.
    async fn append(&self, entry: Entry) -> Result<(), StoreError>;

    /// Query entries within a time range, sorted and limited.
    async fn query(
        &self,
        partition: &str,
        range: &TimeRange,
        opts: &QueryOptions,
    ) -> Result<Vec<Entry>, StoreError>;

    /// Evict oldest entries, keeping only `keep` most recent.
    /// Returns the number of entries evicted.
    async fn evict(&self, partition: &str, keep: usize) -> Result<usize, StoreError>;

    /// Delete a single entry by ID.
    async fn delete(&self, id: &str) -> Result<(), StoreError>;

    /// Remove all entries in a partition.
    async fn clear_partition(&self, partition: &str) -> Result<(), StoreError>;
}