multi-tier-cache 0.6.7

Customizable multi-tier cache with L1 (Moka in-memory) + L2 (Redis distributed) defaults, expandable to L3/L4+, cross-instance invalidation via Pub/Sub, stampede protection, and flexible TTL scaling
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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
//! Basic integration tests for L1 and L2 cache operations
//!
//! These tests verify core functionality with real Redis instance.

mod common;

use common::*;
use multi_tier_cache::{CacheBackend, CacheStrategy};
use std::time::Duration;

/// Test basic cache set and get operations
#[tokio::test]
async fn test_basic_set_and_get() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("basic");
    let value = test_data::bytes_user(1);

    // Set value
    cache
        .cache_manager()
        .set_with_strategy(&key, value.clone(), CacheStrategy::ShortTerm)
        .await
        .unwrap_or_else(|_| panic!("Failed to set value"));

    // Get value
    let cached = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get value"));

    assert_eq!(cached, Some(value));

    // Cleanup
    let _ = cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .remove(&key)
        .await;
}

/// Test L1 hit path
#[tokio::test]
async fn test_l1_cache_hit() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("l1_hit");
    let value = test_data::bytes_user(2);

    // Set value (populates L1)
    cache
        .cache_manager()
        .set_with_strategy(&key, value.clone(), CacheStrategy::MediumTerm)
        .await
        .unwrap_or_else(|_| panic!("Failed to set cache"));

    // First get - should hit L1
    let _ = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache"));

    // Second get - should also hit L1
    let cached = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache"));
    assert_eq!(cached, Some(value));

    // Verify L1 hits
    let stats = cache.cache_manager().get_stats();
    assert!(stats.l1_hits >= 1, "Expected at least 1 L1 hit");

    // Cleanup
    let _ = cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .remove(&key)
        .await;
}

/// Test L2-to-L1 promotion
#[tokio::test]
async fn test_l2_to_l1_promotion() {
    let cache = setup_cache_with_n(1)
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("l2_promote");
    let value = test_data::bytes_user(3);

    // Set directly in L2 (bypass L1)
    cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .set_with_ttl(&key, value.clone(), Duration::from_secs(300))
        .await
        .unwrap_or_else(|_| panic!("Failed to set L2"));

    // Get from cache manager - should promote to L1
    let cached = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache"));
    assert_eq!(cached, Some(value.clone()));

    // Verify promotion occurred
    let stats = cache.cache_manager().get_stats();
    assert!(stats.promotions >= 1, "Expected at least 1 promotion");

    // Next get should hit L1
    let cached2 = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache"));
    assert_eq!(cached2, Some(value));

    // Cleanup
    let _ = cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .remove(&key)
        .await;
}

/// Test cache miss behavior
#[tokio::test]
async fn test_cache_miss() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("miss");

    // Get non-existent key
    let cached = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache"));
    assert_eq!(cached, None);

    // Verify miss was counted
    let stats = cache.cache_manager().get_stats();
    assert!(stats.misses >= 1, "Expected at least 1 miss");
}

/// Test compute-on-miss pattern
#[tokio::test]
async fn test_compute_on_miss() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("compute");
    let expected_value = test_data::bytes_user(4);

    // Compute on miss
    let value = cache
        .cache_manager()
        .get_or_compute_with(&key, CacheStrategy::ShortTerm, || {
            let v = expected_value.clone();
            async move { Ok(v) }
        })
        .await
        .unwrap_or_else(|_| panic!("Failed to get/compute"));

    assert_eq!(value, expected_value);

    // Verify it's now cached
    let cached = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache"));
    assert_eq!(cached, Some(expected_value));

    // Cleanup
    let _ = cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .remove(&key)
        .await;
}

/// Test type-safe caching
#[tokio::test]
async fn test_type_safe_caching() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("typed");
    let expected_user = test_data::User::new(5);

    // Store and retrieve with type safety
    let user: test_data::User = cache
        .cache_manager()
        .get_or_compute_typed(&key, CacheStrategy::MediumTerm, || {
            let u = expected_user.clone();
            async move { Ok(u) }
        })
        .await
        .unwrap_or_else(|_| panic!("Failed to get/compute typed"));

    assert_eq!(user, expected_user);

    // Verify it's cached
    let user2: test_data::User = cache
        .cache_manager()
        .get_or_compute_typed(&key, CacheStrategy::MediumTerm, || async {
            panic!("Should not compute again");
        })
        .await
        .unwrap_or_else(|_| panic!("Failed to get/compute typed"));

    assert_eq!(user2, expected_user);

    // Cleanup
    let _ = cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .remove(&key)
        .await;
}

/// Test TTL expiration
#[tokio::test]
async fn test_ttl_expiration() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("ttl");
    let value = test_data::bytes_user(6);

    // Set with very short TTL
    cache
        .cache_manager()
        .set_with_strategy(
            &key,
            value.clone(),
            CacheStrategy::Custom(Duration::from_millis(100)),
        )
        .await
        .unwrap_or_else(|_| panic!("Failed to set cache"));

    // Immediate get should work
    let cached = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache"));
    assert_eq!(cached, Some(value.clone()));

    // Wait for expiration
    tokio::time::sleep(Duration::from_millis(200)).await;

    // Should be expired now
    let cached2 = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache"));
    assert_eq!(cached2, None);

    // Cleanup
    let _ = cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .remove(&key)
        .await;
}

/// Test cache statistics tracking
#[tokio::test]
async fn test_statistics_tracking() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("stats");
    let value = test_data::bytes_user(7);

    // Initial stats
    let stats_before = cache.cache_manager().get_stats();

    // Perform operations
    cache
        .cache_manager()
        .set_with_strategy(&key, value, CacheStrategy::ShortTerm)
        .await
        .unwrap_or_else(|_| panic!("Failed to set cache"));

    let _ = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache")); // L1 hit
    let _ = cache
        .cache_manager()
        .get(&test_key("nonexistent"))
        .await
        .unwrap_or_else(|_| panic!("Failed to get cache")); // Miss

    // Check stats increased
    let stats_after = cache.cache_manager().get_stats();
    assert!(stats_after.total_requests > stats_before.total_requests);
    assert!(
        stats_after.l1_hits > stats_before.l1_hits || stats_after.l2_hits > stats_before.l2_hits
    );
    assert!(stats_after.misses > stats_before.misses);

    // Cleanup
    let _ = cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .remove(&key)
        .await;
}

/// Test health check functionality
#[tokio::test]
async fn test_health_check() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));

    let healthy = cache.health_check().await;
    assert!(healthy, "Cache system should be healthy");
}

/// Test different cache strategies
#[tokio::test]
async fn test_cache_strategies() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));

    let strategies = vec![
        ("realtime", CacheStrategy::RealTime),
        ("short", CacheStrategy::ShortTerm),
        ("medium", CacheStrategy::MediumTerm),
        ("long", CacheStrategy::LongTerm),
        ("custom", CacheStrategy::Custom(Duration::from_secs(60))),
    ];

    for (name, strategy) in strategies {
        let key = test_key(name);
        let value = test_data::bytes_user(8);

        cache
            .cache_manager()
            .set_with_strategy(&key, value.clone(), strategy)
            .await
            .unwrap_or_else(|_| panic!("Failed to set with {name} strategy"));

        let cached = cache
            .cache_manager()
            .get(&key)
            .await
            .unwrap_or_else(|_| panic!("Failed to get with {name} strategy"));

        assert_eq!(cached, Some(value));

        // Cleanup
        let _ = cache
            .l2_cache
            .as_ref()
            .unwrap_or_else(|| panic!("L2 cache missing"))
            .remove(&key)
            .await;
    }
}

/// Test negative caching (caching empty bytes)
#[tokio::test]
async fn test_negative_caching() {
    let cache = setup_cache_system()
        .await
        .unwrap_or_else(|_| panic!("Failed to setup cache"));
    let key = test_key("negative_caching");
    let empty_value = bytes::Bytes::new();

    // Store empty bytes
    cache
        .cache_manager()
        .set_with_strategy(&key, empty_value.clone(), CacheStrategy::ShortTerm)
        .await
        .unwrap_or_else(|_| panic!("Failed to set empty cache"));

    // Retrieve - should be a hit returning empty bytes (not None)
    let cached = cache
        .cache_manager()
        .get(&key)
        .await
        .unwrap_or_else(|_| panic!("Failed to get empty cache"));
    assert_eq!(cached, Some(empty_value.clone()));

    // Retrieve via get_or_compute_with - should NOT compute again
    let mut computed_count = 0;
    let cached_or_computed = cache
        .cache_manager()
        .get_or_compute_with(&key, CacheStrategy::ShortTerm, || async {
            computed_count += 1;
            Ok(bytes::Bytes::from("should not compute"))
        })
        .await
        .unwrap_or_else(|_| panic!("Failed to get or compute empty cache"));
    assert_eq!(cached_or_computed, empty_value);
    assert_eq!(
        computed_count, 0,
        "Compute function was called, bypassing negative cache hit!"
    );

    // Cleanup
    let _ = cache
        .l2_cache
        .as_ref()
        .unwrap_or_else(|| panic!("L2 cache missing"))
        .remove(&key)
        .await;
}