imc 0.1.0

Trait-based, deduplicating, in-memory caching library for Rust
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

use std::hash::Hash;
use std::time::Duration;

use crate::hasher::hash_value;

/// Marker trait for cache keys whose updates should be broadcast
/// to other pods via Redis pub/sub.
///
/// Derive this on your key enum with [`#[derive(CriticalKey)]`](imc_derive::CriticalKey)
/// to automatically invalidate the corresponding cache entry across all
/// pods whenever [`through_imc_keyed`](crate::through_imc_keyed) stores a
/// new value for that key.
///
/// Requires the `critical` feature.
///
/// # Example
///
/// ```ignore
/// #[derive(Hash, Clone, CriticalKey)]
/// enum UserKey { ById(i32), ByEmail(String) }
/// ```
#[cfg(feature = "critical")]
pub trait CriticalKey: Hash + Clone + Send + 'static {
    /// Pub/sub channel name for this key type.
    ///
    /// The derive macro generates this automatically from
    /// `module_path!() + "::" + type_name`.
    fn channel() -> &'static str;
}

/// Eviction strategy for a per-type cache namespace.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum CacheStrategy {
    /// Evict the entry accessed **least recently**.
    Lru,
    /// Evict the entry accessed **most recently**.
    Mru,
    /// Evict the entry accessed **least frequently**.
    Lfu,
    /// Evict the entry accessed **most frequently**.
    Mfu,
    /// Evict the entry that was inserted **earliest** (FIFO).
    Fifo,
}

/// Any type that should be cacheable **must** implement this trait.
///
/// Implementors define:
/// - a unique identifier (`Id`) extracted via [`cache_id`](ImcCacheable::cache_id)
/// - the eviction strategy, TTL and max-size for the type
///
/// # Example
///
/// ```ignore
/// #[derive(Clone)]
/// struct User { id: u32, name: String }
///
/// impl ImcCacheable for User {
///     type Id = u32;
///     fn cache_id(&self) -> u32 { self.id }
///     fn cache_ttl() -> Option<Duration> { Some(Duration::from_secs(300)) }
/// }
/// ```
pub trait ImcCacheable: Clone + Send + Sync + 'static {
    /// The unique-identifier type for this data (e.g. a primary key).
    type Id: Hash + Eq + Clone + Send + 'static;

    /// Typed cache key for use with [`through_imc_keyed`](crate::through_imc_keyed).
    ///
    /// All types must specify this (typically `type Key = String;`).  Override
    /// with a closed enum to make invalid cache keys a compile-time error.
    type Key: Hash + Clone + Send + 'static;

    /// Extract the unique identifier from a value *after* it has been
    /// fetched.  This is used internally to deduplicate entries.
    fn cache_id(&self) -> Self::Id;

    // ── Optional defaults ──────────────────────────────────────────────

    /// Eviction strategy for this type's cache namespace.
    fn cache_strategy() -> CacheStrategy { CacheStrategy::Lru }

    /// Time-to-live for cached values.  `None` means they never expire.
    fn cache_ttl() -> Option<Duration> { None }

    /// Maximum number of entries allowed in this type's namespace.
    fn cache_max_size() -> usize { 10_000 }

    /// Optional: return the approximate byte-size of `self` for the
    /// per-value size limit check.  When `Some(s)` is returned and
    /// `s > cache_max_value_size()` the value is returned directly
    /// without caching.  `None` means "unknown — always cache".
    ///
    /// ```ignore
    /// fn cache_value_size(&self) -> Option<usize> {
    ///     Some(std::mem::size_of_val(self) + self.name.len())
    /// }
    /// ```
    fn cache_value_size(&self) -> Option<usize> { None }

    /// Maximum byte-size of a single cached value.  Values whose
    /// [`cache_value_size()`](ImcCacheable::cache_value_size) exceeds
    /// this are not stored (they bypass the cache).
    /// Default: 1 MiB.
    fn cache_max_value_size() -> usize { 1_048_576 }

    /// Optional: return a pub/sub channel name to enable cross-process
    /// cache invalidation for this type. Requires the `invalidation-redis`
    /// feature and a [`CacheWorker`](crate::worker::CacheWorker) with
    /// [`WorkerConfig::redis_connection_string`](crate::worker::WorkerConfig) configured.
    fn cache_invalidation_channel() -> Option<&'static str> { None }
}

// ---------------------------------------------------------------------------
// Blanket impl for Vec<T> — cache entire result sets
// ---------------------------------------------------------------------------

impl<T: ImcCacheable> ImcCacheable for Vec<T> {
    type Id = String;
    type Key = String;

    fn cache_id(&self) -> String {
        let ids: Vec<T::Id> = self.iter().map(|e| e.cache_id()).collect();
        hash_value(&ids).to_string()
    }

    fn cache_strategy() -> CacheStrategy { T::cache_strategy() }
    fn cache_ttl() -> Option<Duration> { T::cache_ttl() }
    fn cache_max_size() -> usize { T::cache_max_size() }
    fn cache_invalidation_channel() -> Option<&'static str> { None }
    fn cache_value_size(&self) -> Option<usize> {
        let elem: Option<usize> = self.iter().try_fold(0usize, |acc, e| {
            e.cache_value_size().map(|s| acc + s)
        });
        elem.map(|s| s + self.capacity() * std::mem::size_of::<T>())
    }
    fn cache_max_value_size() -> usize { T::cache_max_value_size() }
}