multi_tier_cache/
traits.rs

1//! Cache Backend Traits
2//!
3//! This module defines the trait abstractions that allow users to implement
4//! custom cache backends for both L1 (in-memory) and L2 (distributed) caches.
5//!
6//! # Architecture
7//!
8//! - `CacheBackend`: Core trait for all cache implementations
9//! - `L2CacheBackend`: Extended trait for L2 caches with TTL introspection
10//! - `StreamingBackend`: Optional trait for event streaming capabilities
11//!
12//! # Example: Custom L1 Backend
13//!
14/// ```rust,no_run
15/// use anyhow::Result;
16/// use bytes::Bytes;
17/// use std::time::Duration;
18/// use futures_util::future::BoxFuture;
19/// use multi_tier_cache::CacheBackend;
20///
21/// struct MyCustomCache;
22///
23/// impl CacheBackend for MyCustomCache {
24///     fn get<'a>(&'a self, _key: &'a str) -> BoxFuture<'a, Option<Bytes>> {
25///         Box::pin(async move { None })
26///     }
27///
28///     fn set_with_ttl<'a>(&'a self, _key: &'a str, _value: Bytes, _ttl: Duration) -> BoxFuture<'a, Result<()>> {
29///         Box::pin(async move { Ok(()) })
30///     }
31///
32///     fn remove<'a>(&'a self, _key: &'a str) -> BoxFuture<'a, Result<()>> {
33///         Box::pin(async move { Ok(()) })
34///     }
35///
36///     fn health_check(&self) -> BoxFuture<'_, bool> {
37///         Box::pin(async move { true })
38///     }
39///
40///     fn name(&self) -> &'static str { "MyCache" }
41/// }
42/// ```
43use anyhow::Result;
44use bytes::Bytes;
45use futures_util::future::BoxFuture;
46use std::time::Duration;
47
48/// Core cache backend trait for both L1 and L2 caches
49///
50/// This trait defines the essential operations that any cache backend must support.
51/// Implement this trait to create custom L1 (in-memory) or L2 (distributed) cache backends.
52///
53/// # Required Operations
54///
55/// - `get`: Retrieve a value by key
56/// - `set_with_ttl`: Store a value with a time-to-live
57/// - `remove`: Delete a value by key
58/// - `health_check`: Verify cache backend is operational
59///
60/// # Thread Safety
61///
62/// Implementations must be `Send + Sync` to support concurrent access across async tasks.
63///
64/// # Performance Considerations
65///
66/// - `get` operations should be optimized for low latency (target: <1ms for L1, <5ms for L2)
67/// - `set_with_ttl` operations can be slightly slower but should still be fast
68/// - Consider connection pooling for distributed backends
69///
70/// # Example
71///
72/// See module-level documentation for a complete example.
73pub trait CacheBackend: Send + Sync {
74    /// Get value from cache by key
75    ///
76    /// # Arguments
77    ///
78    /// * `key` - The cache key to retrieve
79    ///
80    /// # Returns
81    ///
82    /// * `Some(value)` - Value found in cache
83    /// * `None` - Key not found or expired
84    fn get<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Option<Bytes>>;
85
86    /// Set value in cache with time-to-live
87    ///
88    /// # Arguments
89    ///
90    /// * `key` - The cache key
91    /// * `value` - The value to store (raw bytes)
92    /// * `ttl` - Time-to-live duration
93    ///
94    /// # Returns
95    ///
96    /// * `Ok(())` - Value successfully cached
97    /// * `Err(e)` - Cache operation failed
98    fn set_with_ttl<'a>(
99        &'a self,
100        key: &'a str,
101        value: Bytes,
102        ttl: Duration,
103    ) -> BoxFuture<'a, Result<()>>;
104
105    /// Remove value from cache
106    ///
107    /// # Arguments
108    ///
109    /// * `key` - The cache key to remove
110    ///
111    /// # Returns
112    ///
113    /// * `Ok(())` - Value removed (or didn't exist)
114    /// * `Err(e)` - Cache operation failed
115    fn remove<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<()>>;
116
117    /// Check if cache backend is healthy
118    ///
119    /// This method should verify that the cache backend is operational.
120    /// For distributed caches, this typically involves a ping or connectivity check.
121    ///
122    /// # Returns
123    ///
124    /// * `true` - Cache is healthy and operational
125    /// * `false` - Cache is unhealthy or unreachable
126    fn health_check(&self) -> BoxFuture<'_, bool>;
127
128    /// Remove keys matching a pattern
129    ///
130    /// # Arguments
131    ///
132    /// * `pattern` - Glob-style pattern (e.g. "user:*")
133    ///
134    /// # Returns
135    ///
136    /// * `Ok(())` - Pattern processed
137    /// * `Err(e)` - Operation failed
138    fn remove_pattern<'a>(&'a self, _pattern: &'a str) -> BoxFuture<'a, Result<()>> {
139        Box::pin(async { Ok(()) })
140    }
141
142    /// Get the name of this cache backend
143    fn name(&self) -> &'static str;
144}
145
146// (No longer needed since traits are now dyn-compatible)
147
148/// Extended trait for L2 cache backends with TTL introspection
149///
150/// This trait extends `CacheBackend` with the ability to retrieve both a value
151/// and its remaining TTL. This is essential for implementing efficient L2-to-L1
152/// promotion with accurate TTL propagation.
153///
154/// # Use Cases
155///
156/// - L2-to-L1 promotion with same TTL
157/// - TTL-based cache warming strategies
158/// - Monitoring and analytics
159///
160/// # Example
161///
162/// ```rust,no_run
163/// use anyhow::Result;
164/// use bytes::Bytes;
165/// use std::time::Duration;
166/// use futures_util::future::BoxFuture;
167/// use multi_tier_cache::{CacheBackend, L2CacheBackend};
168///
169/// struct MyDistributedCache;
170///
171/// impl CacheBackend for MyDistributedCache {
172///     fn get<'a>(&'a self, _key: &'a str) -> BoxFuture<'a, Option<Bytes>> { Box::pin(async move { None }) }
173///     fn set_with_ttl<'a>(&'a self, _k: &'a str, _v: Bytes, _t: Duration) -> BoxFuture<'a, Result<()>> { Box::pin(async move { Ok(()) }) }
174///     fn remove<'a>(&'a self, _k: &'a str) -> BoxFuture<'a, Result<()>> { Box::pin(async move { Ok(()) }) }
175///     fn health_check(&self) -> BoxFuture<'_, bool> { Box::pin(async move { true }) }
176///     fn name(&self) -> &'static str { "MyDistCache" }
177/// }
178///
179/// impl L2CacheBackend for MyDistributedCache {
180///     fn get_with_ttl<'a>(&'a self, _key: &'a str) -> BoxFuture<'a, Option<(Bytes, Option<Duration>)>> {
181///         Box::pin(async move { None })
182///     }
183/// }
184/// ```
185pub trait L2CacheBackend: CacheBackend {
186    /// Get value with its remaining TTL from L2 cache
187    fn get_with_ttl<'a>(&'a self, key: &'a str)
188    -> BoxFuture<'a, Option<(Bytes, Option<Duration>)>>;
189}
190
191// (No longer needed since traits are now dyn-compatible)
192
193/// Optional trait for cache backends that support event streaming
194///
195/// # Type Definitions
196///
197/// * `StreamEntry` - A single entry in a stream: `(id, fields)` where fields are `Vec<(key, value)>`
198pub type StreamEntry = (String, Vec<(String, String)>);
199
200/// Optional trait for cache backends that support event streaming
201///
202/// This trait defines operations for event-driven architectures using
203/// streaming data structures like Redis Streams.
204///
205/// # Capabilities
206///
207/// - Publish events to streams with automatic trimming
208/// - Read latest entries (newest first)
209/// - Read entries with blocking support
210///
211/// # Backend Requirements
212///
213/// Not all cache backends support streaming. This trait is optional and
214/// should only be implemented by backends with native streaming support
215/// (e.g., Redis Streams, Kafka, Pulsar).
216///
217/// # Example
218///
219/// ```rust,no_run
220/// use multi_tier_cache::StreamingBackend;
221/// use anyhow::Result;
222/// use futures_util::future::BoxFuture;
223///
224/// struct MyStreamingCache;
225///
226/// impl StreamingBackend for MyStreamingCache {
227///     fn stream_add<'a>(
228///         &'a self,
229///         _stream_key: &'a str,
230///         _fields: Vec<(String, String)>,
231///         _maxlen: Option<usize>,
232///     ) -> BoxFuture<'a, Result<String>> {
233///         Box::pin(async move { Ok("entry-id".to_string()) })
234///     }
235///
236///     fn stream_read_latest<'a>(
237///         &'a self,
238///         _stream_key: &'a str,
239///         _count: usize,
240///     ) -> BoxFuture<'a, Result<Vec<(String, Vec<(String, String)>)>>> {
241///         Box::pin(async move { Ok(vec![]) })
242///     }
243///
244///     fn stream_read<'a>(
245///         &'a self,
246///         _stream_key: &'a str,
247///         _last_id: &'a str,
248///         _count: usize,
249///         _block_ms: Option<usize>,
250///     ) -> BoxFuture<'a, Result<Vec<(String, Vec<(String, String)>)>>> {
251///         Box::pin(async move { Ok(vec![]) })
252///     }
253/// }
254/// ```
255pub trait StreamingBackend: Send + Sync {
256    /// Add an entry to a stream
257    fn stream_add<'a>(
258        &'a self,
259        stream_key: &'a str,
260        fields: Vec<(String, String)>,
261        maxlen: Option<usize>,
262    ) -> BoxFuture<'a, Result<String>>;
263
264    /// Read the latest N entries from a stream (newest first)
265    fn stream_read_latest<'a>(
266        &'a self,
267        stream_key: &'a str,
268        count: usize,
269    ) -> BoxFuture<'a, Result<Vec<StreamEntry>>>;
270
271    /// Read entries from a stream with optional blocking
272    fn stream_read<'a>(
273        &'a self,
274        stream_key: &'a str,
275        last_id: &'a str,
276        count: usize,
277        block_ms: Option<usize>,
278    ) -> BoxFuture<'a, Result<Vec<StreamEntry>>>;
279}
multi_tier_cache/traits.rs

multi_tier_cache/
traits.rs
