fornix 0.4.0

Knowledge storage, retrieval, and graph infrastructure for cognitive systems
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

//! The `CacheAdapter` trait — the core interface for all cache backends.

use async_trait::async_trait;
use crate::cache::{config::CacheConfig, error::Result, stats::CacheStats};
use crate::common::namespace::Namespace;
use crate::store::health::HealthReport;

/// The core interface for all cache backends.
///
/// Values are stored as raw bytes (`Vec<u8>`) for binary safety.
/// Callers are responsible for serialising and deserialising their own types.
/// TTL overrides at the call site take precedence over the adapter's
/// configured default TTL.
#[async_trait]
pub trait CacheAdapter: Send + Sync {
    /// Store a value under `key` in `namespace`.
    ///
    /// `ttl` overrides the adapter's configured default TTL.
    /// `None` means use the default; `Some(Duration::ZERO)` explicitly disables expiry.
    async fn set(
        &self,
        key: &str,
        value: Vec<u8>,
        namespace: Option<&Namespace>,
        ttl: Option<std::time::Duration>,
    ) -> Result<()>;

    /// Retrieve a value by `key` from `namespace`.
    ///
    /// Returns `None` if the key does not exist or has expired.
    async fn get(&self, key: &str, namespace: Option<&Namespace>) -> Result<Option<Vec<u8>>>;

    /// Delete a single entry. Returns `true` if the entry existed and was removed.
    async fn delete(&self, key: &str, namespace: Option<&Namespace>) -> Result<bool>;

    /// Delete all entries within `namespace`, or all entries if `None`.
    /// Returns the number of entries removed.
    async fn clear(&self, namespace: Option<&Namespace>) -> Result<usize>;

    /// Returns `true` if the key exists and has not expired.
    async fn exists(&self, key: &str, namespace: Option<&Namespace>) -> Result<bool>;

    /// Returns statistics for `namespace`, or aggregate stats if `None`.
    async fn stats(&self, namespace: Option<&Namespace>) -> Result<CacheStats>;

    /// Check the health of the cache backend.
    async fn healthcheck(&self) -> HealthReport;

    /// The human-readable name of this adapter.
    fn name(&self) -> &'static str;

    /// Whether the adapter is currently connected.
    fn is_connected(&self) -> bool;

    /// The configuration this adapter was built from.
    fn config(&self) -> &CacheConfig;
}