1use 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
22pub(crate) const DEFAULT_MAX_ENTRIES: usize = 10_000;
24pub(crate) const DEFAULT_TTL: Duration = Duration::from_secs(30);
28const DEFAULT_MAX_EPOCHS: usize = DEFAULT_MAX_ENTRIES;
32
33const 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
47fn 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#[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 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 _ => return None,
90 }
91 }
92
93 Some((cache_key, redis_key))
94}
95
96#[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 _ => 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 _ => Some(Vec::new()),
133 }
134}
135
136const 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
246const 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#[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 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 b"DEL" | b"UNLINK" => collect_keys(&items[1..]),
406
407 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 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 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 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 b"FLUSHALL" | b"FLUSHDB" | b"SELECT" | b"SWAPDB" => CommandInvalidation::Clear,
435
436 _ => CommandInvalidation::Clear,
438 }
439}
440
441#[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
461struct Entry {
463 redis_key: Vec<u8>,
465 partition: Option<PartitionEpoch>,
468 frame: Frame,
469 stored_at: Instant,
471}
472
473#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
479pub struct CacheStatistics {
480 pub hits: u64,
482 pub misses: u64,
484 pub invalidations: u64,
486 pub evictions: u64,
488}
489
490#[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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
506struct PartitionEpoch {
507 partition: u16,
508 generation: u64,
509}
510
511pub struct CacheState {
518 entries: HashMap<Vec<u8>, Entry>,
520 index: HashMap<Vec<u8>, HashSet<Vec<u8>>>,
522 partition_index: HashMap<u16, HashSet<Vec<u8>>>,
524 enabled: bool,
527 max_size: usize,
529 ttl: Option<Duration>,
531 generation: u64,
534 key_epochs: HashMap<Vec<u8>, u64>,
536 partition_generations: HashMap<u16, u64>,
538 next_key_epoch: u64,
540 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 pub(crate) fn new(max_size: usize, ttl: Option<Duration>) -> Self {
559 Self::new_with_recorder(max_size, ttl, None)
560 }
561
562 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 pub(crate) fn get(&self, cache_key: &[u8]) -> Option<&Frame> {
598 self.get_inner(cache_key, None)
599 }
600
601 #[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 self.record_event(CacheEvent::Miss, 1);
631 return None;
632 }
633 self.record_event(CacheEvent::Hit, 1);
634 Some(&entry.frame)
635 }
636
637 pub(crate) fn snapshot_epoch(&self, redis_key: &[u8]) -> Option<CacheEpoch> {
646 self.snapshot_epoch_inner(redis_key, None)
647 }
648
649 #[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 #[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 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 #[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 if !self.enabled || self.snapshot_epoch_inner(&redis_key, partition) != Some(epoch) {
723 return false;
724 }
725
726 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 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 #[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 #[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 #[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 #[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 #[doc(hidden)]
850 pub fn disable(&mut self) {
851 self.enabled = false;
852 self.clear();
853 }
854
855 #[doc(hidden)]
857 pub fn enable(&mut self) {
858 self.resume();
859 }
860
861 #[doc(hidden)]
868 pub fn suspend(&mut self) {
869 if self.enabled {
870 self.enabled = false;
871 self.advance_generation();
872 }
873 }
874
875 #[doc(hidden)]
877 pub fn resume(&mut self) {
878 self.enabled = true;
879 }
880
881 pub fn is_enabled(&self) -> bool {
884 self.enabled
885 }
886
887 pub fn len(&self) -> usize {
889 self.entries.len()
890 }
891
892 pub fn is_empty(&self) -> bool {
894 self.entries.is_empty()
895 }
896
897 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 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 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 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 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 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"); 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")); assert_eq!(state.len(), 1);
1080 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 state.disable();
1172 assert!(!state.is_enabled());
1173 assert_eq!(state.len(), 0);
1174 assert!(state.get(&k).is_none());
1175
1176 state.insert(k.clone(), rk, bulk("v2"));
1178 assert_eq!(state.len(), 0);
1179
1180 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 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 state.invalidate_partition(42);
1293 let owner_b = state.snapshot_epoch_in_partition(&redis_key, 42).unwrap();
1294
1295 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"); 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}