:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
//! Read-through cache implementation with Redis backing
//!
//! This module provides the main [`ReadThroughCache`] type that implements the read-through
//! caching pattern with support for:
//! - Redis-based positive caching
//! - Optional in-memory negative caching
//! - Cache corruption handling
//! - Graceful Redis degradation
use crate::{CacheConfig, CacheResult, CacheSource, NegativeCache};
use common_redis::{Client as RedisClient, CustomRedisError};
use serde::{Deserialize, Serialize};
use std::fmt::Display;
use std::future::Future;
use std::sync::Arc;
/// A generic read-through cache that supports:
/// - Redis-based positive caching with configurable TTL
/// - Optional in-memory negative caching to prevent repeated loader invocations for missing keys
/// - Function-based loader API (no trait implementations required)
/// - User-defined error types
/// - Rich return types for observability
/// - Cache corruption handling
///
/// The cache follows the "cache-aside" pattern:
/// 1. Try to get data from Redis cache
/// 2. On cache miss, check negative cache (if enabled)
/// 3. On negative cache miss, call the loader function
/// 4. If loader succeeds, update positive cache and invalidate negative cache
/// 5. If loader returns None, add to negative cache
///
/// # Example
/// ```rust,ignore
/// use common_cache::{ReadThroughCache, CacheConfig, CacheSource};
///
/// let cache = ReadThroughCache::new(
/// redis_reader,
/// redis_writer,
/// CacheConfig::with_ttl("my_data:", 300),
/// None, // no negative cache
/// );
///
/// let result = cache
/// .get_or_load(&key, |key| async {
/// load_from_source(key).await
/// })
/// .await?;
///
/// match result.source {
/// CacheSource::PositiveCache => println!("Cache hit!"),
/// CacheSource::LoaderCacheMiss => println!("Loaded from source"),
/// _ => {}
/// }
/// ```
pub struct ReadThroughCache {
redis_reader: Arc<dyn RedisClient + Send + Sync>,
redis_writer: Arc<dyn RedisClient + Send + Sync>,
config: CacheConfig,
negative_cache: Option<Arc<NegativeCache>>,
}
impl ReadThroughCache {
/// Create a new read-through cache instance
///
/// # Arguments
/// * `redis_reader` - Redis client for reading cached data
/// * `redis_writer` - Redis client for writing cached data
/// * `config` - Cache configuration (prefix, TTL)
/// * `negative_cache` - Optional negative cache to prevent repeated loader invocations for missing keys
pub fn new(
redis_reader: Arc<dyn RedisClient + Send + Sync>,
redis_writer: Arc<dyn RedisClient + Send + Sync>,
config: CacheConfig,
negative_cache: Option<Arc<NegativeCache>>,
) -> Self {
Self {
redis_reader,
redis_writer,
config,
negative_cache,
}
}
/// Get a value from cache or load it using the loader function
///
/// This is the main API for the cache. It:
/// 1. Tries Redis cache
/// 2. On miss, checks negative cache (if enabled)
/// 3. On negative cache miss, calls loader function with the key
/// 4. Updates caches based on the result
///
/// The loader function should return `Option<V>` where:
/// - `Some(value)` indicates the item was found
/// - `None` indicates the item doesn't exist (will be negative cached)
///
/// # Type Parameters
/// * `K` - Key type (must be displayable for logging)
/// * `V` - Value type (must be serializable)
/// * `E` - Error type (user-defined, for loader errors)
/// * `F` - Loader function type
/// * `Fut` - Future returned by loader function
///
/// # Arguments
/// * `key` - The key to look up
/// * `loader` - Function to call on cache miss, receives the key as parameter
///
/// # Returns
/// * `Ok(CacheResult)` - Contains the value (if found) and source information
/// * `Err(error)` - Error from loader function
pub async fn get_or_load<K, V, E, F, Fut>(
&self,
key: &K,
loader: F,
) -> Result<CacheResult<V>, E>
where
K: Serialize + Display + Send + Sync,
V: Serialize + for<'de> Deserialize<'de> + Send + Sync,
F: FnOnce(&K) -> Fut,
Fut: Future<Output = Result<Option<V>, E>>,
E: Send + Sync,
{
let cache_key = self.build_cache_key(key);
// Try to get from Redis cache
match self.get_from_redis(&cache_key).await {
Ok(cached_value) => {
// Positive cache hit
tracing::debug!("Positive cache hit for key: {}", key);
Ok(CacheResult::found(cached_value, CacheSource::PositiveCache))
}
Err(cache_error) => {
// Cache miss or error - need to fetch from loader
self.handle_cache_miss(key, &cache_key, cache_error, loader)
.await
}
}
}
/// Build the full Redis cache key from the user key
fn build_cache_key<K>(&self, key: &K) -> String
where
K: Display,
{
format!("{}{}", self.config.cache_prefix, key)
}
/// Get a value from Redis cache
async fn get_from_redis<V>(&self, cache_key: &str) -> Result<V, CustomRedisError>
where
V: for<'de> Deserialize<'de>,
{
let serialized_value = self.redis_reader.get(cache_key.to_string()).await?;
let value = serde_json::from_str(&serialized_value).map_err(|e| {
CustomRedisError::ParseError(format!("Failed to deserialize cached value: {e}"))
})?;
Ok(value)
}
/// Handle cache miss by calling loader and updating caches
async fn handle_cache_miss<K, V, E, F, Fut>(
&self,
key: &K,
cache_key: &str,
cache_error: CustomRedisError,
loader: F,
) -> Result<CacheResult<V>, E>
where
K: Display + Send + Sync,
V: Serialize + Send + Sync,
F: FnOnce(&K) -> Fut,
Fut: Future<Output = Result<Option<V>, E>>,
E: Send + Sync,
{
// Log Redis problems before checking negative cache — these
// indicate real issues even if we short-circuit via negative cache
match &cache_error {
CustomRedisError::ParseError(err) => {
tracing::warn!(
"Cache corruption detected for key {}: {}. Will refresh from source.",
key,
err
);
}
CustomRedisError::Timeout
| CustomRedisError::Redis(_)
| CustomRedisError::InvalidConfiguration(_) => {
tracing::warn!(
"Redis infrastructure issue for key {}: {:?}. Operating without cache.",
key,
cache_error
);
}
CustomRedisError::NotFound => {}
}
// Check negative cache before calling loader, but always refresh on
// corruption so corrupted Redis entries get repaired
if !matches!(&cache_error, CustomRedisError::ParseError(_)) {
if let Some(neg_cache) = &self.negative_cache {
if neg_cache.contains(cache_key) {
tracing::debug!("Negative cache hit for key: {}", key);
return Ok(CacheResult::not_found(CacheSource::NegativeCache));
}
}
}
match cache_error {
CustomRedisError::NotFound => {
self.load_and_cache(
key,
cache_key,
loader,
CacheSource::LoaderCacheMiss,
CacheSource::LoaderNotFoundCacheMiss,
)
.await
}
CustomRedisError::ParseError(_) => {
// Best-effort delete the corrupted key so subsequent calls
// see a clean NotFound instead of re-hitting ParseError
if let Err(e) = self.redis_writer.del(cache_key.to_string()).await {
tracing::warn!("Failed to delete corrupted cache key {}: {:?}", key, e);
}
self.load_and_cache(
key,
cache_key,
loader,
CacheSource::LoaderCacheCorrupted,
CacheSource::LoaderNotFoundCacheCorrupted,
)
.await
}
CustomRedisError::Timeout
| CustomRedisError::Redis(_)
| CustomRedisError::InvalidConfiguration(_) => {
self.handle_redis_unavailable(key, loader).await
}
}
}
/// Load from source and update caches accordingly.
/// Used for both cache misses and corrupted cache entries.
async fn load_and_cache<K, V, E, F, Fut>(
&self,
key: &K,
cache_key: &str,
loader: F,
found_source: CacheSource,
not_found_source: CacheSource,
) -> Result<CacheResult<V>, E>
where
K: Display + Send + Sync,
V: Serialize + Send + Sync,
F: FnOnce(&K) -> Fut,
Fut: Future<Output = Result<Option<V>, E>>,
E: Send + Sync,
{
match loader(key).await? {
Some(value) => {
if let Some(neg_cache) = &self.negative_cache {
neg_cache.invalidate(cache_key);
}
if let Err(redis_err) = self.set_in_redis(cache_key, &value).await {
tracing::warn!(
"Failed to update cache for key {} ({:?}): {:?}",
key,
found_source,
redis_err
);
}
Ok(CacheResult::found(value, found_source))
}
None => {
if let Some(neg_cache) = &self.negative_cache {
neg_cache.insert(cache_key.to_string());
}
Ok(CacheResult::not_found(not_found_source))
}
}
}
/// Handle Redis being unavailable
async fn handle_redis_unavailable<K, V, E, F, Fut>(
&self,
key: &K,
loader: F,
) -> Result<CacheResult<V>, E>
where
K: Display + Send + Sync,
V: Serialize + Send + Sync,
F: FnOnce(&K) -> Fut,
Fut: Future<Output = Result<Option<V>, E>>,
E: Send + Sync,
{
// Don't update any caches when Redis is having issues
match loader(key).await? {
Some(value) => Ok(CacheResult::found(
value,
CacheSource::LoaderRedisUnavailable,
)),
None => Ok(CacheResult::not_found(
CacheSource::LoaderNotFoundRedisUnavailable,
)),
}
}
/// Write a value to Redis cache
async fn set_in_redis<V>(&self, cache_key: &str, value: &V) -> Result<(), CustomRedisError>
where
V: Serialize,
{
let serialized_value = serde_json::to_string(value).map_err(|e| {
CustomRedisError::ParseError(format!("Failed to serialize value for cache: {e}"))
})?;
match self.config.ttl_seconds {
Some(ttl) => {
self.redis_writer
.setex(cache_key.to_string(), serialized_value, ttl)
.await
}
None => {
self.redis_writer
.set(cache_key.to_string(), serialized_value)
.await
}
}
}
/// Invalidate a key from both positive and negative caches
/// Errors from Redis deletion are logged but not returned, as invalidation
/// is best-effort and shouldn't block the calling operation.
/// # Arguments
/// * `key` - The key to invalidate
pub async fn invalidate<K>(&self, key: &K) -> Result<(), CustomRedisError>
where
K: Display,
{
let cache_key = self.build_cache_key(key);
// Remove from Redis
if let Err(e) = self.redis_writer.del(cache_key.clone()).await {
tracing::warn!("Failed to delete cache key {}: {:?}", cache_key, e);
}
// Remove from negative cache
if let Some(neg_cache) = &self.negative_cache {
neg_cache.invalidate(&cache_key);
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
use common_redis::{MockRedisClient, RedisErrorKind};
use serde::{Deserialize, Serialize};
use std::sync::Arc;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct TestData {
id: i32,
name: String,
}
fn setup_cache(
reader: MockRedisClient,
writer: MockRedisClient,
negative_cache: Option<Arc<NegativeCache>>,
) -> ReadThroughCache {
let config = CacheConfig::with_ttl("test:", 300);
ReadThroughCache::new(Arc::new(reader), Arc::new(writer), config, negative_cache)
}
#[tokio::test]
async fn test_positive_cache_hit() {
let data = TestData {
id: 1,
name: "test".to_string(),
};
let serialized = serde_json::to_string(&data).unwrap();
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Ok(serialized));
let cache = setup_cache(reader, MockRedisClient::new(), None);
let result = cache
.get_or_load(&"key1", |_key| async {
Ok::<Option<TestData>, String>(None)
})
.await
.unwrap();
assert_eq!(result.value, Some(data));
assert_eq!(result.source, CacheSource::PositiveCache);
assert!(result.was_cached());
assert!(!result.invoked_loader());
}
#[tokio::test]
async fn test_cache_miss_loads_and_caches() {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Err(CustomRedisError::NotFound));
let mut writer = MockRedisClient::new();
writer.set_ret("test:key1", Ok(()));
let cache = setup_cache(reader, writer.clone(), None);
let data = TestData {
id: 1,
name: "loaded".to_string(),
};
let expected_data = data.clone();
let result = cache
.get_or_load(&"key1", |_key| async move {
Ok::<Option<TestData>, String>(Some(expected_data))
})
.await
.unwrap();
assert_eq!(result.value, Some(data));
assert_eq!(result.source, CacheSource::LoaderCacheMiss);
assert!(!result.was_cached());
assert!(result.invoked_loader());
// Verify cache was written to
let calls = writer.get_calls();
assert_eq!(calls.len(), 1);
assert_eq!(calls[0].op, "setex");
assert_eq!(calls[0].key, "test:key1");
}
#[tokio::test]
async fn test_cache_miss_not_found_returns_none() {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Err(CustomRedisError::NotFound));
let cache = setup_cache(reader, MockRedisClient::new(), None);
let result = cache
.get_or_load(&"key1", |_key| async {
Ok::<Option<TestData>, String>(None)
})
.await
.unwrap();
assert_eq!(result.value, None);
assert_eq!(result.source, CacheSource::LoaderNotFoundCacheMiss);
assert!(!result.was_cached());
assert!(result.invoked_loader());
}
#[tokio::test]
async fn test_cache_corruption_reloads_and_refreshes() {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Ok("invalid json{".to_string()));
let mut writer = MockRedisClient::new();
writer.del_ret("test:key1", Ok(()));
writer.set_ret("test:key1", Ok(()));
let cache = setup_cache(reader, writer.clone(), None);
let data = TestData {
id: 1,
name: "refreshed".to_string(),
};
let expected_data = data.clone();
let result = cache
.get_or_load(&"key1", |_key| async move {
Ok::<Option<TestData>, String>(Some(expected_data))
})
.await
.unwrap();
assert_eq!(result.value, Some(data));
assert_eq!(result.source, CacheSource::LoaderCacheCorrupted);
assert!(!result.was_cached());
assert!(result.invoked_loader());
assert!(result.had_cache_problem());
// Verify corrupted key was deleted and cache was refreshed
let calls = writer.get_calls();
assert_eq!(calls.len(), 2);
assert_eq!(calls[0].op, "del");
assert_eq!(calls[0].key, "test:key1");
assert_eq!(calls[1].op, "setex");
}
#[tokio::test]
async fn test_cache_corruption_not_found() {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Ok("invalid json{".to_string()));
let mut writer = MockRedisClient::new();
writer.del_ret("test:key1", Ok(()));
let cache = setup_cache(reader, writer.clone(), None);
let result = cache
.get_or_load(&"key1", |_key| async {
Ok::<Option<TestData>, String>(None)
})
.await
.unwrap();
assert_eq!(result.value, None);
assert_eq!(result.source, CacheSource::LoaderNotFoundCacheCorrupted);
assert!(result.had_cache_problem());
// Verify corrupted key was deleted so subsequent calls don't
// keep hitting ParseError in a loop
let calls = writer.get_calls();
assert_eq!(calls.len(), 1);
assert_eq!(calls[0].op, "del");
assert_eq!(calls[0].key, "test:key1");
}
async fn test_redis_infrastructure_error_skips_cache_write_impl(redis_error: CustomRedisError) {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Err(redis_error));
let writer = MockRedisClient::new();
let cache = setup_cache(reader, writer.clone(), None);
let data = TestData {
id: 1,
name: "from_loader".to_string(),
};
let expected_data = data.clone();
let result = cache
.get_or_load(&"key1", |_key| async move {
Ok::<Option<TestData>, String>(Some(expected_data))
})
.await
.unwrap();
assert_eq!(result.value, Some(data));
assert_eq!(result.source, CacheSource::LoaderRedisUnavailable);
assert!(result.had_cache_problem());
assert!(result.invoked_loader());
// Verify NO cache write occurred
let calls = writer.get_calls();
assert_eq!(calls.len(), 0);
}
#[tokio::test]
async fn test_redis_timeout_skips_cache_write() {
test_redis_infrastructure_error_skips_cache_write_impl(CustomRedisError::Timeout).await;
}
#[tokio::test]
async fn test_redis_other_error_skips_cache_write() {
let error =
CustomRedisError::from_redis_kind(RedisErrorKind::IoError, "connection refused");
test_redis_infrastructure_error_skips_cache_write_impl(error).await;
}
async fn test_redis_infrastructure_error_not_found_impl(redis_error: CustomRedisError) {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Err(redis_error));
let negative_cache = Arc::new(NegativeCache::new(100, 300));
let cache = setup_cache(reader, MockRedisClient::new(), Some(negative_cache.clone()));
let result = cache
.get_or_load(&"key1", |_key| async {
Ok::<Option<TestData>, String>(None)
})
.await
.unwrap();
assert_eq!(result.value, None);
assert_eq!(result.source, CacheSource::LoaderNotFoundRedisUnavailable);
assert!(result.had_cache_problem());
// Verify negative cache was NOT updated (don't poison cache when Redis is down)
assert!(!negative_cache.contains("test:key1"));
}
#[tokio::test]
async fn test_redis_timeout_not_found() {
test_redis_infrastructure_error_not_found_impl(CustomRedisError::Timeout).await;
}
#[tokio::test]
async fn test_redis_other_error_not_found() {
let error = CustomRedisError::from_redis_kind(RedisErrorKind::IoError, "network error");
test_redis_infrastructure_error_not_found_impl(error).await;
}
#[tokio::test]
async fn test_negative_cache_hit() {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Err(CustomRedisError::NotFound));
let negative_cache = Arc::new(NegativeCache::new(100, 300));
let cache = setup_cache(reader, MockRedisClient::new(), Some(negative_cache.clone()));
// First call - cache miss, loader returns None
let result = cache
.get_or_load(&"key1", |_key| async {
Ok::<Option<TestData>, String>(None)
})
.await
.unwrap();
assert_eq!(result.value, None);
assert_eq!(result.source, CacheSource::LoaderNotFoundCacheMiss);
// Second call - should hit negative cache without invoking loader
let result: CacheResult<TestData> = cache
.get_or_load(&"key1", |_key| async {
panic!("Loader should not be called for negative cache hit");
#[allow(unreachable_code)]
Ok::<Option<TestData>, String>(None)
})
.await
.unwrap();
assert_eq!(result.value, None);
assert_eq!(result.source, CacheSource::NegativeCache);
assert!(result.was_cached());
assert!(!result.invoked_loader());
}
#[tokio::test]
async fn test_negative_cache_invalidated_on_found() {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Err(CustomRedisError::NotFound));
let mut writer = MockRedisClient::new();
writer.set_ret("test:key1", Ok(()));
let negative_cache = Arc::new(NegativeCache::new(100, 300));
let cache = setup_cache(reader, writer, Some(negative_cache.clone()));
// First call - loader returns None, should add to negative cache
let result = cache
.get_or_load(&"key1", |_key| async {
Ok::<Option<TestData>, String>(None)
})
.await
.unwrap();
assert_eq!(result.value, None);
assert_eq!(result.source, CacheSource::LoaderNotFoundCacheMiss);
assert!(negative_cache.contains("test:key1"));
// Second call - this time loader would return Some if called
// But negative cache will return early
let result: CacheResult<TestData> = cache
.get_or_load(&"key1", |_key| async {
Ok::<Option<TestData>, String>(Some(TestData {
id: 1,
name: "found".to_string(),
}))
})
.await
.unwrap();
// Should hit negative cache
assert_eq!(result.value, None);
assert_eq!(result.source, CacheSource::NegativeCache);
// Now invalidate the cache entry
cache.invalidate(&"key1").await.unwrap();
assert!(!negative_cache.contains("test:key1"));
// Third call - after invalidation, loader should be invoked
let data = TestData {
id: 1,
name: "found".to_string(),
};
let expected_data = data.clone();
let result = cache
.get_or_load(&"key1", |_key| async move {
Ok::<Option<TestData>, String>(Some(expected_data))
})
.await
.unwrap();
assert_eq!(result.value, Some(data));
assert_eq!(result.source, CacheSource::LoaderCacheMiss);
// Verify negative cache was NOT re-added (since we found a value)
assert!(!negative_cache.contains("test:key1"));
}
#[tokio::test]
async fn test_redis_hit_takes_priority_over_negative_cache() {
let data = TestData {
id: 1,
name: "from_redis".to_string(),
};
let serialized = serde_json::to_string(&data).unwrap();
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Ok(serialized));
let negative_cache = Arc::new(NegativeCache::new(100, 300));
negative_cache.insert("test:key1".to_string());
let cache = setup_cache(reader, MockRedisClient::new(), Some(negative_cache.clone()));
let result = cache
.get_or_load(&"key1", |_key| async {
panic!("Loader should not be called when Redis has the value");
#[allow(unreachable_code)]
Ok::<Option<TestData>, String>(None)
})
.await
.unwrap();
assert_eq!(result.value, Some(data));
assert_eq!(result.source, CacheSource::PositiveCache);
assert!(result.was_cached());
assert!(!result.invoked_loader());
}
#[tokio::test]
async fn test_invalidate_clears_both_caches() {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Ok(serde_json::to_string(&"cached").unwrap()));
let mut writer = MockRedisClient::new();
writer.del_ret("test:key1", Ok(()));
let negative_cache = Arc::new(NegativeCache::new(100, 300));
negative_cache.insert("test:key1".to_string());
let cache = setup_cache(reader, writer.clone(), Some(negative_cache.clone()));
cache.invalidate(&"key1").await.unwrap();
// Verify Redis delete was called
let calls = writer.get_calls();
assert_eq!(calls.len(), 1);
assert_eq!(calls[0].op, "del");
assert_eq!(calls[0].key, "test:key1");
// Verify negative cache was cleared
assert!(!negative_cache.contains("test:key1"));
}
#[tokio::test]
async fn test_loader_error_propagates() {
let mut reader = MockRedisClient::new();
reader.get_ret("test:key1", Err(CustomRedisError::NotFound));
let cache = setup_cache(reader, MockRedisClient::new(), None);
let result = cache
.get_or_load(&"key1", |_key| async {
Err::<Option<TestData>, String>("loader error".to_string())
})
.await;
assert!(result.is_err());
assert_eq!(result.unwrap_err(), "loader error");
}
}