Skip to main content

redis_tower/
cache_state.rs

1//! Shared state and helpers for client-side caching.
2//!
3//! Both [`CachedClient`](crate::caching::CachedClient) and the Tower
4//! [`CacheService`](crate::cache_layer::CacheService) use this so their
5//! cache-key derivation and invalidation can never diverge.
6//!
7//! Cache keys are the **full** command argument vector, length-prefixed and
8//! binary-safe -- so `HGET h f1` and `HGET h f2` are distinct entries rather
9//! than colliding on `HGET:h`. A reverse index maps each Redis key to the cache
10//! entries that depend on it, so a single invalidation evicts every variant in
11//! O(1) lookups instead of an O(n) suffix scan that over-evicts.
12
13use std::collections::{HashMap, HashSet};
14use std::sync::Arc;
15use std::sync::atomic::{AtomicU64, Ordering};
16use std::time::{Duration, Instant};
17
18use redis_tower_core::Frame;
19
20use crate::metrics_layer::{CacheEvent, MetricsRecorder};
21
22/// Default maximum number of cached entries (memory bound).
23pub(crate) const DEFAULT_MAX_ENTRIES: usize = 10_000;
24/// Default per-entry client-side freshness deadline. A cached entry older than
25/// this is treated as a miss even if no invalidation arrived -- a safety
26/// backstop against missed invalidations (Redis CSC guidance).
27pub(crate) const DEFAULT_TTL: Duration = Duration::from_secs(30);
28/// Maximum number of per-key invalidation epochs retained when the cache itself
29/// is configured as unbounded. Epoch pruning advances the global generation,
30/// so dropping bookkeeping can never make an old in-flight read current again.
31const DEFAULT_MAX_EPOCHS: usize = DEFAULT_MAX_ENTRIES;
32
33/// The cacheable read commands. The key these read is always argument 1.
34///
35/// `TTL` is intentionally excluded: its reply is a countdown that is wrong the
36/// instant it is cached.
37const CACHEABLE: &[&[u8]] = &[
38    b"GET",
39    b"HGET",
40    b"HGETALL",
41    b"LRANGE",
42    b"SMEMBERS",
43    b"ZRANGE",
44    b"TYPE",
45];
46
47/// Append `arg` to `buf` with a 4-byte length prefix, so a concatenation of
48/// arguments is unambiguous regardless of the bytes inside any argument.
49fn push_arg(buf: &mut Vec<u8>, arg: &[u8]) {
50    buf.extend_from_slice(&(arg.len() as u32).to_le_bytes());
51    buf.extend_from_slice(arg);
52}
53
54/// For a cacheable read command frame, return `(cache_key, redis_key)`:
55///
56/// - `cache_key` identifies the exact command + arguments (binary-safe).
57/// - `redis_key` is the Redis key the command reads, used for the reverse
58///   index so invalidation of that key evicts this entry.
59///
60/// Returns `None` for non-cacheable commands or malformed frames.
61#[doc(hidden)]
62pub fn extract_cache_entry(frame: &Frame) -> Option<(Vec<u8>, Vec<u8>)> {
63    let items = match frame {
64        Frame::Array(Some(items)) if items.len() >= 2 => items,
65        _ => return None,
66    };
67
68    let cmd_name = match &items[0] {
69        Frame::BulkString(Some(b)) => b.as_ref(),
70        _ => return None,
71    };
72    let upper: Vec<u8> = cmd_name.iter().map(|b| b.to_ascii_uppercase()).collect();
73    if !CACHEABLE.contains(&upper.as_slice()) {
74        return None;
75    }
76
77    let redis_key = match &items[1] {
78        Frame::BulkString(Some(b)) => b.to_vec(),
79        _ => return None,
80    };
81
82    // Cache key = uppercased command name + every argument, length-prefixed.
83    let mut cache_key = Vec::new();
84    push_arg(&mut cache_key, &upper);
85    for item in &items[1..] {
86        match item {
87            Frame::BulkString(Some(b)) => push_arg(&mut cache_key, b.as_ref()),
88            // A non-bulk argument can't be keyed safely; don't cache.
89            _ => return None,
90        }
91    }
92
93    Some((cache_key, redis_key))
94}
95
96/// Parse a server invalidation push message into the affected key bytes.
97///
98/// Returns `Some(vec![])` for a flush-everything invalidation (null payload),
99/// `Some(keys)` for specific keys, or `None` if the frame is not an
100/// `invalidate` message. Keys are raw bytes (binary-safe).
101#[doc(hidden)]
102pub fn parse_invalidation(frame: &Frame) -> Option<Vec<Vec<u8>>> {
103    let items = match frame {
104        Frame::Push(items) if !items.is_empty() => items,
105        Frame::Array(Some(items)) if !items.is_empty() => items,
106        _ => return None,
107    };
108
109    match &items[0] {
110        Frame::BulkString(Some(b)) | Frame::SimpleString(b) if b.as_ref() == b"invalidate" => {}
111        _ => return None,
112    }
113
114    match items.get(1) {
115        Some(Frame::Array(Some(keys))) => {
116            let mut result = Vec::new();
117            for key in keys {
118                let bytes = match key {
119                    Frame::BulkString(Some(b)) | Frame::SimpleString(b) => b,
120                    // The message is recognizably an invalidation but its key
121                    // payload is malformed. Flush instead of risking a stale
122                    // entry by applying only a partial key list.
123                    _ => return Some(Vec::new()),
124                };
125                result.push(bytes.to_vec());
126            }
127            Some(result)
128        }
129        Some(Frame::Null | Frame::Array(None)) => Some(Vec::new()),
130        // Once the frame is recognizably an invalidation, any missing or
131        // malformed payload must flush rather than be ignored.
132        _ => Some(Vec::new()),
133    }
134}
135
136/// Commands known not to mutate Redis keyspace. Unknown commands are treated
137/// as mutations by [`command_invalidation`] so new Redis/module commands remain
138/// correct until explicitly classified.
139const READ_ONLY_COMMANDS: &[&[u8]] = &[
140    b"BITCOUNT",
141    b"BITFIELD_RO",
142    b"BITPOS",
143    b"COMMAND",
144    b"DBSIZE",
145    b"DUMP",
146    b"ECHO",
147    b"EXISTS",
148    b"EXPIRETIME",
149    b"FCALL_RO",
150    b"FT.AGGREGATE",
151    b"FT.EXPLAIN",
152    b"FT.EXPLAINCLI",
153    b"FT.INFO",
154    b"FT.PROFILE",
155    b"FT.SEARCH",
156    b"GEOHASH",
157    b"GEOPOS",
158    b"GEODIST",
159    b"GEOSEARCH",
160    b"GET",
161    b"GETBIT",
162    b"GETRANGE",
163    b"HEXISTS",
164    b"HGET",
165    b"HGETALL",
166    b"HKEYS",
167    b"HLEN",
168    b"HMGET",
169    b"HRANDFIELD",
170    b"HSCAN",
171    b"HSTRLEN",
172    b"HVALS",
173    b"INFO",
174    b"KEYS",
175    b"LATENCY",
176    b"LINDEX",
177    b"LLEN",
178    b"LPOS",
179    b"LRANGE",
180    b"MEMORY",
181    b"MGET",
182    b"OBJECT",
183    b"PEXPIRETIME",
184    b"PFCOUNT",
185    b"PING",
186    b"PTTL",
187    b"PUBSUB",
188    b"PUBLISH",
189    b"RANDOMKEY",
190    b"ROLE",
191    b"SCAN",
192    b"SCARD",
193    b"SDIFF",
194    b"SINTER",
195    b"SINTERCARD",
196    b"SISMEMBER",
197    b"SMEMBERS",
198    b"SMISMEMBER",
199    b"SORT_RO",
200    b"SRANDMEMBER",
201    b"SSCAN",
202    b"STRLEN",
203    b"SUNION",
204    b"TIME",
205    b"TTL",
206    b"TYPE",
207    b"WAIT",
208    b"WAITAOF",
209    b"XINFO",
210    b"XLEN",
211    b"XPENDING",
212    b"XRANGE",
213    b"XREAD",
214    b"XREVRANGE",
215    b"ZCARD",
216    b"ZCOUNT",
217    b"ZDIFF",
218    b"ZINTER",
219    b"ZINTERCARD",
220    b"ZLEXCOUNT",
221    b"ZMSCORE",
222    b"ZRANDMEMBER",
223    b"ZRANGE",
224    b"ZRANGEBYLEX",
225    b"ZRANGEBYSCORE",
226    b"ZRANK",
227    b"ZREVRANGE",
228    b"ZREVRANGEBYLEX",
229    b"ZREVRANGEBYSCORE",
230    b"ZREVRANK",
231    b"ZSCAN",
232    b"ZSCORE",
233    b"ZUNION",
234    b"JSON.ARRINDEX",
235    b"JSON.ARRLEN",
236    b"JSON.DEBUG",
237    b"JSON.GET",
238    b"JSON.MGET",
239    b"JSON.OBJKEYS",
240    b"JSON.OBJLEN",
241    b"JSON.RESP",
242    b"JSON.STRLEN",
243    b"JSON.TYPE",
244];
245
246/// Mutations whose first argument is the only Redis key they change.
247const FIRST_KEY_MUTATIONS: &[&[u8]] = &[
248    b"APPEND",
249    b"BITFIELD",
250    b"DECR",
251    b"DECRBY",
252    b"EXPIRE",
253    b"EXPIREAT",
254    b"GETDEL",
255    b"GETEX",
256    b"GETSET",
257    b"GEOADD",
258    b"HDEL",
259    b"HINCRBY",
260    b"HINCRBYFLOAT",
261    b"HMSET",
262    b"HSET",
263    b"HSETNX",
264    b"INCR",
265    b"INCRBY",
266    b"INCRBYFLOAT",
267    b"LINSERT",
268    b"LPOP",
269    b"LPUSH",
270    b"LPUSHX",
271    b"LREM",
272    b"LSET",
273    b"LTRIM",
274    b"PERSIST",
275    b"PEXPIRE",
276    b"PEXPIREAT",
277    b"PFADD",
278    b"PSETEX",
279    b"RESTORE",
280    b"RPOP",
281    b"RPUSH",
282    b"RPUSHX",
283    b"SADD",
284    b"SREM",
285    b"SET",
286    b"SETBIT",
287    b"SETEX",
288    b"SETNX",
289    b"SETRANGE",
290    b"SPOP",
291    b"XACK",
292    b"XADD",
293    b"XAUTOCLAIM",
294    b"XCLAIM",
295    b"XDEL",
296    b"XSETID",
297    b"XTRIM",
298    b"ZADD",
299    b"ZINCRBY",
300    b"ZPOPMAX",
301    b"ZPOPMIN",
302    b"ZREM",
303    b"ZREMRANGEBYLEX",
304    b"ZREMRANGEBYRANK",
305    b"ZREMRANGEBYSCORE",
306    b"JSON.ARRAPPEND",
307    b"JSON.ARRINSERT",
308    b"JSON.ARRPOP",
309    b"JSON.ARRTRIM",
310    b"JSON.CLEAR",
311    b"JSON.DEL",
312    b"JSON.FORGET",
313    b"JSON.MERGE",
314    b"JSON.NUMINCRBY",
315    b"JSON.NUMMULTBY",
316    b"JSON.SET",
317    b"JSON.STRAPPEND",
318    b"JSON.TOGGLE",
319];
320
321enum CommandInvalidation {
322    None,
323    Keys(Vec<Vec<u8>>),
324    Clear,
325}
326
327fn bulk_arg(frame: &Frame) -> Option<&[u8]> {
328    match frame {
329        Frame::BulkString(Some(value)) => Some(value.as_ref()),
330        _ => None,
331    }
332}
333
334/// Return the connection-local command reserved by managed cached clients.
335///
336/// These commands can disable tracking, change RESP protocol/reply semantics,
337/// or close/reset the data connection. Cached clients reject them before
338/// dispatch so callers cannot silently invalidate the owned lifecycle.
339#[doc(hidden)]
340pub fn managed_cache_state_command(frame: &Frame) -> Option<&'static str> {
341    let items = match frame {
342        Frame::Array(Some(items)) if !items.is_empty() => items,
343        _ => return None,
344    };
345    let command = bulk_arg(&items[0])?;
346
347    if command.eq_ignore_ascii_case(b"RESET") {
348        return Some("RESET");
349    }
350    if command.eq_ignore_ascii_case(b"HELLO") {
351        return Some("HELLO");
352    }
353    if command.eq_ignore_ascii_case(b"QUIT") {
354        return Some("QUIT");
355    }
356    if !command.eq_ignore_ascii_case(b"CLIENT") {
357        return None;
358    }
359
360    let subcommand = items.get(1).and_then(bulk_arg)?;
361    if subcommand.eq_ignore_ascii_case(b"TRACKING") {
362        Some("CLIENT TRACKING")
363    } else if subcommand.eq_ignore_ascii_case(b"CACHING") {
364        Some("CLIENT CACHING")
365    } else if subcommand.eq_ignore_ascii_case(b"REPLY") {
366        Some("CLIENT REPLY")
367    } else {
368        None
369    }
370}
371
372fn command_invalidation(frame: &Frame) -> CommandInvalidation {
373    let items = match frame {
374        Frame::Array(Some(items)) if !items.is_empty() => items,
375        _ => return CommandInvalidation::Clear,
376    };
377    let Some(command) = bulk_arg(&items[0]) else {
378        return CommandInvalidation::Clear;
379    };
380    let command: Vec<u8> = command.iter().map(u8::to_ascii_uppercase).collect();
381
382    if READ_ONLY_COMMANDS.contains(&command.as_slice()) {
383        return CommandInvalidation::None;
384    }
385
386    if FIRST_KEY_MUTATIONS.contains(&command.as_slice()) {
387        return items
388            .get(1)
389            .and_then(bulk_arg)
390            .map(|key| CommandInvalidation::Keys(vec![key.to_vec()]))
391            .unwrap_or(CommandInvalidation::Clear);
392    }
393
394    match command.as_slice() {
395        // XGROUP's first argument is the subcommand; its stream key is the
396        // second argument. In particular, CREATE ... MKSTREAM can change a
397        // cached TYPE response from `none` to `stream`.
398        b"XGROUP" => items
399            .get(2)
400            .and_then(bulk_arg)
401            .map(|key| CommandInvalidation::Keys(vec![key.to_vec()]))
402            .unwrap_or(CommandInvalidation::Clear),
403
404        // Every remaining argument is a key.
405        b"DEL" | b"UNLINK" => collect_keys(&items[1..]),
406
407        // Alternating key/value pairs.
408        b"MSET" | b"MSETNX" => {
409            if items.len() < 3 || items.len().is_multiple_of(2) {
410                return CommandInvalidation::Clear;
411            }
412            collect_keys(items[1..].iter().step_by(2))
413        }
414
415        // Both endpoints can change.
416        b"RENAME" | b"RENAMENX" | b"LMOVE" | b"BLMOVE" | b"RPOPLPUSH" | b"BRPOPLPUSH"
417        | b"SMOVE" => collect_keys(items.iter().skip(1).take(2)),
418
419        // Only the destination changes.
420        b"COPY" => collect_keys(items.iter().skip(2).take(1)),
421        b"BITOP" => collect_keys(items.iter().skip(2).take(1)),
422        b"GEOSEARCHSTORE" | b"PFMERGE" | b"SDIFFSTORE" | b"SINTERSTORE" | b"SUNIONSTORE"
423        | b"ZDIFFSTORE" | b"ZINTERSTORE" | b"ZUNIONSTORE" => {
424            collect_keys(items.iter().skip(1).take(1))
425        }
426
427        // Blocking pops use every argument except the trailing timeout as a
428        // key. More complex numkeys-based variants conservatively clear below.
429        b"BLPOP" | b"BRPOP" | b"BZPOPMAX" | b"BZPOPMIN" if items.len() >= 3 => {
430            collect_keys(items.iter().skip(1).take(items.len() - 2))
431        }
432
433        // Database switches and global mutations invalidate every local entry.
434        b"FLUSHALL" | b"FLUSHDB" | b"SELECT" | b"SWAPDB" => CommandInvalidation::Clear,
435
436        // Unknown commands may be module writes or future Redis mutations.
437        _ => CommandInvalidation::Clear,
438    }
439}
440
441/// Whether `frame` can change cached keyspace state.
442///
443/// Unknown and malformed commands return `true` so callers fail safely when
444/// Redis or a module adds a mutation this crate does not yet classify.
445#[doc(hidden)]
446pub fn command_may_mutate(frame: &Frame) -> bool {
447    !matches!(command_invalidation(frame), CommandInvalidation::None)
448}
449
450fn collect_keys<'a>(items: impl IntoIterator<Item = &'a Frame>) -> CommandInvalidation {
451    let keys: Option<Vec<Vec<u8>>> = items
452        .into_iter()
453        .map(|item| bulk_arg(item).map(<[u8]>::to_vec))
454        .collect();
455    match keys {
456        Some(keys) if !keys.is_empty() => CommandInvalidation::Keys(keys),
457        _ => CommandInvalidation::Clear,
458    }
459}
460
461/// A cached response plus the metadata needed to bound and expire it.
462struct Entry {
463    /// The Redis key this entry depends on (for reverse-index cleanup).
464    redis_key: Vec<u8>,
465    /// The optional cluster partition and the generation under which this
466    /// entry was populated. Standalone caches leave this unset.
467    partition: Option<PartitionEpoch>,
468    frame: Frame,
469    /// When the entry was stored, for the per-entry client TTL.
470    stored_at: Instant,
471}
472
473/// Aggregate client-side cache counters.
474///
475/// The snapshot contains no Redis keys or command arguments, so it is safe to
476/// expose through diagnostics without leaking data or creating unbounded label
477/// cardinality.
478#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
479pub struct CacheStatistics {
480    /// Responses served from the local cache.
481    pub hits: u64,
482    /// Cacheable requests that required a Redis roundtrip.
483    pub misses: u64,
484    /// Key or full-cache invalidation operations observed locally.
485    pub invalidations: u64,
486    /// Cached entries removed by invalidation, expiry, or capacity bounds.
487    pub evictions: u64,
488}
489
490/// A point-in-time invalidation token captured before a cacheable request is
491/// sent to Redis. The response may only be inserted if every value still
492/// matches.
493///
494/// This type is public only so sibling workspace crates can integrate with the
495/// shared cache implementation. Its fields intentionally remain opaque.
496#[doc(hidden)]
497#[derive(Debug, Clone, Copy, PartialEq, Eq)]
498pub struct CacheEpoch {
499    generation: u64,
500    key_epoch: u64,
501    partition: Option<PartitionEpoch>,
502}
503
504/// A partition identifier paired with its current ownership generation.
505#[derive(Debug, Clone, Copy, PartialEq, Eq)]
506struct PartitionEpoch {
507    partition: u16,
508    generation: u64,
509}
510
511/// The client-side cache: response entries keyed by the full command, plus a
512/// reverse index from Redis key to the cache entries that depend on it.
513///
514/// This is an opaque handle. Construct one with [`CacheState::default`] to
515/// share a cache between a [`CacheService`](crate::cache_layer::CacheService)
516/// and its invalidation task; the cache is managed internally by those types.
517pub struct CacheState {
518    /// `cache_key -> Entry`.
519    entries: HashMap<Vec<u8>, Entry>,
520    /// `redis_key -> {cache_key}`.
521    index: HashMap<Vec<u8>, HashSet<Vec<u8>>>,
522    /// `partition -> {cache_key}` for targeted topology invalidation.
523    partition_index: HashMap<u16, HashSet<Vec<u8>>>,
524    /// When `false`, the tracking connection is unhealthy: reads pass through to
525    /// the server and nothing is cached, so stale data can never be served.
526    enabled: bool,
527    /// Maximum number of cached entries (`0` = unbounded).
528    max_size: usize,
529    /// Per-entry freshness deadline (`None` = no client TTL).
530    ttl: Option<Duration>,
531    /// Advances for full-cache invalidations and whenever per-key epoch
532    /// bookkeeping is pruned.
533    generation: u64,
534    /// Latest invalidation epoch for each Redis key.
535    key_epochs: HashMap<Vec<u8>, u64>,
536    /// Latest ownership/invalidation generation for each partition.
537    partition_generations: HashMap<u16, u64>,
538    /// Monotonic source for per-key epochs within a generation.
539    next_key_epoch: u64,
540    /// Bound for `key_epochs`; never zero.
541    max_key_epochs: usize,
542    hits: AtomicU64,
543    misses: AtomicU64,
544    invalidations: AtomicU64,
545    evictions: AtomicU64,
546    recorder: Option<Arc<dyn MetricsRecorder>>,
547}
548
549impl Default for CacheState {
550    fn default() -> Self {
551        Self::new(DEFAULT_MAX_ENTRIES, Some(DEFAULT_TTL))
552    }
553}
554
555impl CacheState {
556    /// Create a cache bounded to `max_size` entries (`0` = unbounded) with an
557    /// optional per-entry client TTL.
558    pub(crate) fn new(max_size: usize, ttl: Option<Duration>) -> Self {
559        Self::new_with_recorder(max_size, ttl, None)
560    }
561
562    /// Create a cache and optionally forward aggregate events to a metrics
563    /// recorder. The in-memory counters are always enabled.
564    pub(crate) fn new_with_recorder(
565        max_size: usize,
566        ttl: Option<Duration>,
567        recorder: Option<Arc<dyn MetricsRecorder>>,
568    ) -> Self {
569        Self {
570            entries: HashMap::new(),
571            index: HashMap::new(),
572            partition_index: HashMap::new(),
573            enabled: true,
574            max_size,
575            ttl,
576            generation: 0,
577            key_epochs: HashMap::new(),
578            partition_generations: HashMap::new(),
579            next_key_epoch: 0,
580            max_key_epochs: if max_size == 0 {
581                DEFAULT_MAX_EPOCHS
582            } else {
583                max_size
584            }
585            .max(1),
586            hits: AtomicU64::new(0),
587            misses: AtomicU64::new(0),
588            invalidations: AtomicU64::new(0),
589            evictions: AtomicU64::new(0),
590            recorder,
591        }
592    }
593
594    /// Look up a cached response by its full-command cache key. Returns `None`
595    /// when caching is disabled (passthrough) or when the entry is older than
596    /// the client TTL, so the caller fetches fresh from the server.
597    pub(crate) fn get(&self, cache_key: &[u8]) -> Option<&Frame> {
598        self.get_inner(cache_key, None)
599    }
600
601    /// Look up a response scoped to `partition` (a Redis Cluster slot).
602    ///
603    /// Entries from a previous partition generation are treated as misses.
604    /// This method is public only for the workspace cluster integration.
605    #[doc(hidden)]
606    pub fn get_in_partition(&self, cache_key: &[u8], partition: u16) -> Option<&Frame> {
607        self.get_inner(cache_key, Some(partition))
608    }
609
610    fn get_inner(&self, cache_key: &[u8], partition: Option<u16>) -> Option<&Frame> {
611        if !self.enabled {
612            self.record_event(CacheEvent::Miss, 1);
613            return None;
614        }
615        let Some(entry) = self.entries.get(cache_key) else {
616            self.record_event(CacheEvent::Miss, 1);
617            return None;
618        };
619        let expected_partition = partition.map(|partition| self.partition_epoch(partition));
620        if entry.partition != expected_partition {
621            self.record_event(CacheEvent::Miss, 1);
622            return None;
623        }
624        if let Some(ttl) = self.ttl
625            && entry.stored_at.elapsed() >= ttl
626        {
627            // Expired: don't serve it. The entry is left in place and will be
628            // overwritten by the re-fetch's insert (removing it would need
629            // &mut, and the Tower read path only holds a read lock).
630            self.record_event(CacheEvent::Miss, 1);
631            return None;
632        }
633        self.record_event(CacheEvent::Hit, 1);
634        Some(&entry.frame)
635    }
636
637    /// Capture the key and full-cache generations before dispatching a cache
638    /// miss to Redis.
639    ///
640    /// Pass this token to [`insert_if_current`](Self::insert_if_current). If a
641    /// server invalidation or local write races the request, the token no
642    /// longer matches and the stale response is discarded. Returns `None`
643    /// while caching is disabled so a read begun without invalidation tracking
644    /// can never populate the cache after tracking recovers.
645    pub(crate) fn snapshot_epoch(&self, redis_key: &[u8]) -> Option<CacheEpoch> {
646        self.snapshot_epoch_inner(redis_key, None)
647    }
648
649    /// Capture an invalidation token for a key routed through `partition`.
650    ///
651    /// A later key invalidation, partition invalidation/ownership change, full
652    /// clear, or suspension makes the token stale. This method is public only
653    /// for the workspace cluster integration.
654    #[doc(hidden)]
655    pub fn snapshot_epoch_in_partition(
656        &self,
657        redis_key: &[u8],
658        partition: u16,
659    ) -> Option<CacheEpoch> {
660        self.snapshot_epoch_inner(redis_key, Some(partition))
661    }
662
663    fn snapshot_epoch_inner(&self, redis_key: &[u8], partition: Option<u16>) -> Option<CacheEpoch> {
664        self.enabled.then(|| CacheEpoch {
665            generation: self.generation,
666            key_epoch: self.key_epochs.get(redis_key).copied().unwrap_or(0),
667            partition: partition.map(|partition| self.partition_epoch(partition)),
668        })
669    }
670
671    /// Store `frame` under `cache_key`, recording the reverse-index link to
672    /// `redis_key`. If the cache is bounded and full of *new* keys, one
673    /// arbitrary existing entry is evicted first.
674    #[cfg(test)]
675    pub(crate) fn insert(&mut self, cache_key: Vec<u8>, redis_key: Vec<u8>, frame: Frame) -> bool {
676        let Some(epoch) = self.snapshot_epoch(&redis_key) else {
677            return false;
678        };
679        self.insert_if_current(cache_key, redis_key, frame, epoch)
680    }
681
682    /// Store a response only if its invalidation epoch is still current.
683    ///
684    /// Returns `false` when caching is disabled or an invalidation raced the
685    /// Redis request. A rejected response is never visible through the cache.
686    pub(crate) fn insert_if_current(
687        &mut self,
688        cache_key: Vec<u8>,
689        redis_key: Vec<u8>,
690        frame: Frame,
691        epoch: CacheEpoch,
692    ) -> bool {
693        self.insert_if_current_inner(cache_key, redis_key, frame, None, epoch)
694    }
695
696    /// Store a response only if its key, global, and partition generations are
697    /// still current.
698    ///
699    /// This is the cluster-scoped counterpart to the standalone insertion
700    /// path. It is public only for the workspace cluster integration.
701    #[doc(hidden)]
702    pub fn insert_if_current_in_partition(
703        &mut self,
704        cache_key: Vec<u8>,
705        redis_key: Vec<u8>,
706        frame: Frame,
707        partition: u16,
708        epoch: CacheEpoch,
709    ) -> bool {
710        self.insert_if_current_inner(cache_key, redis_key, frame, Some(partition), epoch)
711    }
712
713    fn insert_if_current_inner(
714        &mut self,
715        cache_key: Vec<u8>,
716        redis_key: Vec<u8>,
717        frame: Frame,
718        partition: Option<u16>,
719        epoch: CacheEpoch,
720    ) -> bool {
721        // Don't populate the cache while tracking is unhealthy.
722        if !self.enabled || self.snapshot_epoch_inner(&redis_key, partition) != Some(epoch) {
723            return false;
724        }
725
726        // Expired entries remain observable as misses on the read-only lookup
727        // path. Remove and count one when their replacement arrives.
728        let replacing_expired = self
729            .entries
730            .get(&cache_key)
731            .is_some_and(|entry| self.ttl.is_some_and(|ttl| entry.stored_at.elapsed() >= ttl));
732        if replacing_expired && self.remove_entry(&cache_key) {
733            self.record_event(CacheEvent::Eviction, 1);
734        }
735
736        if self.max_size > 0
737            && !self.entries.contains_key(&cache_key)
738            && self.entries.len() >= self.max_size
739            && let Some(victim) = self.entries.keys().next().cloned()
740            && self.remove_entry(&victim)
741        {
742            self.record_event(CacheEvent::Eviction, 1);
743        }
744
745        // An exact-key overwrite should normally point at the same Redis key,
746        // but keep the reverse index correct even for manually constructed
747        // state in tests or downstream integrations.
748        if self.entries.contains_key(&cache_key) {
749            self.remove_entry(&cache_key);
750        }
751        self.index
752            .entry(redis_key.clone())
753            .or_default()
754            .insert(cache_key.clone());
755        if let Some(partition) = partition {
756            self.partition_index
757                .entry(partition)
758                .or_default()
759                .insert(cache_key.clone());
760        }
761        self.entries.insert(
762            cache_key,
763            Entry {
764                redis_key,
765                partition: epoch.partition,
766                frame,
767                stored_at: Instant::now(),
768            },
769        );
770        true
771    }
772
773    /// Evict every cache entry that depends on `redis_key`.
774    #[doc(hidden)]
775    pub fn invalidate(&mut self, redis_key: &[u8]) {
776        self.advance_key_epoch(redis_key);
777        self.record_event(CacheEvent::Invalidation, 1);
778        if let Some(cache_keys) = self.index.remove(redis_key) {
779            let mut count = 0;
780            for ck in cache_keys {
781                count += u64::from(self.remove_entry(&ck));
782            }
783            self.record_event(CacheEvent::Eviction, count);
784        }
785    }
786
787    /// Evict entries routed through `partition` and advance its generation.
788    ///
789    /// Advancing even when the partition currently has no entries rejects any
790    /// earlier in-flight response. Repeating this for each observed ownership
791    /// transition also protects an A -> B -> A cycle: a response issued during
792    /// either prior ownership generation cannot become current again.
793    #[doc(hidden)]
794    pub fn invalidate_partition(&mut self, partition: u16) {
795        self.advance_partition_generation(partition);
796        self.record_event(CacheEvent::Invalidation, 1);
797        if let Some(cache_keys) = self.partition_index.remove(&partition) {
798            let mut count = 0;
799            for cache_key in cache_keys {
800                count += u64::from(self.remove_entry(&cache_key));
801            }
802            self.record_event(CacheEvent::Eviction, count);
803        }
804    }
805
806    /// Drop all cached entries and index links.
807    #[doc(hidden)]
808    pub fn clear(&mut self) {
809        self.advance_generation();
810        self.key_epochs.clear();
811        self.partition_generations.clear();
812        self.next_key_epoch = 0;
813        self.record_event(CacheEvent::Invalidation, 1);
814        let evicted = self.entries.len() as u64;
815        self.entries.clear();
816        self.index.clear();
817        self.partition_index.clear();
818        self.record_event(CacheEvent::Eviction, evicted);
819    }
820
821    /// Synchronously invalidate cache state affected by `request`.
822    ///
823    /// Common single- and multi-key mutations invalidate only their affected
824    /// keys. Known read-only commands preserve the cache. Unknown or malformed
825    /// commands conservatively clear it, which is safe for module commands and
826    /// future Redis mutations the client does not yet recognize.
827    ///
828    /// Cached services call this both before dispatch and after a successful
829    /// write. Advancing the epoch twice is intentional: the first call removes
830    /// values that predate the write, while the second rejects reads that raced
831    /// the write window (including when `NOLOOP` suppresses server pushes).
832    #[doc(hidden)]
833    pub fn invalidate_for_command(&mut self, request: &Frame) {
834        match command_invalidation(request) {
835            CommandInvalidation::None => {}
836            CommandInvalidation::Keys(keys) => {
837                for key in keys {
838                    self.invalidate(&key);
839                }
840            }
841            CommandInvalidation::Clear => self.clear(),
842        }
843    }
844
845    /// Disable caching because the tracking connection was lost: clears all
846    /// entries and makes every read pass through to the server until
847    /// [`enable`](Self::enable) is called. This is what prevents serving stale
848    /// data after invalidations stop arriving.
849    #[doc(hidden)]
850    pub fn disable(&mut self) {
851        self.enabled = false;
852        self.clear();
853    }
854
855    /// Re-enable caching after the tracking connection is restored.
856    #[doc(hidden)]
857    pub fn enable(&mut self) {
858        self.resume();
859    }
860
861    /// Temporarily prevent cache hits and new fills without evicting entries.
862    ///
863    /// The global generation advances when the cache first becomes suspended,
864    /// so responses dispatched before suspension are rejected even if they
865    /// arrive after [`resume`](Self::resume). Callers may invalidate only the
866    /// affected partitions before resuming, preserving unrelated entries.
867    #[doc(hidden)]
868    pub fn suspend(&mut self) {
869        if self.enabled {
870            self.enabled = false;
871            self.advance_generation();
872        }
873    }
874
875    /// Resume cache hits and fills after a temporary suspension.
876    #[doc(hidden)]
877    pub fn resume(&mut self) {
878        self.enabled = true;
879    }
880
881    /// Whether caching is currently active (the tracking connection is healthy).
882    /// A `false` here means reads are passing through to the server.
883    pub fn is_enabled(&self) -> bool {
884        self.enabled
885    }
886
887    /// Number of cached response entries.
888    pub fn len(&self) -> usize {
889        self.entries.len()
890    }
891
892    /// Whether the cache holds no entries.
893    pub fn is_empty(&self) -> bool {
894        self.entries.is_empty()
895    }
896
897    /// Return a lock-free snapshot of the aggregate cache counters.
898    pub fn statistics(&self) -> CacheStatistics {
899        CacheStatistics {
900            hits: self.hits.load(Ordering::Relaxed),
901            misses: self.misses.load(Ordering::Relaxed),
902            invalidations: self.invalidations.load(Ordering::Relaxed),
903            evictions: self.evictions.load(Ordering::Relaxed),
904        }
905    }
906
907    /// Remove a single entry and its reverse-index link.
908    fn remove_entry(&mut self, cache_key: &[u8]) -> bool {
909        let Some(entry) = self.entries.remove(cache_key) else {
910            return false;
911        };
912        if let Some(set) = self.index.get_mut(&entry.redis_key) {
913            set.remove(cache_key);
914            if set.is_empty() {
915                self.index.remove(&entry.redis_key);
916            }
917        }
918        if let Some(partition) = entry.partition.map(|partition| partition.partition)
919            && let Some(set) = self.partition_index.get_mut(&partition)
920        {
921            set.remove(cache_key);
922            if set.is_empty() {
923                self.partition_index.remove(&partition);
924            }
925        }
926        true
927    }
928
929    fn advance_key_epoch(&mut self, redis_key: &[u8]) {
930        if !self.key_epochs.contains_key(redis_key) && self.key_epochs.len() >= self.max_key_epochs
931        {
932            // Advancing the generation before pruning ensures a miss that
933            // captured a now-removed key epoch can never compare equal again.
934            self.advance_generation();
935            self.key_epochs.clear();
936            self.next_key_epoch = 0;
937        }
938
939        if self.next_key_epoch == u64::MAX {
940            self.advance_generation();
941            self.key_epochs.clear();
942            self.next_key_epoch = 0;
943        }
944        self.next_key_epoch += 1;
945        self.key_epochs
946            .insert(redis_key.to_vec(), self.next_key_epoch);
947    }
948
949    fn advance_generation(&mut self) {
950        self.generation = self.generation.wrapping_add(1);
951    }
952
953    fn partition_epoch(&self, partition: u16) -> PartitionEpoch {
954        PartitionEpoch {
955            partition,
956            generation: self
957                .partition_generations
958                .get(&partition)
959                .copied()
960                .unwrap_or(0),
961        }
962    }
963
964    fn advance_partition_generation(&mut self, partition: u16) {
965        if self.partition_generations.get(&partition) == Some(&u64::MAX) {
966            // Global advancement makes every outstanding token stale before
967            // resetting bounded partition-generation bookkeeping.
968            self.advance_generation();
969            self.partition_generations.clear();
970        }
971        *self.partition_generations.entry(partition).or_default() += 1;
972    }
973
974    fn record_event(&self, event: CacheEvent, count: u64) {
975        if count == 0 {
976            return;
977        }
978        let counter = match event {
979            CacheEvent::Hit => &self.hits,
980            CacheEvent::Miss => &self.misses,
981            CacheEvent::Invalidation => &self.invalidations,
982            CacheEvent::Eviction => &self.evictions,
983        };
984        counter.fetch_add(count, Ordering::Relaxed);
985        if let Some(recorder) = &self.recorder {
986            recorder.cache_event(event, count);
987        }
988    }
989}
990
991#[cfg(test)]
992mod tests {
993    use super::*;
994    use bytes::Bytes;
995    use std::sync::Mutex;
996
997    #[derive(Default)]
998    struct RecordingMetrics {
999        events: Mutex<Vec<(CacheEvent, u64)>>,
1000    }
1001
1002    impl MetricsRecorder for RecordingMetrics {
1003        fn command_completed(
1004            &self,
1005            _command: &str,
1006            _duration: Duration,
1007            _error: Option<crate::metrics_layer::ErrorKind>,
1008        ) {
1009        }
1010
1011        fn cache_event(&self, event: CacheEvent, count: u64) {
1012            self.events.lock().unwrap().push((event, count));
1013        }
1014    }
1015
1016    fn bulk(s: &str) -> Frame {
1017        Frame::BulkString(Some(Bytes::from(s.to_string())))
1018    }
1019
1020    fn frame(parts: &[&str]) -> Frame {
1021        Frame::Array(Some(parts.iter().map(|p| bulk(p)).collect()))
1022    }
1023
1024    #[test]
1025    fn hget_fields_do_not_collide() {
1026        // The core bug: HGET h f1 and HGET h f2 must be distinct cache keys.
1027        let (k1, rk1) = extract_cache_entry(&frame(&["HGET", "h", "f1"])).unwrap();
1028        let (k2, rk2) = extract_cache_entry(&frame(&["HGET", "h", "f2"])).unwrap();
1029        assert_ne!(k1, k2, "different fields must not share a cache key");
1030        assert_eq!(rk1, rk2, "both still depend on Redis key `h`");
1031        assert_eq!(rk1, b"h".to_vec());
1032    }
1033
1034    #[test]
1035    fn command_name_is_case_normalized() {
1036        let (lower, _) = extract_cache_entry(&frame(&["get", "k"])).unwrap();
1037        let (upper, _) = extract_cache_entry(&frame(&["GET", "k"])).unwrap();
1038        assert_eq!(lower, upper);
1039    }
1040
1041    #[test]
1042    fn non_cacheable_returns_none() {
1043        assert!(extract_cache_entry(&frame(&["SET", "k", "v"])).is_none());
1044    }
1045
1046    #[test]
1047    fn invalidate_evicts_all_variants_of_a_key() {
1048        let mut state = CacheState::default();
1049        let (k1, rk1) = extract_cache_entry(&frame(&["HGET", "h", "f1"])).unwrap();
1050        let (k2, rk2) = extract_cache_entry(&frame(&["HGET", "h", "f2"])).unwrap();
1051        state.insert(k1.clone(), rk1, bulk("v1"));
1052        state.insert(k2.clone(), rk2, bulk("v2"));
1053        assert_eq!(state.len(), 2);
1054
1055        // Invalidating `h` must drop both variants.
1056        state.invalidate(b"h");
1057        assert_eq!(state.len(), 0);
1058        assert!(state.get(&k1).is_none());
1059        assert!(state.get(&k2).is_none());
1060    }
1061
1062    #[test]
1063    fn invalidate_other_key_leaves_entry() {
1064        let mut state = CacheState::default();
1065        let (k, rk) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1066        state.insert(k.clone(), rk, bulk("v"));
1067        state.invalidate(b"b"); // unrelated key
1068        assert_eq!(state.len(), 1);
1069        assert!(state.get(&k).is_some());
1070    }
1071
1072    #[test]
1073    fn eviction_cleans_reverse_index() {
1074        let mut state = CacheState::new(1, None);
1075        let (k1, rk1) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1076        let (k2, rk2) = extract_cache_entry(&frame(&["GET", "b"])).unwrap();
1077        state.insert(k1, rk1, bulk("va"));
1078        state.insert(k2.clone(), rk2, bulk("vb")); // evicts the "a" entry
1079        assert_eq!(state.len(), 1);
1080        // The evicted key's index link is gone, so invalidating it is a no-op
1081        // and does not disturb the surviving entry.
1082        state.invalidate(b"a");
1083        assert_eq!(state.len(), 1);
1084        assert!(state.get(&k2).is_some());
1085    }
1086
1087    #[test]
1088    fn parse_invalidation_keys_are_bytes() {
1089        let f = Frame::Push(vec![
1090            bulk("invalidate"),
1091            Frame::Array(Some(vec![bulk("k1"), bulk("k2")])),
1092        ]);
1093        assert_eq!(
1094            parse_invalidation(&f),
1095            Some(vec![b"k1".to_vec(), b"k2".to_vec()])
1096        );
1097    }
1098
1099    #[test]
1100    fn parse_invalidation_accepts_resp3_simple_strings() {
1101        let f = Frame::Push(vec![
1102            Frame::SimpleString(Bytes::from_static(b"invalidate")),
1103            Frame::Array(Some(vec![Frame::SimpleString(Bytes::from_static(b"key"))])),
1104        ]);
1105        assert_eq!(parse_invalidation(&f), Some(vec![b"key".to_vec()]));
1106    }
1107
1108    #[test]
1109    fn malformed_recognized_invalidation_fails_safe_to_full_clear() {
1110        let f = Frame::Push(vec![
1111            Frame::SimpleString(Bytes::from_static(b"invalidate")),
1112            Frame::Array(Some(vec![Frame::Integer(42)])),
1113        ]);
1114        assert_eq!(parse_invalidation(&f), Some(Vec::new()));
1115    }
1116
1117    #[test]
1118    fn malformed_or_missing_invalidation_payload_fails_safe_to_full_clear() {
1119        for frame in [
1120            Frame::Push(vec![bulk("invalidate")]),
1121            Frame::Push(vec![bulk("invalidate"), bulk("not-an-array")]),
1122        ] {
1123            assert_eq!(parse_invalidation(&frame), Some(Vec::new()));
1124        }
1125    }
1126
1127    #[test]
1128    fn parse_invalidation_flush_is_empty() {
1129        let f = Frame::Push(vec![bulk("invalidate"), Frame::Null]);
1130        assert_eq!(parse_invalidation(&f), Some(Vec::new()));
1131    }
1132
1133    #[test]
1134    fn parse_invalidation_non_invalidate_is_none() {
1135        let f = Frame::Push(vec![bulk("other"), Frame::Null]);
1136        assert!(parse_invalidation(&f).is_none());
1137    }
1138
1139    #[test]
1140    fn managed_connection_state_commands_are_detected_without_blocking_diagnostics() {
1141        for (parts, expected) in [
1142            (&["CLIENT", "TRACKING", "OFF"][..], "CLIENT TRACKING"),
1143            (&["client", "caching", "yes"][..], "CLIENT CACHING"),
1144            (&["CLIENT", "REPLY", "OFF"][..], "CLIENT REPLY"),
1145            (&["RESET"][..], "RESET"),
1146            (&["HELLO", "2"][..], "HELLO"),
1147            (&["QUIT"][..], "QUIT"),
1148        ] {
1149            assert_eq!(managed_cache_state_command(&frame(parts)), Some(expected));
1150        }
1151
1152        for parts in [
1153            &["CLIENT", "TRACKINGINFO"][..],
1154            &["CLIENT", "GETREDIR"][..],
1155            &["CLIENT", "ID"][..],
1156            &["GET", "key"][..],
1157        ] {
1158            assert_eq!(managed_cache_state_command(&frame(parts)), None);
1159        }
1160    }
1161
1162    #[test]
1163    fn disabled_cache_passes_through_and_drops_writes() {
1164        let mut state = CacheState::default();
1165        let (k, rk) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1166        state.insert(k.clone(), rk.clone(), bulk("v"));
1167        assert!(state.get(&k).is_some());
1168
1169        // Losing the tracking connection: disable clears entries and forces
1170        // every read to pass through (never serve stale data).
1171        state.disable();
1172        assert!(!state.is_enabled());
1173        assert_eq!(state.len(), 0);
1174        assert!(state.get(&k).is_none());
1175
1176        // Writes while disabled are dropped, so nothing accumulates uninvalidated.
1177        state.insert(k.clone(), rk, bulk("v2"));
1178        assert_eq!(state.len(), 0);
1179
1180        // Re-enabling (tracking restored) resumes normal caching.
1181        state.enable();
1182        let (k2, rk2) = extract_cache_entry(&frame(&["GET", "b"])).unwrap();
1183        state.insert(k2.clone(), rk2, bulk("vb"));
1184        assert!(state.get(&k2).is_some());
1185    }
1186
1187    #[test]
1188    fn disabled_cache_does_not_issue_an_insertion_epoch() {
1189        let mut state = CacheState::default();
1190        let (_, redis_key) = extract_cache_entry(&frame(&["GET", "key"])).unwrap();
1191
1192        state.disable();
1193        assert!(state.snapshot_epoch(&redis_key).is_none());
1194
1195        state.enable();
1196        assert!(state.snapshot_epoch(&redis_key).is_some());
1197    }
1198
1199    #[test]
1200    fn ttl_command_is_not_cacheable() {
1201        // A cached TTL countdown would be wrong the instant it is stored.
1202        assert!(extract_cache_entry(&frame(&["TTL", "k"])).is_none());
1203    }
1204
1205    #[test]
1206    fn entry_expires_after_client_ttl() {
1207        let mut state = CacheState::new(0, Some(Duration::from_millis(10)));
1208        let (k, rk) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1209        state.insert(k.clone(), rk, bulk("v"));
1210        assert!(state.get(&k).is_some(), "fresh entry is a hit");
1211
1212        std::thread::sleep(Duration::from_millis(25));
1213        assert!(
1214            state.get(&k).is_none(),
1215            "an entry past the client TTL must not be served"
1216        );
1217    }
1218
1219    #[test]
1220    fn no_ttl_means_no_expiry() {
1221        let mut state = CacheState::new(0, None);
1222        let (k, rk) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1223        state.insert(k.clone(), rk, bulk("v"));
1224        std::thread::sleep(Duration::from_millis(15));
1225        assert!(
1226            state.get(&k).is_some(),
1227            "no TTL configured -> never expires"
1228        );
1229    }
1230
1231    #[test]
1232    fn zero_ttl_never_serves_a_cached_response() {
1233        let mut state = CacheState::new(1, Some(Duration::ZERO));
1234        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1235        state.insert(cache_key.clone(), redis_key, bulk("value"));
1236        assert!(state.get(&cache_key).is_none());
1237    }
1238
1239    #[test]
1240    fn key_invalidation_rejects_a_racing_miss() {
1241        let mut state = CacheState::default();
1242        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1243        let before_request = state.snapshot_epoch(&redis_key).unwrap();
1244
1245        state.invalidate(&redis_key);
1246
1247        assert!(!state.insert_if_current(
1248            cache_key.clone(),
1249            redis_key,
1250            bulk("stale"),
1251            before_request,
1252        ));
1253        assert!(state.get(&cache_key).is_none());
1254    }
1255
1256    #[test]
1257    fn partition_invalidation_preserves_unrelated_entries() {
1258        let mut state = CacheState::default();
1259        let (a_cache_key, a_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1260        let (b_cache_key, b_key) = extract_cache_entry(&frame(&["GET", "b"])).unwrap();
1261        let a_epoch = state.snapshot_epoch_in_partition(&a_key, 1).unwrap();
1262        let b_epoch = state.snapshot_epoch_in_partition(&b_key, 2).unwrap();
1263        assert!(state.insert_if_current_in_partition(
1264            a_cache_key.clone(),
1265            a_key,
1266            bulk("va"),
1267            1,
1268            a_epoch,
1269        ));
1270        assert!(state.insert_if_current_in_partition(
1271            b_cache_key.clone(),
1272            b_key,
1273            bulk("vb"),
1274            2,
1275            b_epoch,
1276        ));
1277
1278        state.invalidate_partition(1);
1279
1280        assert!(state.get_in_partition(&a_cache_key, 1).is_none());
1281        assert!(state.get_in_partition(&b_cache_key, 2).is_some());
1282        assert_eq!(state.len(), 1);
1283    }
1284
1285    #[test]
1286    fn partition_generation_rejects_racing_fills_across_owner_cycles() {
1287        let mut state = CacheState::default();
1288        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "moved"])).unwrap();
1289        let owner_a_first = state.snapshot_epoch_in_partition(&redis_key, 42).unwrap();
1290
1291        // Observe A -> B, then capture a request while B owns the slot.
1292        state.invalidate_partition(42);
1293        let owner_b = state.snapshot_epoch_in_partition(&redis_key, 42).unwrap();
1294
1295        // Observe B -> A. Neither response from a prior ownership generation
1296        // may become valid merely because the original owner has returned.
1297        state.invalidate_partition(42);
1298        assert!(!state.insert_if_current_in_partition(
1299            cache_key.clone(),
1300            redis_key.clone(),
1301            bulk("stale-a"),
1302            42,
1303            owner_a_first,
1304        ));
1305        assert!(!state.insert_if_current_in_partition(
1306            cache_key.clone(),
1307            redis_key.clone(),
1308            bulk("stale-b"),
1309            42,
1310            owner_b,
1311        ));
1312
1313        let owner_a_second = state.snapshot_epoch_in_partition(&redis_key, 42).unwrap();
1314        assert!(state.insert_if_current_in_partition(
1315            cache_key.clone(),
1316            redis_key,
1317            bulk("fresh-a"),
1318            42,
1319            owner_a_second,
1320        ));
1321        assert!(state.get_in_partition(&cache_key, 42).is_some());
1322    }
1323
1324    #[test]
1325    fn scoped_and_standalone_entries_cannot_cross_lookup_domains() {
1326        let mut state = CacheState::default();
1327        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1328        let epoch = state.snapshot_epoch_in_partition(&redis_key, 7).unwrap();
1329        assert!(state.insert_if_current_in_partition(
1330            cache_key.clone(),
1331            redis_key,
1332            bulk("value"),
1333            7,
1334            epoch,
1335        ));
1336
1337        assert!(state.get(&cache_key).is_none());
1338        assert!(state.get_in_partition(&cache_key, 8).is_none());
1339        assert!(state.get_in_partition(&cache_key, 7).is_some());
1340    }
1341
1342    #[test]
1343    fn suspension_rejects_hits_and_fills_but_preserves_existing_entries() {
1344        let mut state = CacheState::default();
1345        let (cached_key, cached_redis_key) =
1346            extract_cache_entry(&frame(&["GET", "cached"])).unwrap();
1347        let cached_epoch = state
1348            .snapshot_epoch_in_partition(&cached_redis_key, 1)
1349            .unwrap();
1350        assert!(state.insert_if_current_in_partition(
1351            cached_key.clone(),
1352            cached_redis_key,
1353            bulk("value"),
1354            1,
1355            cached_epoch,
1356        ));
1357
1358        let (racing_key, racing_redis_key) =
1359            extract_cache_entry(&frame(&["GET", "racing"])).unwrap();
1360        let before_suspend = state
1361            .snapshot_epoch_in_partition(&racing_redis_key, 2)
1362            .unwrap();
1363
1364        state.suspend();
1365        assert!(!state.is_enabled());
1366        assert!(state.get_in_partition(&cached_key, 1).is_none());
1367        assert!(
1368            state
1369                .snapshot_epoch_in_partition(&racing_redis_key, 2)
1370                .is_none()
1371        );
1372        assert!(!state.insert_if_current_in_partition(
1373            racing_key.clone(),
1374            racing_redis_key.clone(),
1375            bulk("stale"),
1376            2,
1377            before_suspend,
1378        ));
1379        assert_eq!(state.len(), 1, "suspension itself preserves entries");
1380
1381        state.resume();
1382        assert!(state.is_enabled());
1383        assert!(state.get_in_partition(&cached_key, 1).is_some());
1384        assert!(!state.insert_if_current_in_partition(
1385            racing_key,
1386            racing_redis_key,
1387            bulk("late"),
1388            2,
1389            before_suspend,
1390        ));
1391    }
1392
1393    #[test]
1394    fn key_and_capacity_eviction_clean_the_partition_index() {
1395        let mut state = CacheState::new(1, None);
1396        let (a_cache_key, a_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1397        let a_epoch = state.snapshot_epoch_in_partition(&a_key, 1).unwrap();
1398        assert!(state.insert_if_current_in_partition(
1399            a_cache_key,
1400            a_key.clone(),
1401            bulk("a"),
1402            1,
1403            a_epoch,
1404        ));
1405        state.invalidate(&a_key);
1406        assert!(!state.partition_index.contains_key(&1));
1407
1408        let (b_cache_key, b_key) = extract_cache_entry(&frame(&["GET", "b"])).unwrap();
1409        let b_epoch = state.snapshot_epoch_in_partition(&b_key, 2).unwrap();
1410        assert!(state.insert_if_current_in_partition(b_cache_key, b_key, bulk("b"), 2, b_epoch,));
1411        let (c_cache_key, c_key) = extract_cache_entry(&frame(&["GET", "c"])).unwrap();
1412        let c_epoch = state.snapshot_epoch_in_partition(&c_key, 3).unwrap();
1413        assert!(state.insert_if_current_in_partition(c_cache_key, c_key, bulk("c"), 3, c_epoch,));
1414        assert!(!state.partition_index.contains_key(&2));
1415        assert!(state.partition_index.contains_key(&3));
1416    }
1417
1418    #[test]
1419    fn full_clear_rejects_every_racing_miss() {
1420        let mut state = CacheState::default();
1421        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1422        let before_request = state.snapshot_epoch(&redis_key).unwrap();
1423
1424        state.clear();
1425
1426        assert!(!state.insert_if_current(cache_key, redis_key, bulk("stale"), before_request,));
1427    }
1428
1429    #[test]
1430    fn pruning_key_epochs_advances_the_global_generation() {
1431        let mut state = CacheState {
1432            max_key_epochs: 1,
1433            ..CacheState::default()
1434        };
1435        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "old"])).unwrap();
1436        let before_prune = state.snapshot_epoch(&redis_key).unwrap();
1437
1438        state.invalidate(b"first");
1439        state.invalidate(b"second"); // prunes `first` before recording `second`
1440
1441        assert_eq!(state.key_epochs.len(), 1);
1442        assert!(!state.insert_if_current(cache_key, redis_key, bulk("stale"), before_prune,));
1443    }
1444
1445    #[test]
1446    fn local_writes_invalidate_only_known_keys_and_advance_twice() {
1447        let mut state = CacheState::default();
1448        let (a_cache_key, a_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1449        let (b_cache_key, b_key) = extract_cache_entry(&frame(&["GET", "b"])).unwrap();
1450        state.insert(a_cache_key.clone(), a_key.clone(), bulk("old-a"));
1451        state.insert(b_cache_key.clone(), b_key, bulk("old-b"));
1452
1453        state.invalidate_for_command(&frame(&["SET", "a", "new-a"]));
1454        let during_write = state.snapshot_epoch(&a_key).unwrap();
1455        state.invalidate_for_command(&frame(&["SET", "a", "new-a"]));
1456
1457        assert!(state.get(&a_cache_key).is_none());
1458        assert!(state.get(&b_cache_key).is_some());
1459        assert!(!state.insert_if_current(a_cache_key, a_key, bulk("raced"), during_write));
1460    }
1461
1462    #[test]
1463    fn known_reads_preserve_cache_and_unknown_commands_clear_it() {
1464        let mut state = CacheState::default();
1465        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1466        state.insert(cache_key.clone(), redis_key.clone(), bulk("value"));
1467
1468        state.invalidate_for_command(&frame(&["TTL", "a"]));
1469        assert!(state.get(&cache_key).is_some());
1470
1471        state.invalidate_for_command(&frame(&["FUTURE.WRITE", "a"]));
1472        assert!(state.get(&cache_key).is_none());
1473    }
1474
1475    #[test]
1476    fn mutation_classifier_handles_reads_stateful_commands_and_xgroup_key() {
1477        assert!(!command_may_mutate(&frame(&["TTL", "a"])));
1478        assert!(command_may_mutate(&frame(&["SET", "a", "value"])));
1479        assert!(command_may_mutate(&frame(&["CLIENT", "TRACKING", "OFF"])));
1480
1481        let mut state = CacheState::default();
1482        let (cache_key, redis_key) = extract_cache_entry(&frame(&["TYPE", "stream-key"])).unwrap();
1483        state.insert(cache_key.clone(), redis_key, bulk("none"));
1484        state.invalidate_for_command(&frame(&[
1485            "XGROUP",
1486            "CREATE",
1487            "stream-key",
1488            "group",
1489            "$",
1490            "MKSTREAM",
1491        ]));
1492        assert!(state.get(&cache_key).is_none());
1493    }
1494
1495    #[test]
1496    fn cache_statistics_count_hits_misses_invalidations_and_evictions() {
1497        let mut state = CacheState::default();
1498        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1499
1500        assert!(state.get(&cache_key).is_none());
1501        state.insert(cache_key.clone(), redis_key.clone(), bulk("value"));
1502        assert!(state.get(&cache_key).is_some());
1503        state.invalidate(&redis_key);
1504
1505        assert_eq!(
1506            state.statistics(),
1507            CacheStatistics {
1508                hits: 1,
1509                misses: 1,
1510                invalidations: 1,
1511                evictions: 1,
1512            }
1513        );
1514    }
1515
1516    #[test]
1517    fn cache_events_are_forwarded_to_the_metrics_recorder() {
1518        let recorder = Arc::new(RecordingMetrics::default());
1519        let metrics: Arc<dyn MetricsRecorder> = recorder.clone();
1520        let mut state = CacheState::new_with_recorder(1, None, Some(metrics));
1521        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1522
1523        assert!(state.get(&cache_key).is_none());
1524        state.insert(cache_key.clone(), redis_key.clone(), bulk("value"));
1525        assert!(state.get(&cache_key).is_some());
1526        state.invalidate(&redis_key);
1527
1528        assert_eq!(
1529            *recorder.events.lock().unwrap(),
1530            vec![
1531                (CacheEvent::Miss, 1),
1532                (CacheEvent::Hit, 1),
1533                (CacheEvent::Invalidation, 1),
1534                (CacheEvent::Eviction, 1),
1535            ]
1536        );
1537    }
1538
1539    #[test]
1540    fn replacing_an_expired_entry_counts_an_eviction() {
1541        let mut state = CacheState::new(1, Some(Duration::from_millis(1)));
1542        let (cache_key, redis_key) = extract_cache_entry(&frame(&["GET", "a"])).unwrap();
1543        state.insert(cache_key.clone(), redis_key.clone(), bulk("old"));
1544        std::thread::sleep(Duration::from_millis(5));
1545        assert!(state.get(&cache_key).is_none());
1546
1547        state.insert(cache_key, redis_key, bulk("fresh"));
1548
1549        assert_eq!(state.statistics().evictions, 1);
1550    }
1551}