1use std::future::Future;
35use std::pin::Pin;
36use std::sync::atomic::{AtomicUsize, Ordering};
37use std::sync::{Arc, Once};
38use std::task::{Context, Poll};
39use std::time::Duration;
40
41use bytes::Bytes;
42use futures::Stream;
43use redis_tower_commands::{ClientCaching, ClientTracking};
44use redis_tower_core::{Command, Frame, FrameService, RedisError};
45use tokio::sync::RwLock;
46use tower_layer::Layer;
47use tower_service::Service;
48
49use crate::auto_pipeline::AutoPipelineService;
50use crate::cache_state::{
51 CacheState, CacheStatistics, DEFAULT_MAX_ENTRIES, DEFAULT_TTL, command_may_mutate,
52 extract_cache_entry, parse_invalidation,
53};
54use crate::caching::{
55 CacheMutationGuard, CachedClientConfig, DataConnectionHealth, InvalidationLifecycle,
56 TrackingConfigurator, TrackingRecovery, own_invalidation_stream, start_tracking_supervisor,
57 validate_cached_user_command,
58};
59use crate::metrics_layer::MetricsRecorder;
60use crate::reconnect::ConnectionFactory;
61use crate::reconnect_layer::ReconnectService;
62
63type BoxRedisFuture<T> = Pin<Box<dyn Future<Output = Result<T, RedisError>> + Send>>;
64type OptInDispatch<S> = fn(&mut S, Frame) -> BoxRedisFuture<Frame>;
65
66pub trait ReleaseReadiness {
84 fn release_readiness(&mut self);
87}
88
89impl ReleaseReadiness for AutoPipelineService {
90 fn release_readiness(&mut self) {
91 self.release_reservation();
92 }
93}
94
95impl ReleaseReadiness for FrameService {
96 fn release_readiness(&mut self) {
97 }
100}
101
102impl ReleaseReadiness for ReconnectService {
103 fn release_readiness(&mut self) {
104 }
107}
108
109#[derive(Debug, Clone)]
116pub struct CacheConfig {
117 pub max_size: usize,
119 pub ttl: Option<Duration>,
121}
122
123impl Default for CacheConfig {
124 fn default() -> Self {
125 Self {
126 max_size: DEFAULT_MAX_ENTRIES,
127 ttl: Some(DEFAULT_TTL),
128 }
129 }
130}
131
132#[derive(Clone)]
140pub struct CacheLayer {
141 cache: Arc<RwLock<CacheState>>,
142 mutations_in_flight: Arc<AtomicUsize>,
143 tracked_prefixes: Option<Arc<Vec<Bytes>>>,
144 recovery: Option<TrackingRecovery>,
145 invalidation: Option<InvalidationLifecycle>,
146}
147
148impl CacheLayer {
149 pub fn new(config: CacheConfig) -> Self {
157 Self::without_invalidation(config)
158 }
159
160 pub fn without_invalidation(config: CacheConfig) -> Self {
162 warn_invalidation_free();
163 Self {
164 cache: Arc::new(RwLock::new(CacheState::new(config.max_size, config.ttl))),
165 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
166 tracked_prefixes: None,
167 recovery: None,
168 invalidation: None,
169 }
170 }
171
172 pub fn without_invalidation_with_recorder(
174 config: CacheConfig,
175 recorder: Arc<dyn MetricsRecorder>,
176 ) -> Self {
177 warn_invalidation_free();
178 Self {
179 cache: Arc::new(RwLock::new(CacheState::new_with_recorder(
180 config.max_size,
181 config.ttl,
182 Some(recorder),
183 ))),
184 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
185 tracked_prefixes: None,
186 recovery: None,
187 invalidation: None,
188 }
189 }
190
191 pub fn with_invalidation_stream<T>(config: CacheConfig, push_stream: T) -> Self
199 where
200 T: Stream<Item = Result<Frame, redis_tower_protocol::ProtocolError>> + Send + 'static,
201 {
202 let cache = Arc::new(RwLock::new(CacheState::new(config.max_size, config.ttl)));
203 let invalidation = own_invalidation_stream(Arc::clone(&cache), Box::pin(push_stream));
204 Self {
205 cache,
206 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
207 tracked_prefixes: None,
208 recovery: None,
209 invalidation: Some(invalidation),
210 }
211 }
212
213 pub fn with_invalidation_stream_and_recorder<T>(
225 config: CacheConfig,
226 push_stream: T,
227 recorder: Arc<dyn MetricsRecorder>,
228 ) -> Self
229 where
230 T: Stream<Item = Result<Frame, redis_tower_protocol::ProtocolError>> + Send + 'static,
231 {
232 let cache = Arc::new(RwLock::new(CacheState::new_with_recorder(
233 config.max_size,
234 config.ttl,
235 Some(recorder),
236 )));
237 let invalidation = own_invalidation_stream(Arc::clone(&cache), Box::pin(push_stream));
238 Self {
239 cache,
240 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
241 tracked_prefixes: None,
242 recovery: None,
243 invalidation: Some(invalidation),
244 }
245 }
246
247 pub fn cache(&self) -> &Arc<RwLock<CacheState>> {
249 &self.cache
250 }
251}
252
253impl<S: ReleaseReadiness> Layer<S> for CacheLayer {
254 type Service = CacheService<S>;
255
256 fn layer(&self, inner: S) -> Self::Service {
257 CacheService {
258 inner,
259 cache: Arc::clone(&self.cache),
260 mutations_in_flight: Arc::clone(&self.mutations_in_flight),
261 data_health: None,
262 tracked_prefixes: self.tracked_prefixes.clone(),
263 recovery: self.recovery.clone(),
264 invalidation: self.invalidation.clone(),
265 opt_in_dispatch: None,
266 }
267 }
268}
269
270pub struct CacheService<S> {
284 inner: S,
285 cache: Arc<RwLock<CacheState>>,
286 mutations_in_flight: Arc<AtomicUsize>,
287 data_health: Option<DataConnectionHealth>,
288 tracked_prefixes: Option<Arc<Vec<Bytes>>>,
289 recovery: Option<TrackingRecovery>,
290 invalidation: Option<InvalidationLifecycle>,
291 opt_in_dispatch: Option<OptInDispatch<S>>,
292}
293
294impl<S: Clone> Clone for CacheService<S> {
295 fn clone(&self) -> Self {
296 Self {
297 inner: self.inner.clone(),
298 cache: Arc::clone(&self.cache),
299 mutations_in_flight: Arc::clone(&self.mutations_in_flight),
300 data_health: self.data_health.clone(),
301 tracked_prefixes: self.tracked_prefixes.clone(),
302 recovery: self.recovery.clone(),
303 invalidation: self.invalidation.clone(),
304 opt_in_dispatch: self.opt_in_dispatch,
305 }
306 }
307}
308
309impl<S> CacheService<S> {
310 pub fn new(inner: S, config: CacheConfig) -> Self {
319 Self::without_invalidation(inner, config)
320 }
321
322 pub fn without_invalidation(inner: S, config: CacheConfig) -> Self {
324 warn_invalidation_free();
325 Self {
326 inner,
327 cache: Arc::new(RwLock::new(CacheState::new(config.max_size, config.ttl))),
328 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
329 data_health: None,
330 tracked_prefixes: None,
331 recovery: None,
332 invalidation: None,
333 opt_in_dispatch: None,
334 }
335 }
336
337 pub fn with_cache(inner: S, cache: Arc<RwLock<CacheState>>) -> Self {
344 warn_invalidation_free();
345 Self {
346 inner,
347 cache,
348 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
349 data_health: None,
350 tracked_prefixes: None,
351 recovery: None,
352 invalidation: None,
353 opt_in_dispatch: None,
354 }
355 }
356
357 pub fn with_invalidation_stream<T>(inner: S, config: CacheConfig, push_stream: T) -> Self
364 where
365 T: Stream<Item = Result<Frame, redis_tower_protocol::ProtocolError>> + Send + 'static,
366 {
367 let cache = Arc::new(RwLock::new(CacheState::new(config.max_size, config.ttl)));
368 let invalidation = own_invalidation_stream(Arc::clone(&cache), Box::pin(push_stream));
369 Self {
370 inner,
371 cache,
372 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
373 data_health: None,
374 tracked_prefixes: None,
375 recovery: None,
376 invalidation: Some(invalidation),
377 opt_in_dispatch: None,
378 }
379 }
380
381 pub fn with_invalidation_stream_and_recorder<T>(
389 inner: S,
390 config: CacheConfig,
391 push_stream: T,
392 recorder: Arc<dyn MetricsRecorder>,
393 ) -> Self
394 where
395 T: Stream<Item = Result<Frame, redis_tower_protocol::ProtocolError>> + Send + 'static,
396 {
397 let cache = Arc::new(RwLock::new(CacheState::new_with_recorder(
398 config.max_size,
399 config.ttl,
400 Some(recorder),
401 )));
402 let invalidation = own_invalidation_stream(Arc::clone(&cache), Box::pin(push_stream));
403 Self {
404 inner,
405 cache,
406 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
407 data_health: None,
408 tracked_prefixes: None,
409 recovery: None,
410 invalidation: Some(invalidation),
411 opt_in_dispatch: None,
412 }
413 }
414}
415
416impl<S> CacheService<S> {
417 pub fn inner(&self) -> &S {
419 &self.inner
420 }
421
422 pub fn inner_mut(&mut self) -> &mut S {
424 &mut self.inner
425 }
426
427 pub fn into_inner(self) -> S {
431 self.inner
432 }
433
434 pub fn cache(&self) -> &Arc<RwLock<CacheState>> {
436 &self.cache
437 }
438
439 pub async fn cache_size(&self) -> usize {
441 self.cache.read().await.len()
442 }
443
444 pub async fn clear_cache(&self) {
446 self.cache.write().await.clear();
447 }
448
449 pub async fn cache_statistics(&self) -> CacheStatistics {
451 self.cache.read().await.statistics()
452 }
453
454 pub async fn is_caching_healthy(&self) -> bool {
457 self.data_connection_is_healthy()
458 && self.mutations_in_flight.load(Ordering::Acquire) == 0
459 && self.cache.read().await.is_enabled()
460 }
461
462 fn data_connection_is_healthy(&self) -> bool {
463 self.data_health
464 .as_ref()
465 .is_none_or(DataConnectionHealth::is_usable)
466 }
467}
468
469impl CacheService<AutoPipelineService> {
470 pub(crate) async fn with_tracking(
472 inner: AutoPipelineService,
473 receiver_factory: Arc<dyn ConnectionFactory>,
474 config: &CachedClientConfig,
475 ) -> Result<Self, RedisError> {
476 let cache = Arc::new(RwLock::new(config.new_state()));
477 if !inner.is_connection_healthy() {
478 cache.write().await.disable();
479 return Err(RedisError::ConnectionClosed);
480 }
481 let data_health_rx = inner.subscribe_connection_health();
482 let data_health = DataConnectionHealth::new(data_health_rx.clone());
483 let tracking_inner = inner.clone();
484 let tracking_mode = config.tracking_mode.clone();
485 let configure: TrackingConfigurator = Arc::new(move |receiver_id| {
486 let mut inner = tracking_inner.clone();
487 let reset = ClientTracking::off();
488 let command = tracking_mode.tracking_command(receiver_id);
489 Box::pin(async move {
490 let mut responses = inner
491 .call_pipeline(vec![reset.to_frame(), command.to_frame()])
492 .await?
493 .into_iter();
494 reset.parse_response(responses.next().ok_or(RedisError::ConnectionClosed)?)?;
495 command.parse_response(responses.next().ok_or(RedisError::ConnectionClosed)?)
496 })
497 });
498 let invalidation = start_tracking_supervisor(
499 receiver_factory,
500 Arc::clone(&cache),
501 configure,
502 data_health_rx,
503 data_health.clone(),
504 )
505 .await?;
506 let recovery = invalidation.recovery();
507
508 Ok(Self {
509 inner,
510 cache,
511 mutations_in_flight: Arc::new(AtomicUsize::new(0)),
512 data_health: Some(data_health),
513 tracked_prefixes: match &config.tracking_mode {
514 crate::caching::CacheTrackingMode::Broadcast { prefixes } => {
515 Some(Arc::new(prefixes.clone()))
516 }
517 crate::caching::CacheTrackingMode::ServerDefault
518 | crate::caching::CacheTrackingMode::OptIn => None,
519 },
520 recovery,
521 invalidation: Some(invalidation),
522 opt_in_dispatch: config
523 .tracking_mode
524 .is_opt_in()
525 .then_some(dispatch_opt_in_auto_pipeline),
526 })
527 }
528
529 pub fn queue_depth(&self) -> usize {
531 self.inner.queue_depth()
532 }
533
534 pub async fn call_pipeline(&mut self, frames: Vec<Frame>) -> Result<Vec<Frame>, RedisError> {
537 for frame in &frames {
538 validate_cached_user_command(frame)?;
539 }
540 let guard = CacheMutationGuard::new(
541 Arc::clone(&self.cache),
542 Arc::clone(&self.mutations_in_flight),
543 self.recovery.clone(),
544 );
545 self.cache.write().await.clear();
546 let result = self.inner.call_pipeline(frames).await;
547 self.cache.write().await.clear();
548 guard.finish();
549 result
550 }
551
552 pub async fn shutdown(self) {
554 let Self {
555 inner,
556 invalidation,
557 ..
558 } = self;
559 if let Some(invalidation) = invalidation {
560 invalidation.shutdown().await;
561 }
562 inner.shutdown().await;
563 }
564}
565
566fn dispatch_opt_in_auto_pipeline(
567 inner: &mut AutoPipelineService,
568 request: Frame,
569) -> BoxRedisFuture<Frame> {
570 let caching = ClientCaching::new(true);
571 let future = inner.call_reserved_pipeline(vec![caching.to_frame(), request]);
572 Box::pin(async move {
573 let mut responses = future.await?.into_iter();
574 let setup = responses.next().ok_or(RedisError::ConnectionClosed)?;
575 caching.parse_response(setup)?;
576 responses.next().ok_or(RedisError::ConnectionClosed)
577 })
578}
579
580impl<S> Service<Frame> for CacheService<S>
581where
582 S: Service<Frame, Response = Frame, Error = RedisError> + ReleaseReadiness,
583 S::Future: Send + 'static,
584{
585 type Response = Frame;
586 type Error = RedisError;
587 type Future = BoxRedisFuture<Frame>;
588
589 fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
590 self.inner.poll_ready(cx)
591 }
592
593 fn call(&mut self, request: Frame) -> Self::Future {
594 if let Err(error) = validate_cached_user_command(&request) {
595 self.inner.release_readiness();
596 return Box::pin(async move { Err(error) });
597 }
598
599 let extracted_entry = extract_cache_entry(&request);
600 let entry = extracted_entry.clone().filter(|(_, redis_key)| {
601 self.tracked_prefixes.as_ref().is_none_or(|prefixes| {
602 prefixes.is_empty() || prefixes.iter().any(|prefix| redis_key.starts_with(prefix))
603 })
604 });
605
606 if extracted_entry.is_some() && entry.is_none() {
607 return Box::pin(self.inner.call(request));
611 }
612
613 if extracted_entry.is_none() && !command_may_mutate(&request) {
614 return Box::pin(self.inner.call(request));
615 }
616
617 let mut epoch = None;
618
619 if self.mutations_in_flight.load(Ordering::Acquire) == 0
620 && let Some((ref cache_key, ref redis_key)) = entry
621 && let Ok(cache) = self.cache.try_read()
622 && self.data_connection_is_healthy()
625 {
626 if let Some(cached) = cache.get(cache_key) {
627 let response = cached.clone();
628 drop(cache);
629 self.inner.release_readiness();
630 return Box::pin(async move { Ok(response) });
631 }
632 epoch = cache.snapshot_epoch(redis_key);
633 }
634
635 let request_for_invalidation = request.clone();
636 let mutation_guard = if entry.is_none() {
637 let guard = CacheMutationGuard::new(
640 Arc::clone(&self.cache),
641 Arc::clone(&self.mutations_in_flight),
642 self.recovery.clone(),
643 );
644 if let Ok(mut cache) = self.cache.try_write() {
645 cache.invalidate_for_command(&request_for_invalidation);
646 }
647 Some(guard)
648 } else {
649 None
650 };
651
652 let future = if entry.is_some() {
653 if let Some(dispatch) = self.opt_in_dispatch {
654 dispatch(&mut self.inner, request)
655 } else {
656 Box::pin(self.inner.call(request))
657 }
658 } else {
659 Box::pin(self.inner.call(request))
660 };
661 let cache = Arc::clone(&self.cache);
662
663 if entry.is_none() {
664 Box::pin(complete_mutation(
665 future,
666 cache,
667 mutation_guard.expect("mutation entry must have a guard"),
668 request_for_invalidation,
669 ))
670 } else {
671 let data_health = self.data_health.clone();
672 Box::pin(async move {
673 let result = future.await;
674 if let (Some((cache_key, redis_key)), Ok(response)) = (&entry, &result)
675 && !matches!(response, Frame::Error(_))
676 && let Some(epoch) = epoch
677 && data_health
678 .as_ref()
679 .is_none_or(DataConnectionHealth::is_usable)
680 {
681 cache.write().await.insert_if_current(
682 cache_key.clone(),
683 redis_key.clone(),
684 response.clone(),
685 epoch,
686 );
687 }
688 result
689 })
690 }
691 }
692}
693
694async fn complete_mutation(
695 future: BoxRedisFuture<Frame>,
696 cache: Arc<RwLock<CacheState>>,
697 guard: CacheMutationGuard,
698 request: Frame,
699) -> Result<Frame, RedisError> {
700 let result = future.await;
701 cache.write().await.invalidate_for_command(&request);
702 guard.finish();
703 result
704}
705
706fn warn_invalidation_free() {
707 static WARN_ONCE: Once = Once::new();
708 WARN_ONCE.call_once(|| {
709 tracing::warn!(
710 "client-side cache created without Redis invalidations; entries may be stale until TTL"
711 );
712 });
713}
714
715pub fn spawn_invalidation_task(
721 cache: Arc<RwLock<CacheState>>,
722 mut push_rx: impl Stream<Item = Result<Frame, redis_tower_protocol::ProtocolError>>
723 + Unpin
724 + Send
725 + 'static,
726) -> tokio::task::JoinHandle<()> {
727 use futures::StreamExt;
728 tokio::spawn(async move {
729 while let Some(Ok(frame)) = push_rx.next().await {
730 if let Some(keys) = parse_invalidation(&frame) {
731 let mut cache = cache.write().await;
732 if keys.is_empty() {
733 cache.clear();
734 } else {
735 for key in keys {
736 cache.invalidate(&key);
737 }
738 }
739 }
740 }
741 cache.write().await.disable();
742 })
743}
744
745#[cfg(test)]
746mod tests {
747 use super::*;
748 use crate::metrics_layer::{CacheEvent, ErrorKind};
749 use bytes::Bytes;
750 use std::sync::Mutex;
751 use std::sync::atomic::AtomicU64;
752
753 #[derive(Clone)]
754 struct CountingService {
755 call_count: Arc<Mutex<usize>>,
756 response: Frame,
757 }
758
759 #[derive(Default)]
760 struct RecordingCacheMetrics {
761 hits: AtomicU64,
762 misses: AtomicU64,
763 }
764
765 impl MetricsRecorder for RecordingCacheMetrics {
766 fn command_completed(
767 &self,
768 _command: &str,
769 _duration: Duration,
770 _error: Option<ErrorKind>,
771 ) {
772 }
773
774 fn cache_event(&self, event: CacheEvent, count: u64) {
775 let counter = match event {
776 CacheEvent::Hit => Some(&self.hits),
777 CacheEvent::Miss => Some(&self.misses),
778 CacheEvent::Invalidation | CacheEvent::Eviction => None,
779 };
780 if let Some(counter) = counter {
781 counter.fetch_add(count, Ordering::Relaxed);
782 }
783 }
784 }
785
786 impl Service<Frame> for CountingService {
787 type Response = Frame;
788 type Error = RedisError;
789 type Future = BoxRedisFuture<Frame>;
790
791 fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
792 Poll::Ready(Ok(()))
793 }
794
795 fn call(&mut self, _req: Frame) -> Self::Future {
796 let count = Arc::clone(&self.call_count);
797 let response = self.response.clone();
798 Box::pin(async move {
799 *count.lock().unwrap() += 1;
800 Ok(response)
801 })
802 }
803 }
804
805 impl ReleaseReadiness for CountingService {
806 fn release_readiness(&mut self) {}
807 }
808
809 #[derive(Clone)]
810 struct GatedReadService {
811 get_calls: Arc<AtomicUsize>,
812 first_get_started: Arc<tokio::sync::Semaphore>,
813 release_first_get: Arc<tokio::sync::Semaphore>,
814 }
815
816 impl Service<Frame> for GatedReadService {
817 type Response = Frame;
818 type Error = RedisError;
819 type Future = BoxRedisFuture<Frame>;
820
821 fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
822 Poll::Ready(Ok(()))
823 }
824
825 fn call(&mut self, request: Frame) -> Self::Future {
826 if !is_command(&request, b"GET") {
827 return Box::pin(async { Ok(Frame::SimpleString(Bytes::from_static(b"OK"))) });
828 }
829
830 let call_index = self.get_calls.fetch_add(1, Ordering::SeqCst);
831 let first_get_started = Arc::clone(&self.first_get_started);
832 let release_first_get = Arc::clone(&self.release_first_get);
833 Box::pin(async move {
834 if call_index == 0 {
835 first_get_started.add_permits(1);
836 release_first_get
837 .acquire_owned()
838 .await
839 .expect("first GET release semaphore must remain open")
840 .forget();
841 Ok(Frame::BulkString(Some(Bytes::from_static(b"stale"))))
842 } else {
843 Ok(Frame::BulkString(Some(Bytes::from_static(b"fresh"))))
844 }
845 })
846 }
847 }
848
849 impl ReleaseReadiness for GatedReadService {
850 fn release_readiness(&mut self) {}
851 }
852
853 #[derive(Clone)]
854 struct CancellableReadOnlyService {
855 get_calls: Arc<AtomicUsize>,
856 read_only_started: Arc<tokio::sync::Semaphore>,
857 }
858
859 impl Service<Frame> for CancellableReadOnlyService {
860 type Response = Frame;
861 type Error = RedisError;
862 type Future = BoxRedisFuture<Frame>;
863
864 fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
865 Poll::Ready(Ok(()))
866 }
867
868 fn call(&mut self, request: Frame) -> Self::Future {
869 if is_command(&request, b"GET") {
870 self.get_calls.fetch_add(1, Ordering::SeqCst);
871 return Box::pin(async {
872 Ok(Frame::BulkString(Some(Bytes::from_static(b"value"))))
873 });
874 }
875
876 let read_only_started = Arc::clone(&self.read_only_started);
877 Box::pin(async move {
878 read_only_started.add_permits(1);
879 std::future::pending::<Result<Frame, RedisError>>().await
880 })
881 }
882 }
883
884 impl ReleaseReadiness for CancellableReadOnlyService {
885 fn release_readiness(&mut self) {}
886 }
887
888 #[derive(Default)]
889 struct CapacityOneState {
890 reserved: bool,
891 calls: usize,
892 releases: usize,
893 }
894
895 struct CapacityOneService {
896 state: Arc<Mutex<CapacityOneState>>,
897 }
898
899 impl Service<Frame> for CapacityOneService {
900 type Response = Frame;
901 type Error = RedisError;
902 type Future = BoxRedisFuture<Frame>;
903
904 fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
905 let mut state = self.state.lock().unwrap();
906 if state.reserved {
907 Poll::Pending
908 } else {
909 state.reserved = true;
910 Poll::Ready(Ok(()))
911 }
912 }
913
914 fn call(&mut self, _request: Frame) -> Self::Future {
915 let mut state = self.state.lock().unwrap();
916 assert!(
917 state.reserved,
918 "call must consume capacity acquired by poll_ready"
919 );
920 state.reserved = false;
921 state.calls += 1;
922 Box::pin(async { Ok(Frame::BulkString(Some(Bytes::from_static(b"value")))) })
923 }
924 }
925
926 impl ReleaseReadiness for CapacityOneService {
927 fn release_readiness(&mut self) {
928 let mut state = self.state.lock().unwrap();
929 assert!(
930 state.reserved,
931 "a cache hit must follow successful poll_ready"
932 );
933 state.reserved = false;
934 state.releases += 1;
935 }
936 }
937
938 fn frame(parts: &[&str]) -> Frame {
939 Frame::Array(Some(
940 parts
941 .iter()
942 .map(|part| Frame::BulkString(Some(Bytes::copy_from_slice(part.as_bytes()))))
943 .collect(),
944 ))
945 }
946
947 fn is_command(request: &Frame, expected: &[u8]) -> bool {
948 let Frame::Array(Some(parts)) = request else {
949 return false;
950 };
951 let Some(Frame::BulkString(Some(command))) = parts.first() else {
952 return false;
953 };
954 command.as_ref().eq_ignore_ascii_case(expected)
955 }
956
957 async fn wait_for_permit(semaphore: &Arc<tokio::sync::Semaphore>) {
958 tokio::time::timeout(Duration::from_secs(1), semaphore.acquire())
959 .await
960 .expect("service future was not polled")
961 .expect("service semaphore must remain open")
962 .forget();
963 }
964
965 #[tokio::test]
966 async fn cloned_service_shares_entries() {
967 let calls = Arc::new(Mutex::new(0));
968 let inner = CountingService {
969 call_count: Arc::clone(&calls),
970 response: Frame::BulkString(Some(Bytes::from_static(b"value"))),
971 };
972 let mut first = CacheService::new(inner, CacheConfig::default());
973 let mut second = first.clone();
974
975 first.call(frame(&["GET", "key"])).await.unwrap();
976 second.call(frame(&["GET", "key"])).await.unwrap();
977 assert_eq!(*calls.lock().unwrap(), 1);
978 }
979
980 #[tokio::test]
981 async fn unhealthy_data_connection_bypasses_an_existing_cache_hit() {
982 let calls = Arc::new(Mutex::new(0));
983 let inner = CountingService {
984 call_count: Arc::clone(&calls),
985 response: Frame::BulkString(Some(Bytes::from_static(b"stale"))),
986 };
987 let mut service = CacheService::new(inner, CacheConfig::default());
988 let (health_tx, health_rx) = tokio::sync::watch::channel(true);
989 service.data_health = Some(DataConnectionHealth::new(health_rx));
990
991 assert_eq!(
992 service.call(frame(&["GET", "key"])).await.unwrap(),
993 Frame::BulkString(Some(Bytes::from_static(b"stale")))
994 );
995 assert_eq!(service.cache_size().await, 1);
996
997 service.inner.response = Frame::BulkString(Some(Bytes::from_static(b"fresh")));
998 health_tx.send_replace(false);
999
1000 assert_eq!(
1001 service.call(frame(&["GET", "key"])).await.unwrap(),
1002 Frame::BulkString(Some(Bytes::from_static(b"fresh")))
1003 );
1004 assert_eq!(*calls.lock().unwrap(), 2);
1005 assert!(!service.is_caching_healthy().await);
1006 }
1007
1008 #[tokio::test]
1009 async fn read_started_while_data_connection_is_unhealthy_is_not_cached() {
1010 let calls = Arc::new(Mutex::new(0));
1011 let inner = CountingService {
1012 call_count: Arc::clone(&calls),
1013 response: Frame::BulkString(Some(Bytes::from_static(b"value"))),
1014 };
1015 let mut service = CacheService::new(inner, CacheConfig::default());
1016 let (_health_tx, health_rx) = tokio::sync::watch::channel(false);
1017 service.data_health = Some(DataConnectionHealth::new(health_rx));
1018
1019 service.call(frame(&["GET", "key"])).await.unwrap();
1020
1021 assert_eq!(service.cache_size().await, 0);
1022 assert_eq!(*calls.lock().unwrap(), 1);
1023 }
1024
1025 #[tokio::test]
1026 async fn cache_hit_releases_capacity_one_readiness_reservation() {
1027 let state = Arc::new(Mutex::new(CapacityOneState::default()));
1028 let inner = CapacityOneService {
1029 state: Arc::clone(&state),
1030 };
1031 let mut service = CacheService::new(inner, CacheConfig::default());
1032
1033 std::future::poll_fn(|cx| service.poll_ready(cx))
1034 .await
1035 .unwrap();
1036 service.call(frame(&["GET", "cached"])).await.unwrap();
1037
1038 std::future::poll_fn(|cx| service.poll_ready(cx))
1039 .await
1040 .unwrap();
1041 service.call(frame(&["GET", "cached"])).await.unwrap();
1042
1043 tokio::time::timeout(
1044 Duration::from_millis(100),
1045 std::future::poll_fn(|cx| service.poll_ready(cx)),
1046 )
1047 .await
1048 .expect("cache hit must restore the only readiness permit")
1049 .unwrap();
1050 service.call(frame(&["GET", "other"])).await.unwrap();
1051
1052 let state = state.lock().unwrap();
1053 assert_eq!(state.calls, 2);
1054 assert_eq!(state.releases, 1);
1055 }
1056
1057 #[tokio::test]
1058 async fn managed_connection_state_is_rejected_and_releases_readiness() {
1059 let state = Arc::new(Mutex::new(CapacityOneState::default()));
1060 let inner = CapacityOneService {
1061 state: Arc::clone(&state),
1062 };
1063 let mut service = CacheService::new(inner, CacheConfig::default());
1064
1065 std::future::poll_fn(|cx| service.poll_ready(cx))
1066 .await
1067 .unwrap();
1068 let error = service
1069 .call(frame(&["CLIENT", "TRACKING", "OFF"]))
1070 .await
1071 .unwrap_err();
1072 assert!(error.to_string().contains("managed internally"));
1073
1074 tokio::time::timeout(
1075 Duration::from_millis(100),
1076 std::future::poll_fn(|cx| service.poll_ready(cx)),
1077 )
1078 .await
1079 .expect("rejected command must return the readiness permit")
1080 .unwrap();
1081 service.call(frame(&["GET", "key"])).await.unwrap();
1082
1083 let state = state.lock().unwrap();
1084 assert_eq!(state.calls, 1);
1085 assert_eq!(state.releases, 1);
1086 }
1087
1088 #[tokio::test]
1089 async fn owned_invalidation_stream_can_emit_cache_metrics() {
1090 let calls = Arc::new(Mutex::new(0));
1091 let recorder = Arc::new(RecordingCacheMetrics::default());
1092 let metrics: Arc<dyn MetricsRecorder> = recorder.clone();
1093 let stream =
1094 futures::stream::pending::<Result<Frame, redis_tower_protocol::ProtocolError>>();
1095 let inner = CountingService {
1096 call_count: Arc::clone(&calls),
1097 response: Frame::BulkString(Some(Bytes::from_static(b"value"))),
1098 };
1099 let mut service = CacheService::with_invalidation_stream_and_recorder(
1100 inner,
1101 CacheConfig::default(),
1102 stream,
1103 metrics,
1104 );
1105
1106 service.call(frame(&["GET", "key"])).await.unwrap();
1107 service.call(frame(&["GET", "key"])).await.unwrap();
1108
1109 assert_eq!(recorder.misses.load(Ordering::Relaxed), 1);
1110 assert_eq!(recorder.hits.load(Ordering::Relaxed), 1);
1111 assert_eq!(*calls.lock().unwrap(), 1);
1112 }
1113
1114 #[tokio::test]
1115 async fn local_write_invalidation_rejects_racing_insert() {
1116 let calls = Arc::new(Mutex::new(0));
1117 let inner = CountingService {
1118 call_count: Arc::clone(&calls),
1119 response: Frame::BulkString(Some(Bytes::from_static(b"value"))),
1120 };
1121 let mut service = CacheService::new(inner, CacheConfig::default());
1122 service.call(frame(&["GET", "key"])).await.unwrap();
1123 service.call(frame(&["SET", "key", "new"])).await.unwrap();
1124 assert_eq!(service.cache_size().await, 0);
1125 }
1126
1127 #[tokio::test]
1128 async fn late_get_response_is_not_cached_after_local_write() {
1129 let get_calls = Arc::new(AtomicUsize::new(0));
1130 let first_get_started = Arc::new(tokio::sync::Semaphore::new(0));
1131 let release_first_get = Arc::new(tokio::sync::Semaphore::new(0));
1132 let inner = GatedReadService {
1133 get_calls: Arc::clone(&get_calls),
1134 first_get_started: Arc::clone(&first_get_started),
1135 release_first_get: Arc::clone(&release_first_get),
1136 };
1137 let mut service = CacheService::new(inner, CacheConfig::default());
1138 let mut reader = service.clone();
1139
1140 let stale_read =
1141 tokio::spawn(async move { reader.call(frame(&["GET", "key"])).await.unwrap() });
1142 wait_for_permit(&first_get_started).await;
1143
1144 service.call(frame(&["SET", "key", "new"])).await.unwrap();
1145 release_first_get.add_permits(1);
1146 assert_eq!(
1147 stale_read.await.unwrap(),
1148 Frame::BulkString(Some(Bytes::from_static(b"stale")))
1149 );
1150 assert_eq!(service.cache_size().await, 0);
1151
1152 assert_eq!(
1153 service.call(frame(&["GET", "key"])).await.unwrap(),
1154 Frame::BulkString(Some(Bytes::from_static(b"fresh")))
1155 );
1156 service.call(frame(&["GET", "key"])).await.unwrap();
1157 assert_eq!(get_calls.load(Ordering::SeqCst), 2);
1158 }
1159
1160 #[tokio::test]
1161 async fn read_started_while_disabled_is_not_cached_after_reenable() {
1162 let get_calls = Arc::new(AtomicUsize::new(0));
1163 let first_get_started = Arc::new(tokio::sync::Semaphore::new(0));
1164 let release_first_get = Arc::new(tokio::sync::Semaphore::new(0));
1165 let inner = GatedReadService {
1166 get_calls: Arc::clone(&get_calls),
1167 first_get_started: Arc::clone(&first_get_started),
1168 release_first_get: Arc::clone(&release_first_get),
1169 };
1170 let mut service = CacheService::new(inner, CacheConfig::default());
1171 service.cache.write().await.disable();
1172 let mut reader = service.clone();
1173
1174 let untracked_read =
1175 tokio::spawn(async move { reader.call(frame(&["GET", "key"])).await.unwrap() });
1176 wait_for_permit(&first_get_started).await;
1177
1178 service.cache.write().await.enable();
1179 release_first_get.add_permits(1);
1180 assert_eq!(
1181 untracked_read.await.unwrap(),
1182 Frame::BulkString(Some(Bytes::from_static(b"stale")))
1183 );
1184 assert_eq!(service.cache_size().await, 0);
1185
1186 assert_eq!(
1187 service.call(frame(&["GET", "key"])).await.unwrap(),
1188 Frame::BulkString(Some(Bytes::from_static(b"fresh")))
1189 );
1190 service.call(frame(&["GET", "key"])).await.unwrap();
1191 assert_eq!(get_calls.load(Ordering::SeqCst), 2);
1192 }
1193
1194 #[tokio::test]
1195 async fn coalesced_data_health_outage_rejects_an_old_read() {
1196 let get_calls = Arc::new(AtomicUsize::new(0));
1197 let first_get_started = Arc::new(tokio::sync::Semaphore::new(0));
1198 let release_first_get = Arc::new(tokio::sync::Semaphore::new(0));
1199 let inner = GatedReadService {
1200 get_calls: Arc::clone(&get_calls),
1201 first_get_started: Arc::clone(&first_get_started),
1202 release_first_get: Arc::clone(&release_first_get),
1203 };
1204 let mut service = CacheService::new(inner, CacheConfig::default());
1205 let (health_tx, health_rx) = tokio::sync::watch::channel(true);
1206 service.data_health = Some(DataConnectionHealth::new(health_rx));
1207 let mut reader = service.clone();
1208
1209 let old_connection_read =
1210 tokio::spawn(async move { reader.call(frame(&["GET", "key"])).await.unwrap() });
1211 wait_for_permit(&first_get_started).await;
1212
1213 health_tx.send_replace(false);
1214 health_tx.send_replace(true);
1215 release_first_get.add_permits(1);
1216
1217 assert_eq!(
1218 old_connection_read.await.unwrap(),
1219 Frame::BulkString(Some(Bytes::from_static(b"stale")))
1220 );
1221 assert_eq!(service.cache_size().await, 0);
1222 assert!(!service.is_caching_healthy().await);
1223
1224 service.cache.write().await.disable();
1225 assert!(
1226 service
1227 .data_health
1228 .as_ref()
1229 .expect("data-health gate")
1230 .begin_reconfigure()
1231 );
1232 assert!(
1233 service
1234 .data_health
1235 .as_ref()
1236 .expect("data-health gate")
1237 .mark_reconfigured()
1238 );
1239 service.cache.write().await.enable();
1240
1241 assert_eq!(
1242 service.call(frame(&["GET", "key"])).await.unwrap(),
1243 Frame::BulkString(Some(Bytes::from_static(b"fresh")))
1244 );
1245 service.call(frame(&["GET", "key"])).await.unwrap();
1246 assert_eq!(get_calls.load(Ordering::SeqCst), 2);
1247 }
1248
1249 #[tokio::test]
1250 async fn broadcast_prefixes_bypass_keys_redis_will_not_invalidate() {
1251 let calls = Arc::new(Mutex::new(0));
1252 let inner = CountingService {
1253 call_count: Arc::clone(&calls),
1254 response: Frame::BulkString(Some(Bytes::from_static(b"value"))),
1255 };
1256 let mut service = CacheService::new(inner, CacheConfig::default());
1257 service.tracked_prefixes = Some(Arc::new(vec![Bytes::from_static(b"tracked:")]));
1258
1259 service.call(frame(&["GET", "outside:key"])).await.unwrap();
1260 service.call(frame(&["GET", "outside:key"])).await.unwrap();
1261
1262 assert_eq!(*calls.lock().unwrap(), 2);
1263 assert_eq!(service.cache_size().await, 0);
1264 }
1265
1266 #[tokio::test]
1267 async fn dropping_unpolled_mutation_fails_cache_closed() {
1268 let calls = Arc::new(Mutex::new(0));
1269 let inner = CountingService {
1270 call_count: Arc::clone(&calls),
1271 response: Frame::BulkString(Some(Bytes::from_static(b"value"))),
1272 };
1273 let mut service = CacheService::new(inner, CacheConfig::default());
1274 service.call(frame(&["GET", "key"])).await.unwrap();
1275 assert_eq!(service.cache_size().await, 1);
1276
1277 let mutation = service.call(frame(&["SET", "key", "new"]));
1278 drop(mutation);
1279
1280 assert!(!service.is_caching_healthy().await);
1281 assert_eq!(service.cache_size().await, 0);
1282 assert_eq!(
1283 *calls.lock().unwrap(),
1284 1,
1285 "dropping the future must not keep polling the command"
1286 );
1287 }
1288
1289 #[tokio::test]
1290 async fn cancelling_dispatched_read_only_commands_keeps_cache_healthy() {
1291 let get_calls = Arc::new(AtomicUsize::new(0));
1292 let read_only_started = Arc::new(tokio::sync::Semaphore::new(0));
1293 let inner = CancellableReadOnlyService {
1294 get_calls: Arc::clone(&get_calls),
1295 read_only_started: Arc::clone(&read_only_started),
1296 };
1297 let mut service = CacheService::new(inner, CacheConfig::default());
1298
1299 service.call(frame(&["GET", "key"])).await.unwrap();
1300 assert_eq!(service.cache_size().await, 1);
1301
1302 for request in [frame(&["PING"]), frame(&["TTL", "key"])] {
1303 let mut dispatched = service.clone();
1304 let task = tokio::spawn(async move { dispatched.call(request).await });
1305 wait_for_permit(&read_only_started).await;
1306 task.abort();
1307 assert!(task.await.unwrap_err().is_cancelled());
1308 }
1309
1310 assert_eq!(service.cache_size().await, 1);
1311 assert!(service.is_caching_healthy().await);
1312 service.call(frame(&["GET", "key"])).await.unwrap();
1313 assert_eq!(get_calls.load(Ordering::SeqCst), 1);
1314 }
1315
1316 #[tokio::test]
1317 async fn invalidation_task_disables_cache_when_stream_ends() {
1318 let cache = Arc::new(RwLock::new(CacheState::default()));
1319 let stream =
1320 futures::stream::iter(Vec::<Result<Frame, redis_tower_protocol::ProtocolError>>::new());
1321 spawn_invalidation_task(Arc::clone(&cache), stream)
1322 .await
1323 .unwrap();
1324 assert!(!cache.read().await.is_enabled());
1325 }
1326
1327 #[test]
1328 fn cache_layer_is_a_real_tower_layer() {
1329 fn assert_layer<L: Layer<CountingService>>() {}
1330 assert_layer::<CacheLayer>();
1331 }
1332}