foxtive 0.25.6

Foxtive Framework
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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

use crate::prelude::AppResult;
use async_trait::async_trait;
use serde::Serialize;
use serde::de::DeserializeOwned;
use std::future::Future;
use tracing::{debug, error};

/// Contract for implementing cache storage drivers
#[async_trait::async_trait]
pub trait CacheDriverContract: Send + Sync {
    /// Retrieves all keys present in the cache
    ///
    /// # Returns
    /// - `AppResult<Vec<String>>`: A vector containing all cache keys
    async fn keys(&self) -> AppResult<Vec<String>>;

    /// Retrieves all keys matching the specified pattern
    ///
    /// # Parameters
    /// - `pattern`: Pattern string to match keys against
    ///
    /// # Returns
    /// - `AppResult<Vec<String>>`: A vector of matching cache keys
    async fn keys_by_pattern(&self, pattern: &str) -> AppResult<Vec<String>>;

    /// Stores a raw string value in the cache
    ///
    /// # Parameters
    /// - `key`: Cache key to store the value under
    /// - `value`: String value to store
    ///
    /// # Returns
    /// - `AppResult<String>`: The stored string value
    async fn put_raw(&self, key: &str, value: String) -> AppResult<String>;

    /// Retrieves a raw string value from the cache
    ///
    /// # Parameters
    /// - `key`: Cache key to retrieve
    ///
    /// # Returns
    /// - `AppResult<Option<String>>`: The stored string value if it exists
    async fn get_raw(&self, key: &str) -> AppResult<Option<String>>;

    /// Removes a single key from the cache
    ///
    /// # Parameters
    /// - `key`: Cache key to remove
    ///
    /// # Returns
    /// - `AppResult<i32>`: Number of keys removed (typically 1 or 0)
    async fn forget(&self, key: &str) -> AppResult<i32>;

    /// Removes all keys matching the specified pattern
    ///
    /// # Parameters
    /// - `pattern`: Pattern string to match keys for removal
    ///
    /// # Returns
    /// - `AppResult<i32>`: Number of keys removed
    async fn forget_by_pattern(&self, pattern: &str) -> AppResult<i32>;
}

/// Extension trait providing serialization-aware caching operations
#[async_trait]
pub trait CacheDriverExt {
    /// Stores a serializable value in the cache
    ///
    /// # Parameters
    /// - `key`: Cache key to store the value under
    /// - `value`: Value to serialize and store
    ///
    /// # Returns
    /// - `AppResult<String>`: The stored JSON string
    ///
    /// # Type Parameters
    /// - `T`: Type that implements Serialize + Sync
    async fn put<T>(&self, key: &str, value: &T) -> AppResult<String>
    where
        T: Serialize + Sync;

    /// Retrieves and deserializes a value from the cache
    ///
    /// # Parameters
    /// - `key`: Cache key to retrieve
    ///
    /// # Returns
    /// - `AppResult<Option<T>>`: The deserialized value if it exists
    ///
    /// # Type Parameters
    /// - `T`: Type that implements DeserializeOwned + Sync
    async fn get<T>(&self, key: &str) -> AppResult<Option<T>>
    where
        T: DeserializeOwned + Sync;

    /// Gets a value from cache or computes and stores it if missing
    ///
    /// # Parameters
    /// - `key`: Cache key to retrieve or store under
    /// - `setter`: Function to compute the value if not in cache
    ///
    /// # Returns
    /// - `AppResult<Val>`: The retrieved or computed value
    ///
    /// # Type Parameters
    /// - `Val`: The value type that implements required traits
    /// - `Fun`: The setter function type
    /// - `Fut`: The future returned by the setter
    async fn get_or_put<Val, Fun, Fut>(&self, key: &str, setter: Fun) -> AppResult<Val>
    where
        Val: Serialize + DeserializeOwned + Clone + Sync + Send,
        Fun: FnOnce() -> Fut + Send,
        Fut: Future<Output = AppResult<Val>> + Send;
}

#[async_trait]
impl<T: ?Sized + CacheDriverContract + Sync> CacheDriverExt for T {
    async fn put<U>(&self, key: &str, value: &U) -> AppResult<String>
    where
        U: Serialize + Sync,
    {
        let json = serde_json::to_string(value)?;
        self.put_raw(key, json).await
    }

    async fn get<U>(&self, key: &str) -> AppResult<Option<U>>
    where
        U: DeserializeOwned + Sync,
    {
        let raw = self.get_raw(key).await?;
        Ok(match raw {
            None => None,
            Some(bytes) => Some(serde_json::from_str(&bytes)?),
        })
    }

    async fn get_or_put<Val, Fun, Fut>(&self, key: &str, setter: Fun) -> AppResult<Val>
    where
        Val: Serialize + DeserializeOwned + Sync + Send, // Removed Clone requirement
        Fun: FnOnce() -> Fut + Send,
        Fut: Future<Output = AppResult<Val>> + Send,
    {
        if let Some(val) = self.get::<Val>(key).await? {
            debug!("'{key}' collected from cache :)");
            return Ok(val);
        }

        debug!("'{key}' is missing in cache, executing setter()...");

        let val = setter().await?;

        // Store the value before returning to ensure cache consistency
        if let Err(e) = self.put(key, &val).await {
            error!("Failed to cache value for '{key}': {e:?}");
            return Err(e);
        }

        Ok(val)
    }
}