feat: add corex-storage crate for unified storage abstraction
- Introduced corex-storage crate with support for local disk, S3-compatible, and Google Cloud Storage backends. - Implemented StorageDriver trait for various storage backends. - Added LocalFileStorage for local disk operations. - Added S3Storage for S3-compatible object storage with multipart upload support. - Added GcsStorage for Google Cloud Storage operations. - Included error handling for storage operations. - Added tests for each storage backend to ensure functionality. - Created README.md for documentation and usage examples. - Added Apache and MIT licenses for open-source compliance.
This commit is contained in:
asepharyana
@@ -0,0 +1,123 @@
|
||||
//! Cache-aside with read-through (feature `cache-aside`).
|
||||
//!
|
||||
//! [`CacheAside`] wires a [`Cache`] to a data source: on a miss it invokes a
|
||||
//! user-provided async fetcher, stores the result (with an optional TTL), and
|
||||
//! returns it. This is the standard cache-aside pattern — reads bypass a cold
|
||||
//! cache by falling back to the source of truth.
|
||||
|
||||
use std::time::Duration;
|
||||
|
||||
use crate::traits::{Cache, CacheError};
|
||||
|
||||
/// A generic read-through cache-aside helper.
|
||||
///
|
||||
/// `F` is the data source: an async closure `(owned key) -> Option<Vec<u8>>`.
|
||||
/// The key is passed by value ([`String`]) so the returned future does not
|
||||
/// borrow from the caller, which keeps the API simple and `'static`-friendly.
|
||||
#[derive(Clone)]
|
||||
pub struct CacheAside<C, F> {
|
||||
cache: C,
|
||||
fetcher: F,
|
||||
ttl: Option<Duration>,
|
||||
}
|
||||
|
||||
impl<C, F, Fut> CacheAside<C, F>
|
||||
where
|
||||
C: Cache,
|
||||
F: Fn(String) -> Fut + Send + Sync,
|
||||
Fut: std::future::Future<Output = Option<Vec<u8>>> + Send,
|
||||
{
|
||||
/// Builds a cache-aside wrapper around `cache` using `fetcher` to fill
|
||||
/// misses. Entries are stored without expiry unless `with_ttl` is used.
|
||||
pub fn new(cache: C, fetcher: F) -> Self {
|
||||
Self {
|
||||
cache,
|
||||
fetcher,
|
||||
ttl: None,
|
||||
}
|
||||
}
|
||||
|
||||
/// Applies a `ttl` to every entry written by this wrapper.
|
||||
pub fn with_ttl(mut self, ttl: Duration) -> Self {
|
||||
self.ttl = Some(ttl);
|
||||
self
|
||||
}
|
||||
|
||||
/// Returns a value for `key`, reading through to the fetcher on a miss and
|
||||
/// caching the result.
|
||||
pub async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, CacheError> {
|
||||
if let Some(value) = self.cache.get(key).await? {
|
||||
return Ok(Some(value));
|
||||
}
|
||||
if let Some(value) = (self.fetcher)(key.to_string()).await {
|
||||
self.cache.set(key, value.clone(), self.ttl).await?;
|
||||
Ok(Some(value))
|
||||
} else {
|
||||
Ok(None)
|
||||
}
|
||||
}
|
||||
|
||||
/// Explicitly evicts `key`.
|
||||
pub async fn invalidate(&self, key: &str) -> Result<(), CacheError> {
|
||||
self.cache.invalidate(key).await
|
||||
}
|
||||
|
||||
/// Returns a reference to the underlying cache.
|
||||
pub fn cache(&self) -> &C {
|
||||
&self.cache
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::memory::MemoryCache;
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
use std::sync::Arc;
|
||||
|
||||
fn fetcher(
|
||||
hits: Arc<AtomicU64>,
|
||||
) -> impl Fn(String) -> std::future::Ready<Option<Vec<u8>>> + Send + Sync {
|
||||
move |_key: String| {
|
||||
let n = hits.fetch_add(1, Ordering::SeqCst) + 1;
|
||||
std::future::ready(Some(format!("fetched-{n}").into_bytes()))
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn miss_reads_through_and_caches() {
|
||||
let hits = Arc::new(AtomicU64::new(0));
|
||||
let aside = CacheAside::new(MemoryCache::new(), fetcher(hits.clone()));
|
||||
|
||||
let first = aside.get("k").await.unwrap().unwrap();
|
||||
let second = aside.get("k").await.unwrap().unwrap();
|
||||
assert_eq!(first, b"fetched-1");
|
||||
// Cache hit — fetcher not called again.
|
||||
assert_eq!(second, b"fetched-1");
|
||||
assert_eq!(hits.load(Ordering::SeqCst), 1);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn invalidate_forces_refetch() {
|
||||
let hits = Arc::new(AtomicU64::new(0));
|
||||
let aside = CacheAside::new(MemoryCache::new(), fetcher(hits.clone()));
|
||||
let _ = aside.get("k").await.unwrap();
|
||||
aside.invalidate("k").await.unwrap();
|
||||
let again = aside.get("k").await.unwrap().unwrap();
|
||||
assert_eq!(again, b"fetched-2");
|
||||
assert_eq!(hits.load(Ordering::SeqCst), 2);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn ttl_applies_to_writes() {
|
||||
let aside = CacheAside::new(MemoryCache::new(), fetcher(Arc::new(AtomicU64::new(0))))
|
||||
.with_ttl(Duration::from_millis(30));
|
||||
let _ = aside.get("k").await.unwrap();
|
||||
assert_eq!(
|
||||
aside.cache().get("k").await.unwrap(),
|
||||
Some(b"fetched-1".to_vec())
|
||||
);
|
||||
tokio::time::sleep(Duration::from_millis(60)).await;
|
||||
assert_eq!(aside.cache().get("k").await.unwrap(), None);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
//! # corex-cache
|
||||
//!
|
||||
//! A unified multi-layer cache abstraction that keeps your application from
|
||||
//! being locked to any single cache provider.
|
||||
//!
|
||||
//! - **L1 (in-process) caches**: [`memory::MemoryCache`] (zero-dependency,
|
||||
//! default) or [`moka_cache::MokaL1`] (high-performance, TTL/max-capacity).
|
||||
//! - **L2 (distributed) caches**: [`redis::RedisCache`] backed by Redis/Valkey.
|
||||
//! - **Multi-layer composition**: [`multilayer::MultiLayerCache`] layers an L1
|
||||
//! over an L2 behind one [`Cache`] face; reads fall through to L2 and
|
||||
//! backfill L1.
|
||||
//! - **Cache-aside / auto-refresh**: [`cache_aside::CacheAside`] reads through
|
||||
//! to a data source on a miss and caches the result.
|
||||
//!
|
||||
//! The core [`Cache`] trait is byte-oriented; typed convenience (JSON) is
|
||||
//! layered on top via [`memory::typed::TypedCache`].
|
||||
//!
|
||||
//! ## Example
|
||||
//!
|
||||
//! ```no_run
|
||||
//! use corex_cache::{Cache, MemoryCache, MultiLayerCache, CacheAside};
|
||||
//! # async fn run() {
|
||||
//! let l1 = MemoryCache::new();
|
||||
//! let l2 = MemoryCache::new(); // in a real app: a RedisCache
|
||||
//! let cache = MultiLayerCache::new(l1, l2);
|
||||
//!
|
||||
//! cache.set("user:1", b"payload".to_vec(), None).await.unwrap();
|
||||
//! assert_eq!(cache.get("user:1").await.unwrap(), Some(b"payload".to_vec()));
|
||||
//!
|
||||
//! // Cache-aside: fill misses from a source of truth.
|
||||
//! let aside = CacheAside::new(
|
||||
//! MemoryCache::new(),
|
||||
//! |key| async move { Some(format!("data-for-{key}").into_bytes()) },
|
||||
//! );
|
||||
//! let _v = aside.get("orders:42").await.unwrap();
|
||||
//! # }
|
||||
//! ```
|
||||
|
||||
#![forbid(unsafe_code)]
|
||||
|
||||
pub mod traits;
|
||||
|
||||
#[cfg(feature = "l1-memory")]
|
||||
pub mod memory;
|
||||
|
||||
#[cfg(feature = "l1-moka")]
|
||||
pub mod moka_cache;
|
||||
|
||||
#[cfg(feature = "l2-redis")]
|
||||
pub mod redis;
|
||||
|
||||
#[cfg(feature = "cache-aside")]
|
||||
pub mod cache_aside;
|
||||
|
||||
#[cfg(feature = "cache-aside")]
|
||||
pub mod multilayer;
|
||||
|
||||
pub use traits::{Cache, CacheError};
|
||||
|
||||
#[cfg(feature = "l1-memory")]
|
||||
pub use memory::MemoryCache;
|
||||
|
||||
#[cfg(feature = "l1-moka")]
|
||||
pub use moka_cache::MokaL1;
|
||||
|
||||
#[cfg(feature = "l2-redis")]
|
||||
pub use redis::RedisCache;
|
||||
|
||||
#[cfg(feature = "cache-aside")]
|
||||
pub use cache_aside::CacheAside;
|
||||
|
||||
#[cfg(feature = "cache-aside")]
|
||||
pub use multilayer::MultiLayerCache;
|
||||
@@ -0,0 +1,191 @@
|
||||
//! A simple, dependency-free in-process cache (L1, `l1-memory`).
|
||||
//!
|
||||
//! Backed by a `HashMap<String, (Vec<u8>, Instant)>` guarded by a `Mutex`.
|
||||
//! Entries are lazily expired on access by comparing against `Instant`; a
|
||||
//! monotonic clock keeps TTLs robust against wall-clock discontinuities.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::sync::{Arc, Mutex};
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use async_trait::async_trait;
|
||||
|
||||
use crate::traits::{Cache, CacheError};
|
||||
|
||||
/// A wrapping entry: `None` expiry means the value never expires.
|
||||
type Entry = (Vec<u8>, Option<Instant>);
|
||||
|
||||
/// An in-process [`Cache`] implementation for L1 caching.
|
||||
#[derive(Clone, Default)]
|
||||
pub struct MemoryCache {
|
||||
inner: Arc<Mutex<HashMap<String, Entry>>>,
|
||||
}
|
||||
|
||||
impl MemoryCache {
|
||||
/// Builds an empty in-memory cache.
|
||||
pub fn new() -> Self {
|
||||
Self::default()
|
||||
}
|
||||
|
||||
/// Pre-allocates space for `capacity` entries to reduce reallocation.
|
||||
pub fn with_capacity(self, capacity: usize) -> Self {
|
||||
self.inner.lock().unwrap().reserve(capacity);
|
||||
self
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Cache for MemoryCache {
|
||||
async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, CacheError> {
|
||||
let mut map = self.inner.lock().unwrap();
|
||||
match map.get(key) {
|
||||
Some((value, Some(expires))) if *expires <= Instant::now() => {
|
||||
map.remove(key);
|
||||
Ok(None)
|
||||
}
|
||||
Some((value, _)) => Ok(Some(value.clone())),
|
||||
None => Ok(None),
|
||||
}
|
||||
}
|
||||
|
||||
async fn set(
|
||||
&self,
|
||||
key: &str,
|
||||
value: Vec<u8>,
|
||||
ttl: Option<Duration>,
|
||||
) -> Result<(), CacheError> {
|
||||
let expires = ttl.map(|d| Instant::now() + d);
|
||||
self.inner
|
||||
.lock()
|
||||
.unwrap()
|
||||
.insert(key.to_string(), (value, expires));
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn invalidate(&self, key: &str) -> Result<(), CacheError> {
|
||||
self.inner.lock().unwrap().remove(key);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn clear(&self) -> Result<(), CacheError> {
|
||||
self.inner.lock().unwrap().clear();
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
/// A typed view over a byte cache using `serde`-compatible (JSON) encoding.
|
||||
///
|
||||
/// Only enabled with the `cache-aside` feature, which pulls in `serde`.
|
||||
#[cfg(feature = "cache-aside")]
|
||||
pub mod typed {
|
||||
use serde::{de::DeserializeOwned, Serialize};
|
||||
|
||||
use super::*;
|
||||
|
||||
/// Wraps a [`Cache`] with JSON-based typed get/set.
|
||||
#[derive(Clone)]
|
||||
pub struct TypedCache<C> {
|
||||
inner: C,
|
||||
}
|
||||
|
||||
impl<C: Cache> TypedCache<C> {
|
||||
/// Wraps `inner`.
|
||||
pub fn new(inner: C) -> Self {
|
||||
Self { inner }
|
||||
}
|
||||
|
||||
/// Fetches and deserializes a value.
|
||||
pub async fn get<T: DeserializeOwned>(&self, key: &str) -> Result<Option<T>, CacheError> {
|
||||
match self.inner.get(key).await? {
|
||||
Some(bytes) => serde_json::from_slice(&bytes)
|
||||
.map(Some)
|
||||
.map_err(|e| CacheError::Serialization(e.to_string())),
|
||||
None => Ok(None),
|
||||
}
|
||||
}
|
||||
|
||||
/// Serializes and stores a value.
|
||||
pub async fn set<T: Serialize>(
|
||||
&self,
|
||||
key: &str,
|
||||
value: &T,
|
||||
ttl: Option<Duration>,
|
||||
) -> Result<(), CacheError> {
|
||||
let bytes =
|
||||
serde_json::to_vec(value).map_err(|e| CacheError::Serialization(e.to_string()))?;
|
||||
self.inner.set(key, bytes, ttl).await
|
||||
}
|
||||
|
||||
/// Returns the underlying byte cache.
|
||||
pub fn into_inner(self) -> C {
|
||||
self.inner
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn set_get_roundtrip() {
|
||||
let c = MemoryCache::new();
|
||||
c.set("k", b"v".to_vec(), None).await.unwrap();
|
||||
assert_eq!(c.get("k").await.unwrap(), Some(b"v".to_vec()));
|
||||
assert_eq!(c.get("missing").await.unwrap(), None);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn ttl_expires_entry() {
|
||||
let c = MemoryCache::new();
|
||||
c.set("k", b"v".to_vec(), Some(Duration::from_millis(30)))
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(c.get("k").await.unwrap(), Some(b"v".to_vec()));
|
||||
tokio::time::sleep(Duration::from_millis(60)).await;
|
||||
assert_eq!(c.get("k").await.unwrap(), None);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn invalidate_and_clear() {
|
||||
let c = MemoryCache::new();
|
||||
c.set("a", b"1".to_vec(), None).await.unwrap();
|
||||
c.set("b", b"2".to_vec(), None).await.unwrap();
|
||||
c.invalidate("a").await.unwrap();
|
||||
assert_eq!(c.get("a").await.unwrap(), None);
|
||||
assert_eq!(c.get("b").await.unwrap(), Some(b"2".to_vec()));
|
||||
c.clear().await.unwrap();
|
||||
assert_eq!(c.get("b").await.unwrap(), None);
|
||||
}
|
||||
|
||||
#[cfg(feature = "cache-aside")]
|
||||
#[tokio::test]
|
||||
async fn typed_cache_roundtrip() {
|
||||
use typed::TypedCache;
|
||||
#[derive(serde::Serialize, serde::Deserialize, Debug, PartialEq)]
|
||||
struct User {
|
||||
id: u64,
|
||||
name: String,
|
||||
}
|
||||
let typed = TypedCache::new(MemoryCache::new());
|
||||
typed
|
||||
.set(
|
||||
"u",
|
||||
&User {
|
||||
id: 1,
|
||||
name: "alice".into(),
|
||||
},
|
||||
None,
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
let got: User = typed.get("u").await.unwrap().unwrap();
|
||||
assert_eq!(
|
||||
got,
|
||||
User {
|
||||
id: 1,
|
||||
name: "alice".into()
|
||||
}
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
//! A high-performance in-process cache backed by Moka (L1, `l1-moka`).
|
||||
//!
|
||||
//! Moka provides automatic max-capacity and (optionally) TTL-based eviction,
|
||||
//! so this L1 is well-suited to workloads where memory bounds matter.
|
||||
|
||||
use std::time::Duration;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use moka::future::Cache as MokaCache;
|
||||
|
||||
use crate::traits::{Cache, CacheError};
|
||||
|
||||
/// A Moka-backed [`Cache`] for L1 caching.
|
||||
#[derive(Clone)]
|
||||
pub struct MokaL1 {
|
||||
inner: MokaCache<String, Vec<u8>>,
|
||||
}
|
||||
|
||||
impl MokaL1 {
|
||||
/// Builds a Moka cache with `max_capacity` entries and an optional default
|
||||
/// `ttl`.
|
||||
pub fn new(max_capacity: u64, ttl: Option<Duration>) -> Self {
|
||||
let mut builder = MokaCache::builder().max_capacity(max_capacity);
|
||||
if let Some(ttl) = ttl {
|
||||
builder = builder.time_to_live(ttl);
|
||||
}
|
||||
Self {
|
||||
inner: builder.build(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Cache for MokaL1 {
|
||||
async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, CacheError> {
|
||||
Ok(self.inner.get(key).await)
|
||||
}
|
||||
|
||||
async fn set(
|
||||
&self,
|
||||
key: &str,
|
||||
value: Vec<u8>,
|
||||
_ttl: Option<Duration>,
|
||||
) -> Result<(), CacheError> {
|
||||
// Per-entry TTL overrides are handled by the builder default in Moka;
|
||||
// the passed `ttl` is intentionally ignored (single configured policy).
|
||||
self.inner.insert(key.to_string(), value).await;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn invalidate(&self, key: &str) -> Result<(), CacheError> {
|
||||
self.inner.invalidate(key).await;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn clear(&self) -> Result<(), CacheError> {
|
||||
self.inner.invalidate_all();
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn set_get_roundtrip() {
|
||||
let c = MokaL1::new(100, None);
|
||||
c.set("k", b"v".to_vec(), None).await.unwrap();
|
||||
assert_eq!(c.get("k").await.unwrap(), Some(b"v".to_vec()));
|
||||
assert_eq!(c.get("missing").await.unwrap(), None);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn invalidate_and_clear() {
|
||||
let c = MokaL1::new(100, None);
|
||||
c.set("a", b"1".to_vec(), None).await.unwrap();
|
||||
c.set("b", b"2".to_vec(), None).await.unwrap();
|
||||
c.invalidate("a").await.unwrap();
|
||||
assert_eq!(c.get("a").await.unwrap(), None);
|
||||
assert_eq!(c.get("b").await.unwrap(), Some(b"2".to_vec()));
|
||||
c.clear().await.unwrap();
|
||||
assert_eq!(c.get("b").await.unwrap(), None);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn ttl_does_expire() {
|
||||
// Keep a firm TTL assertion; sleep well past the expiry window.
|
||||
let c = MokaL1::new(100, Some(Duration::from_millis(40)));
|
||||
c.set("k", b"v".to_vec(), None).await.unwrap();
|
||||
assert_eq!(c.get("k").await.unwrap(), Some(b"v".to_vec()));
|
||||
tokio::time::sleep(Duration::from_millis(120)).await;
|
||||
let v = c.get("k").await.unwrap();
|
||||
assert!(matches!(v, None));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,139 @@
|
||||
//! Multi-layer (L1/L2) caching behind a single [`Cache`] face.
|
||||
//!
|
||||
//! [`MultiLayerCache`] layers a fast in-process L1 over a slower but larger
|
||||
//! L2 (e.g. Redis). Reads are L1-first with an L2 fallback; a hit on L2 is
|
||||
//! backfilled into L1. Writes and invalidations go to both layers.
|
||||
|
||||
use std::time::Duration;
|
||||
|
||||
use async_trait::async_trait;
|
||||
|
||||
use crate::traits::{Cache, CacheError};
|
||||
|
||||
/// A read-through, write-through composition of an L1 and L2 cache.
|
||||
///
|
||||
/// `L1` is typically [`crate::memory::MemoryCache`] or
|
||||
/// [`crate::moka_cache::MokaL1`]; `L2` is typically a distributed cache such
|
||||
/// as a Redis backend. Order of layers fixed: `L1` is consulted first.
|
||||
#[derive(Clone)]
|
||||
pub struct MultiLayerCache<L1, L2> {
|
||||
l1: L1,
|
||||
l2: L2,
|
||||
/// When `true`, an L2 hit is written back into L1 (default `true`).
|
||||
populate_l1: bool,
|
||||
}
|
||||
|
||||
impl<L1, L2> MultiLayerCache<L1, L2>
|
||||
where
|
||||
L1: Cache,
|
||||
L2: Cache,
|
||||
{
|
||||
/// Builds a two-layer cache with L1-backfill enabled.
|
||||
pub fn new(l1: L1, l2: L2) -> Self {
|
||||
Self {
|
||||
l1,
|
||||
l2,
|
||||
populate_l1: true,
|
||||
}
|
||||
}
|
||||
|
||||
/// Disables L1 backfill-on-read.
|
||||
pub fn without_l1_backfill(mut self) -> Self {
|
||||
self.populate_l1 = false;
|
||||
self
|
||||
}
|
||||
|
||||
/// Returns a reference to the L1 layer.
|
||||
pub fn l1(&self) -> &L1 {
|
||||
&self.l1
|
||||
}
|
||||
|
||||
/// Returns a reference to the L2 layer.
|
||||
pub fn l2(&self) -> &L2 {
|
||||
&self.l2
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl<L1, L2> Cache for MultiLayerCache<L1, L2>
|
||||
where
|
||||
L1: Cache,
|
||||
L2: Cache,
|
||||
{
|
||||
async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, CacheError> {
|
||||
// L1 first.
|
||||
if let Some(value) = self.l1.get(key).await? {
|
||||
return Ok(Some(value));
|
||||
}
|
||||
// L2 fallback.
|
||||
if let Some(value) = self.l2.get(key).await? {
|
||||
if self.populate_l1 {
|
||||
self.l1.set(key, value.clone(), None).await?;
|
||||
}
|
||||
return Ok(Some(value));
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
|
||||
async fn set(
|
||||
&self,
|
||||
key: &str,
|
||||
value: Vec<u8>,
|
||||
ttl: Option<Duration>,
|
||||
) -> Result<(), CacheError> {
|
||||
self.l1.set(key, value.clone(), ttl).await?;
|
||||
self.l2.set(key, value, ttl).await
|
||||
}
|
||||
|
||||
async fn invalidate(&self, key: &str) -> Result<(), CacheError> {
|
||||
self.l1.invalidate(key).await?;
|
||||
self.l2.invalidate(key).await
|
||||
}
|
||||
|
||||
async fn clear(&self) -> Result<(), CacheError> {
|
||||
self.l1.clear().await?;
|
||||
self.l2.clear().await
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::memory::MemoryCache;
|
||||
|
||||
#[tokio::test]
|
||||
async fn read_through_populates_l1() {
|
||||
let l2 = MemoryCache::new();
|
||||
l2.set("k", b"l2-value".to_vec(), None).await.unwrap();
|
||||
|
||||
let layered = MultiLayerCache::new(MemoryCache::new(), l2);
|
||||
assert_eq!(layered.l1().get("k").await.unwrap(), None);
|
||||
assert_eq!(layered.get("k").await.unwrap(), Some(b"l2-value".to_vec()));
|
||||
// L2 hit should have populated L1.
|
||||
assert_eq!(
|
||||
layered.l1().get("k").await.unwrap(),
|
||||
Some(b"l2-value".to_vec())
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn write_goes_to_both() {
|
||||
let l1 = MemoryCache::new();
|
||||
let l2 = MemoryCache::new();
|
||||
let layered = MultiLayerCache::new(l1, l2.clone());
|
||||
layered.set("k", b"v".to_vec(), None).await.unwrap();
|
||||
assert_eq!(layered.l1().get("k").await.unwrap(), Some(b"v".to_vec()));
|
||||
assert_eq!(l2.get("k").await.unwrap(), Some(b"v".to_vec()));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn invalidate_clears_both() {
|
||||
let l1 = MemoryCache::new();
|
||||
let l2 = MemoryCache::new();
|
||||
let layered = MultiLayerCache::new(l1, l2);
|
||||
layered.set("k", b"v".to_vec(), None).await.unwrap();
|
||||
layered.invalidate("k").await.unwrap();
|
||||
assert_eq!(layered.l1().get("k").await.unwrap(), None);
|
||||
assert_eq!(layered.l2().get("k").await.unwrap(), None);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,124 @@
|
||||
//! A distributed (L2) cache backed by Redis / Valkey (feature `l2-redis`).
|
||||
//!
|
||||
//! Wraps a `redis` async connection (multiplexed). Values are stored as raw
|
||||
//! Redis strings with an optional TTL (`SETEX` when a TTL is given). The
|
||||
//! caller provides the connection; this type only issues cache commands.
|
||||
|
||||
use std::time::Duration;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use redis::aio::MultiplexedConnection;
|
||||
use redis::{AsyncCommands, RedisError};
|
||||
|
||||
use crate::traits::{Cache, CacheError};
|
||||
|
||||
/// Map a Redis error onto a [`CacheError`].
|
||||
fn map_err(e: RedisError) -> CacheError {
|
||||
CacheError::Io(e.to_string())
|
||||
}
|
||||
|
||||
/// An L2 cache backed by a `redis` [`MultiplexedConnection`].
|
||||
///
|
||||
/// The connection is supplied by the caller; it is cheaply cloned (the
|
||||
/// multiplexed connection is `Arc`-backed internally), so one pool can drive
|
||||
/// both cache operations and other Redis usage.
|
||||
#[derive(Clone)]
|
||||
pub struct RedisCache {
|
||||
conn: MultiplexedConnection,
|
||||
/// Optional namespace prefix prepended to every key.
|
||||
prefix: String,
|
||||
}
|
||||
|
||||
impl RedisCache {
|
||||
/// Wraps an existing connection.
|
||||
pub fn new(conn: MultiplexedConnection) -> Self {
|
||||
Self::with_prefix(conn, String::new())
|
||||
}
|
||||
|
||||
/// Wraps a connection and adds a namespace prefix to every key.
|
||||
pub fn with_prefix(conn: MultiplexedConnection, prefix: String) -> Self {
|
||||
Self { conn, prefix }
|
||||
}
|
||||
|
||||
fn key(&self, key: &str) -> String {
|
||||
if self.prefix.is_empty() {
|
||||
key.to_string()
|
||||
} else {
|
||||
format!("{}{}", self.prefix, key)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Cache for RedisCache {
|
||||
async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, CacheError> {
|
||||
// `get::<_, Option<Vec<u8>>>` returns `None` for a missing key.
|
||||
let mut c = self.conn.clone();
|
||||
let k = self.key(key);
|
||||
let result: Result<Option<Vec<u8>>, RedisError> = c.get(&k).await;
|
||||
result.map_err(map_err)
|
||||
}
|
||||
|
||||
async fn set(
|
||||
&self,
|
||||
key: &str,
|
||||
value: Vec<u8>,
|
||||
ttl: Option<Duration>,
|
||||
) -> Result<(), CacheError> {
|
||||
let mut c = self.conn.clone();
|
||||
let k = self.key(key);
|
||||
match ttl {
|
||||
Some(ttl) => {
|
||||
let secs = ttl.as_secs().max(1);
|
||||
let result: Result<(), RedisError> = c.set_ex(&k, value, secs).await;
|
||||
result.map_err(map_err)
|
||||
}
|
||||
None => {
|
||||
let result: Result<(), RedisError> = c.set(&k, value).await;
|
||||
result.map_err(map_err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async fn invalidate(&self, key: &str) -> Result<(), CacheError> {
|
||||
let mut c = self.conn.clone();
|
||||
let k = self.key(key);
|
||||
let result: Result<u64, RedisError> = c.del(&k).await;
|
||||
result.map(|_| ()).map_err(map_err)
|
||||
}
|
||||
|
||||
async fn clear(&self) -> Result<(), CacheError> {
|
||||
// Deliberately does nothing: `FLUSHALL`/`FLUSHDB` are dangerous on a
|
||||
// shared instance. Consumers should scope keys under a prefix and call
|
||||
// `invalidate` for the keys they own.
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// Integration test requiring a live Redis at `REDIS_URL`
|
||||
/// (e.g. `redis://127.0.0.1:6379`). Run with:
|
||||
/// `REDIS_URL=redis://127.0.0.1:6379 cargo test -p corex-cache --features l2-redis -- --ignored` .
|
||||
#[tokio::test]
|
||||
#[ignore = "requires a live Redis instance (REDIS_URL)"]
|
||||
async fn set_get_roundtrip_live() {
|
||||
let url = std::env::var("REDIS_URL").expect("set REDIS_URL");
|
||||
let client = redis::Client::open(url).expect("valid redis url");
|
||||
let conn = client
|
||||
.get_multiplexed_tokio_connection()
|
||||
.await
|
||||
.expect("connect");
|
||||
let cache = RedisCache::with_prefix(conn, "corex_cache_test:".to_string());
|
||||
|
||||
cache
|
||||
.set("k", b"v".to_vec(), Some(Duration::from_secs(3600)))
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(cache.get("k").await.unwrap(), Some(b"v".to_vec()));
|
||||
cache.invalidate("k").await.unwrap();
|
||||
assert_eq!(cache.get("k").await.unwrap(), None);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
//! The core [`Cache`] and [`KeyEncoder`] traits.
|
||||
|
||||
use std::borrow::Cow;
|
||||
use std::time::Duration;
|
||||
|
||||
use async_trait::async_trait;
|
||||
|
||||
/// Errors returned by cache operations.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum CacheError {
|
||||
/// The backend could not be reached (e.g. Redis connection lost).
|
||||
Io(String),
|
||||
/// A value could not be serialized / deserialized.
|
||||
Serialization(String),
|
||||
/// A key could not be encoded for the backend.
|
||||
Key(String),
|
||||
}
|
||||
|
||||
impl std::fmt::Display for CacheError {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
Self::Io(s) => write!(f, "cache io: {s}"),
|
||||
Self::Serialization(s) => write!(f, "cache serialization: {s}"),
|
||||
Self::Key(s) => write!(f, "cache key: {s}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl std::error::Error for CacheError {}
|
||||
|
||||
/// A generic byte-oriented cache.
|
||||
///
|
||||
/// Real caches operate on bytes or strings; typed convenience is layered on
|
||||
/// top (see [`crate::memory::typed::TypedCache`], behind `cache-aside`).
|
||||
/// Implementors control the value format.
|
||||
#[async_trait]
|
||||
pub trait Cache: Send + Sync {
|
||||
/// Fetches a value by key. `None` indicates a miss.
|
||||
async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, CacheError>;
|
||||
/// Stores a value under `key`, optionally expiring after `ttl`.
|
||||
async fn set(&self, key: &str, value: Vec<u8>, ttl: Option<Duration>)
|
||||
-> Result<(), CacheError>;
|
||||
/// Removes a key.
|
||||
async fn invalidate(&self, key: &str) -> Result<(), CacheError>;
|
||||
/// Removes all entries.
|
||||
async fn clear(&self) -> Result<(), CacheError>;
|
||||
}
|
||||
|
||||
/// Keys given to the byte-oriented [`Cache`] are `&str`, but concrete backends
|
||||
/// may need richer keys. [`KeyEncoder`] turns typed keys into canonical strings.
|
||||
pub trait KeyEncoder {
|
||||
/// The "shape" of a key, e.g. `"user:{id}:profile"`.
|
||||
fn encode<C: Into<Cow<'static, str>>, R: std::fmt::Display>(parts: (C, R)) -> String;
|
||||
}
|
||||
|
||||
/// A blanket implementation that formats `{collection}:{id}`.
|
||||
pub struct DefaultKeyEncoder;
|
||||
|
||||
impl KeyEncoder for DefaultKeyEncoder {
|
||||
fn encode<C: Into<Cow<'static, str>>, R: std::fmt::Display>(parts: (C, R)) -> String {
|
||||
format!("{}:{}", parts.0.into(), parts.1)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn default_key_encoder_formats() {
|
||||
assert_eq!(DefaultKeyEncoder::encode(("user", 42)), "user:42");
|
||||
assert_eq!(
|
||||
DefaultKeyEncoder::encode(("session", "abc-123")),
|
||||
"session:abc-123"
|
||||
);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user