pub mod plugin;
pub use plugin::CachePlugin;
use async_trait::async_trait;
use dashmap::{DashMap, Entry};
#[cfg(feature = "redis")]
use redis::aio::ConnectionManager;
use serde::{de::DeserializeOwned, Serialize};
use std::collections::HashSet;
use std::hash::{BuildHasher, Hasher};
use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Weak};
use std::time::{Duration, Instant};
pub use wordval_core::{Error, Result};
#[async_trait]
pub trait Cache: Send + Sync {
async fn get<T: DeserializeOwned + Send>(&self, key: &str) -> Result<Option<T>>;
async fn set<T: Serialize + Send + Sync>(&self, key: &str, value: &T) -> Result<()>;
async fn set_ex<T: Serialize + Send + Sync>(
&self,
key: &str,
value: &T,
ttl_secs: u64,
) -> Result<()>;
async fn del(&self, key: &str) -> Result<()>;
async fn exists(&self, key: &str) -> Result<bool>;
async fn incr(&self, key: &str, delta: i64) -> Result<i64>;
async fn keys(&self, pattern: &str) -> Result<Vec<String>>;
async fn set_nx<T: Serialize + Send + Sync>(
&self,
key: &str,
value: &T,
ttl_secs: u64,
) -> Result<bool>;
async fn delete_pattern(&self, pattern: &str) -> Result<u64>;
async fn sadd(&self, key: &str, members: &[String]) -> Result<u64>;
async fn srem(&self, key: &str, members: &[String]) -> Result<u64>;
async fn smembers(&self, key: &str) -> Result<Vec<String>>;
async fn sismember(&self, key: &str, member: &str) -> Result<bool> {
Ok(self.smembers(key).await?.iter().any(|m| m == member))
}
async fn expire(&self, key: &str, ttl_secs: u64) -> Result<bool>;
async fn ttl(&self, key: &str) -> Result<Option<u64>> {
let _ = key;
Ok(None)
}
async fn sadd_with_ttl(&self, key: &str, members: &[String], ttl_secs: u64) -> Result<()> {
check_ttl_secs(ttl_secs)?;
self.sadd(key, members).await?;
self.expire(key, ttl_secs).await?;
Ok(())
}
async fn get_raw(&self, key: &str) -> Result<Option<Vec<u8>>> {
match self.get::<serde_json::Value>(key).await? {
Some(v) => Ok(Some(
serde_json::to_vec(&v).map_err(|e| Error::Msg(e.to_string()))?,
)),
None => Ok(None),
}
}
async fn set_raw(&self, key: &str, value: &[u8]) -> Result<()> {
let v: serde_json::Value =
serde_json::from_slice(value).map_err(|e| Error::Msg(e.to_string()))?;
self.set(key, &v).await
}
async fn set_raw_ex(&self, key: &str, value: &[u8], ttl_secs: u64) -> Result<()> {
let v: serde_json::Value =
serde_json::from_slice(value).map_err(|e| Error::Msg(e.to_string()))?;
self.set_ex(key, &v, ttl_secs).await
}
fn stats(&self) -> CacheStats {
CacheStats::default()
}
}
pub async fn get_raw(cache: &SharedCache, key: &str) -> Result<Option<Vec<u8>>> {
Cache::get_raw(cache, key).await
}
pub async fn set_raw(cache: &SharedCache, key: &str, value: &[u8]) -> Result<()> {
Cache::set_raw(cache, key, value).await
}
fn validate_json(value: &[u8]) -> Result<()> {
serde_json::from_slice::<serde::de::IgnoredAny>(value)
.map(|_| ())
.map_err(|e| Error::Msg(e.to_string()))
}
fn wrong_type_err() -> Error {
Error::Msg("WRONGTYPE Operation against a key holding the wrong kind of value".into())
}
fn check_ttl_secs(ttl_secs: u64) -> Result<()> {
if ttl_secs == 0 {
Err(Error::Msg(
"ERR invalid expire time: ttl_secs must be greater than 0".into(),
))
} else if ttl_secs > i64::MAX as u64 {
Err(Error::Msg(
"ERR invalid expire time: ttl_secs is out of range".into(),
))
} else {
Ok(())
}
}
fn expiry_after(secs: u64) -> Result<Instant> {
Instant::now()
.checked_add(Duration::from_secs(secs))
.ok_or_else(|| Error::Msg("ERR invalid expire time: ttl overflow".into()))
}
#[cfg(feature = "redis")]
fn sanitize_redis_url(url: &str) -> String {
let Some(scheme_end) = url.find("://") else {
return url.to_string();
};
let rest_start = scheme_end + 3;
let rest = &url[rest_start..];
let authority_end = rest.find(['/', '?']).unwrap_or(rest.len());
let authority = &rest[..authority_end];
match authority.rfind('@') {
Some(at) => format!(
"{}***{}{}",
&url[..rest_start],
&authority[at..],
&rest[authority_end..]
),
None => url.to_string(),
}
}
struct CacheEntry {
bytes: Arc<[u8]>,
expires_at: Option<Instant>,
}
#[derive(Debug, Clone, Default)]
pub struct CacheStats {
pub hits: u64,
pub misses: u64,
pub sets: u64,
pub deletes: u64,
pub evictions: u64,
pub expired_cleanups: u64,
}
#[derive(Default)]
struct AtomicCacheStats {
hits: AtomicU64,
misses: AtomicU64,
sets: AtomicU64,
deletes: AtomicU64,
evictions: AtomicU64,
expired_cleanups: AtomicU64,
}
struct Inner {
data: DashMap<String, CacheEntry, ahash::RandomState>,
size: AtomicUsize,
max_capacity: u64,
stats: AtomicCacheStats,
cleanup_interval_secs: u64,
cleanup_started: AtomicBool,
inflight: InflightMap,
}
type InflightMap = DashMap<String, Arc<tokio::sync::Mutex<()>>, ahash::RandomState>;
struct InflightGuard<'a> {
map: &'a InflightMap,
key: &'a str,
lock: Arc<tokio::sync::Mutex<()>>,
}
impl Drop for InflightGuard<'_> {
fn drop(&mut self) {
self.map
.remove_if(self.key, |_, v| Arc::ptr_eq(v, &self.lock));
}
}
async fn single_flight<C, T, F, Fut>(
cache: &C,
inflight: &InflightMap,
key: &str,
ttl_secs: u64,
load: F,
) -> Result<T>
where
C: Cache,
T: DeserializeOwned + Serialize + Send + Sync,
F: FnOnce() -> Fut,
Fut: std::future::Future<Output = Result<T>>,
{
if let Some(v) = cache.get::<T>(key).await? {
return Ok(v);
}
let lock = match inflight.entry(key.to_string()) {
Entry::Vacant(e) => {
let lock = Arc::new(tokio::sync::Mutex::new(()));
e.insert(lock.clone());
lock
}
Entry::Occupied(e) => e.get().clone(),
};
let _inflight = InflightGuard {
map: inflight,
key,
lock: Arc::clone(&lock),
};
let guard = lock.lock().await;
if let Some(v) = cache.get::<T>(key).await? {
return Ok(v);
}
let value = load().await?;
if ttl_secs > 0 {
cache.set_ex(key, &value, ttl_secs).await?;
} else {
cache.set(key, &value).await?;
}
drop(guard); Ok(value)
}
#[inline]
fn inc_size(inner: &Inner) {
inner.size.fetch_add(1, Ordering::Relaxed);
}
#[inline]
fn dec_size(inner: &Inner, n: usize) {
let _ = inner
.size
.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |x| {
Some(x.saturating_sub(n))
});
}
fn remove_if_expired(inner: &Inner, key: &str, now: Instant) -> bool {
if inner
.data
.remove_if(key, |_, v| v.expires_at.is_some_and(|t| now > t))
.is_some()
{
dec_size(inner, 1);
true
} else {
false
}
}
const EVICT_SAMPLE: usize = 64;
fn evict_sampled(inner: &Inner, seed_key: &str) {
let total = inner.size.load(Ordering::Relaxed);
if total == 0 {
return;
}
let offset = {
let mut h = ahash::RandomState::new().build_hasher();
h.write(seed_key.as_bytes());
(h.finish() as usize) % total.min(EVICT_SAMPLE)
};
let mut best_key: Option<String> = None;
let mut best_exp: Option<Instant> = None;
let mut scanned = 0usize;
for entry in inner.data.iter().skip(offset) {
let exp = entry.expires_at;
let better = match (best_exp, exp) {
(None, _) => true,
(Some(_), None) => false,
(Some(b), Some(e)) => e < b,
};
if better {
best_key = Some(entry.key().clone());
best_exp = exp;
}
scanned += 1;
if scanned >= EVICT_SAMPLE {
break;
}
}
if let Some(k) = best_key {
if inner.data.remove(&k).is_some() {
dec_size(inner, 1);
inner.stats.evictions.fetch_add(1, Ordering::Relaxed);
}
}
}
#[inline]
fn ensure_capacity_for_insert(inner: &Inner, key: &str) {
if inner.max_capacity > 0
&& inner.size.load(Ordering::Relaxed) as u64 >= inner.max_capacity
&& !inner.data.contains_key(key)
{
evict_sampled(inner, key);
}
}
fn cleanup_expired_inner(inner: &Inner) -> u64 {
let now = Instant::now();
let mut removed = 0usize;
inner.data.retain(|_, v| {
let alive = v.expires_at.map_or(true, |t| now <= t);
if !alive {
removed += 1;
}
alive
});
if removed > 0 {
dec_size(inner, removed);
inner
.stats
.expired_cleanups
.fetch_add(removed as u64, Ordering::Relaxed);
}
removed as u64
}
#[derive(Clone)]
pub struct LocalCache {
inner: Arc<Inner>,
}
impl std::fmt::Debug for LocalCache {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("LocalCache")
.field("len", &self.len())
.field("max_capacity", &self.inner.max_capacity)
.finish()
}
}
impl LocalCache {
pub fn new(max_capacity: u64, default_ttl_secs: u64) -> Self {
let _ = default_ttl_secs; let prealloc = max_capacity.min(1024) as usize;
Self {
inner: Arc::new(Inner {
data: DashMap::with_capacity_and_hasher(prealloc, ahash::RandomState::new()),
size: AtomicUsize::new(0),
max_capacity,
stats: AtomicCacheStats::default(),
cleanup_interval_secs: 60,
cleanup_started: AtomicBool::new(false),
inflight: InflightMap::with_hasher(ahash::RandomState::new()),
}),
}
}
pub fn with_cleanup_interval(mut self, interval_secs: u64) -> Self {
match Arc::get_mut(&mut self.inner) {
Some(inner) => inner.cleanup_interval_secs = interval_secs,
None => tracing::warn!(
"with_cleanup_interval 在实例被克隆后调用,本次配置被忽略"
),
}
self
}
pub fn stats(&self) -> CacheStats {
let s = &self.inner.stats;
CacheStats {
hits: s.hits.load(Ordering::Relaxed),
misses: s.misses.load(Ordering::Relaxed),
sets: s.sets.load(Ordering::Relaxed),
deletes: s.deletes.load(Ordering::Relaxed),
evictions: s.evictions.load(Ordering::Relaxed),
expired_cleanups: s.expired_cleanups.load(Ordering::Relaxed),
}
}
pub fn len(&self) -> usize {
self.inner.size.load(Ordering::Relaxed)
}
pub fn is_empty(&self) -> bool {
self.len() == 0
}
pub fn cleanup_expired(&self) -> u64 {
cleanup_expired_inner(&self.inner)
}
pub fn start_background_cleanup(&self) {
if self.inner.cleanup_started.swap(true, Ordering::AcqRel) {
return;
}
let weak: Weak<Inner> = Arc::downgrade(&self.inner);
let interval = self.inner.cleanup_interval_secs.max(1);
tokio::spawn(async move {
loop {
tokio::time::sleep(Duration::from_secs(interval)).await;
let Some(inner) = weak.upgrade() else {
break; };
let removed = cleanup_expired_inner(&inner);
if removed > 0 {
tracing::debug!("缓存后台清理: 移除 {} 个过期条目", removed);
}
}
});
}
#[inline]
fn read_live_bytes(&self, key: &str) -> Option<Arc<[u8]>> {
let now = Instant::now();
let entry = self.inner.data.get(key)?;
if entry.expires_at.is_some_and(|t| now > t) {
drop(entry);
remove_if_expired(&self.inner, key, now);
return None;
}
Some(Arc::clone(&entry.bytes))
}
fn insert_bytes(&self, key: &str, bytes: Arc<[u8]>, expires_at: Option<Instant>) {
if let Some(mut e) = self.inner.data.get_mut(key) {
*e.value_mut() = CacheEntry { bytes, expires_at };
self.inner.stats.sets.fetch_add(1, Ordering::Relaxed);
return;
}
ensure_capacity_for_insert(&self.inner, key);
match self.inner.data.entry(key.to_string()) {
Entry::Vacant(e) => {
e.insert(CacheEntry { bytes, expires_at });
inc_size(&self.inner);
}
Entry::Occupied(mut e) => {
*e.get_mut() = CacheEntry { bytes, expires_at };
}
}
self.inner.stats.sets.fetch_add(1, Ordering::Relaxed);
}
pub async fn get_or_insert_with<T, F, Fut>(
&self,
key: &str,
ttl_secs: u64,
load: F,
) -> Result<T>
where
T: DeserializeOwned + Serialize + Send + Sync,
F: FnOnce() -> Fut,
Fut: std::future::Future<Output = Result<T>>,
{
single_flight(self, &self.inner.inflight, key, ttl_secs, load).await
}
}
#[async_trait]
impl Cache for LocalCache {
async fn get<T: DeserializeOwned + Send>(&self, key: &str) -> Result<Option<T>> {
let Some(bytes) = self.read_live_bytes(key) else {
self.inner.stats.misses.fetch_add(1, Ordering::Relaxed);
return Ok(None);
};
self.inner.stats.hits.fetch_add(1, Ordering::Relaxed);
let val: T =
serde_json::from_slice(&bytes).map_err(|e| Error::Msg(e.to_string()))?;
Ok(Some(val))
}
async fn set<T: Serialize + Send + Sync>(&self, key: &str, value: &T) -> Result<()> {
let bytes = serde_json::to_vec(value).map_err(|e| Error::Msg(e.to_string()))?;
self.insert_bytes(key, Arc::from(bytes), None);
Ok(())
}
async fn set_ex<T: Serialize + Send + Sync>(
&self,
key: &str,
value: &T,
ttl_secs: u64,
) -> Result<()> {
check_ttl_secs(ttl_secs)?;
let bytes = serde_json::to_vec(value).map_err(|e| Error::Msg(e.to_string()))?;
let expires_at = Some(expiry_after(ttl_secs)?);
self.insert_bytes(key, Arc::from(bytes), expires_at);
Ok(())
}
async fn set_nx<T: Serialize + Send + Sync>(
&self,
key: &str,
value: &T,
ttl_secs: u64,
) -> Result<bool> {
check_ttl_secs(ttl_secs)?;
let bytes = serde_json::to_vec(value).map_err(|e| Error::Msg(e.to_string()))?;
let now = Instant::now();
let entry = CacheEntry {
bytes: Arc::from(bytes),
expires_at: Some(expiry_after(ttl_secs)?),
};
ensure_capacity_for_insert(&self.inner, key);
loop {
if let Some(mut e) = self.inner.data.get_mut(key) {
if e.value().expires_at.map_or(true, |exp| now <= exp) {
return Ok(false);
}
*e.value_mut() = entry;
return Ok(true);
}
match self.inner.data.entry(key.to_string()) {
Entry::Vacant(e) => {
e.insert(entry);
inc_size(&self.inner);
return Ok(true);
}
Entry::Occupied(_) => continue,
}
}
}
async fn del(&self, key: &str) -> Result<()> {
if self.inner.data.remove(key).is_some() {
dec_size(&self.inner, 1);
self.inner.stats.deletes.fetch_add(1, Ordering::Relaxed);
}
Ok(())
}
async fn exists(&self, key: &str) -> Result<bool> {
let now = Instant::now();
let found = match self.inner.data.get(key) {
Some(entry) => {
if entry.expires_at.is_some_and(|exp| now > exp) {
drop(entry);
remove_if_expired(&self.inner, key, now);
false
} else {
true
}
}
None => false,
};
if found {
self.inner.stats.hits.fetch_add(1, Ordering::Relaxed);
} else {
self.inner.stats.misses.fetch_add(1, Ordering::Relaxed);
}
Ok(found)
}
async fn incr(&self, key: &str, delta: i64) -> Result<i64> {
let now = Instant::now();
ensure_capacity_for_insert(&self.inner, key);
loop {
if let Some(mut e) = self.inner.data.get_mut(key) {
let expired = e.value().expires_at.is_some_and(|t| now > t);
let current: i64 = if expired {
0
} else {
std::str::from_utf8(&e.value().bytes)
.ok()
.and_then(|s| s.parse::<i64>().ok())
.ok_or_else(|| {
Error::Msg("value is not an integer or out of range".into())
})?
};
let nv = current
.checked_add(delta)
.ok_or_else(|| Error::Msg("increment or decrement would overflow".into()))?;
let ent = e.value_mut();
ent.bytes = Arc::from(nv.to_string().into_bytes());
if expired {
ent.expires_at = None;
}
return Ok(nv);
}
match self.inner.data.entry(key.to_string()) {
Entry::Vacant(e) => {
e.insert(CacheEntry {
bytes: Arc::from(delta.to_string().into_bytes()),
expires_at: None,
});
inc_size(&self.inner);
return Ok(delta);
}
Entry::Occupied(_) => continue,
}
}
}
async fn keys(&self, pattern: &str) -> Result<Vec<String>> {
let now = Instant::now();
Ok(self
.inner
.data
.iter()
.filter(|e| e.expires_at.map_or(true, |t| now <= t))
.filter(|e| match_pattern(e.key(), pattern))
.map(|e| e.key().clone())
.collect())
}
async fn delete_pattern(&self, pattern: &str) -> Result<u64> {
let mut removed = 0usize;
self.inner.data.retain(|k, _| {
if match_pattern(k, pattern) {
removed += 1;
false
} else {
true
}
});
if removed > 0 {
dec_size(&self.inner, removed);
self.inner
.stats
.deletes
.fetch_add(removed as u64, Ordering::Relaxed);
}
Ok(removed as u64)
}
async fn sadd(&self, key: &str, members: &[String]) -> Result<u64> {
if members.is_empty() {
return Ok(0);
}
let now = Instant::now();
ensure_capacity_for_insert(&self.inner, key);
let mut added = 0u64;
loop {
if let Some(mut e) = self.inner.data.get_mut(key) {
let expired = e.value().expires_at.is_some_and(|t| now > t);
let mut arr: Vec<String> = if expired {
Vec::new()
} else {
serde_json::from_slice(&e.value().bytes).map_err(|_| wrong_type_err())?
};
let mut seen: HashSet<&str> = arr.iter().map(String::as_str).collect();
let mut new_members: Vec<String> = Vec::new();
for m in members {
if seen.insert(m.as_str()) {
new_members.push(m.clone());
added += 1;
}
}
drop(seen);
arr.extend(new_members);
let ent = e.value_mut();
ent.bytes = Arc::from(
serde_json::to_vec(&arr).map_err(|err| Error::Msg(err.to_string()))?,
);
if expired {
ent.expires_at = None; }
return Ok(added);
}
match self.inner.data.entry(key.to_string()) {
Entry::Vacant(e) => {
let mut seen: HashSet<&str> = HashSet::with_capacity(members.len());
let mut arr: Vec<String> = Vec::with_capacity(members.len());
for m in members {
if seen.insert(m.as_str()) {
arr.push(m.clone());
added += 1;
}
}
e.insert(CacheEntry {
bytes: Arc::from(
serde_json::to_vec(&arr).map_err(|err| Error::Msg(err.to_string()))?,
),
expires_at: None,
});
inc_size(&self.inner);
return Ok(added);
}
Entry::Occupied(_) => continue,
}
}
}
async fn srem(&self, key: &str, members: &[String]) -> Result<u64> {
if members.is_empty() {
return Ok(0);
}
let now = Instant::now();
let removed = match self.inner.data.entry(key.to_string()) {
Entry::Occupied(mut e) => {
if e.get().expires_at.is_some_and(|t| now > t) {
e.remove();
dec_size(&self.inner, 1);
return Ok(0);
}
let mut arr: Vec<String> =
serde_json::from_slice(&e.get().bytes).map_err(|_| wrong_type_err())?;
let before = arr.len();
let targets: HashSet<&str> = members.iter().map(String::as_str).collect();
arr.retain(|v| !targets.contains(v.as_str()));
let removed = (before - arr.len()) as u64;
if removed > 0 {
if arr.is_empty() {
e.remove();
dec_size(&self.inner, 1);
} else {
e.get_mut().bytes = Arc::from(
serde_json::to_vec(&arr).map_err(|err| Error::Msg(err.to_string()))?,
);
}
}
removed
}
Entry::Vacant(_) => 0,
};
Ok(removed)
}
async fn smembers(&self, key: &str) -> Result<Vec<String>> {
match self.read_live_bytes(key) {
Some(bytes) => {
self.inner.stats.hits.fetch_add(1, Ordering::Relaxed);
serde_json::from_slice(&bytes).map_err(|_| wrong_type_err())
}
None => {
self.inner.stats.misses.fetch_add(1, Ordering::Relaxed);
Ok(vec![])
}
}
}
async fn expire(&self, key: &str, ttl_secs: u64) -> Result<bool> {
check_ttl_secs(ttl_secs)?;
let now = Instant::now();
match self.inner.data.get_mut(key) {
Some(mut entry) => {
if entry.expires_at.is_some_and(|t| now > t) {
drop(entry);
remove_if_expired(&self.inner, key, now);
Ok(false)
} else {
entry.expires_at = Some(expiry_after(ttl_secs)?);
Ok(true)
}
}
None => Ok(false),
}
}
async fn ttl(&self, key: &str) -> Result<Option<u64>> {
let now = Instant::now();
match self.inner.data.get(key) {
Some(entry) => {
if entry.expires_at.is_some_and(|t| now > t) {
drop(entry);
remove_if_expired(&self.inner, key, now);
Ok(None)
} else {
Ok(entry.expires_at.map(|t| {
let rem = t.saturating_duration_since(now);
rem.as_secs() + u64::from(rem.subsec_nanos() > 0)
}))
}
}
None => Ok(None),
}
}
async fn get_raw(&self, key: &str) -> Result<Option<Vec<u8>>> {
match self.read_live_bytes(key) {
Some(bytes) => {
self.inner.stats.hits.fetch_add(1, Ordering::Relaxed);
Ok(Some(bytes.to_vec()))
}
None => {
self.inner.stats.misses.fetch_add(1, Ordering::Relaxed);
Ok(None)
}
}
}
async fn set_raw(&self, key: &str, value: &[u8]) -> Result<()> {
validate_json(value)?;
self.insert_bytes(key, Arc::from(value), None);
Ok(())
}
async fn set_raw_ex(&self, key: &str, value: &[u8], ttl_secs: u64) -> Result<()> {
check_ttl_secs(ttl_secs)?;
validate_json(value)?;
let expires_at = Some(expiry_after(ttl_secs)?);
self.insert_bytes(key, Arc::from(value), expires_at);
Ok(())
}
}
#[cfg(feature = "redis")]
#[derive(Clone)]
pub struct RedisCache {
conn: ConnectionManager,
inflight: Arc<InflightMap>,
}
impl std::fmt::Debug for RedisCache {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("RedisCache").finish_non_exhaustive()
}
}
#[cfg(feature = "redis")]
impl RedisCache {
pub fn new(conn: ConnectionManager) -> Self {
Self {
conn,
inflight: Arc::new(InflightMap::with_hasher(ahash::RandomState::new())),
}
}
pub async fn connect(url: &str) -> Result<Self> {
let client = redis::Client::open(url)
.map_err(|e| Error::Config(format!("Redis URL 无效: {}", e)))?;
let conn = ConnectionManager::new(client)
.await
.map_err(|e| Error::Config(format!("Redis 连接失败: {}", e)))?;
Ok(Self {
conn,
inflight: Arc::new(InflightMap::with_hasher(ahash::RandomState::new())),
})
}
pub async fn get_or_insert_with<T, F, Fut>(
&self,
key: &str,
ttl_secs: u64,
load: F,
) -> Result<T>
where
T: DeserializeOwned + Serialize + Send + Sync,
F: FnOnce() -> Fut,
Fut: std::future::Future<Output = Result<T>>,
{
single_flight(self, &self.inflight, key, ttl_secs, load).await
}
fn map_err(e: redis::RedisError) -> Error {
Error::Msg(e.to_string())
}
}
#[cfg(feature = "redis")]
const SCAN_COUNT: u32 = 1000;
#[cfg(feature = "redis")]
#[async_trait]
impl Cache for RedisCache {
async fn get<T: DeserializeOwned + Send>(&self, key: &str) -> Result<Option<T>> {
let result: Option<Vec<u8>> = redis::cmd("GET")
.arg(key)
.query_async(&mut self.conn.clone())
.await
.map_err(Self::map_err)?;
match result {
Some(bytes) => {
let val: T =
serde_json::from_slice(&bytes).map_err(|e| Error::Msg(e.to_string()))?;
Ok(Some(val))
}
None => Ok(None),
}
}
async fn set<T: Serialize + Send + Sync>(&self, key: &str, value: &T) -> Result<()> {
let json = serde_json::to_string(value).map_err(|e| Error::Msg(e.to_string()))?;
redis::cmd("SET")
.arg(key)
.arg(&json)
.query_async::<()>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn set_ex<T: Serialize + Send + Sync>(
&self,
key: &str,
value: &T,
ttl_secs: u64,
) -> Result<()> {
check_ttl_secs(ttl_secs)?;
let json = serde_json::to_string(value).map_err(|e| Error::Msg(e.to_string()))?;
redis::cmd("SETEX")
.arg(key)
.arg(ttl_secs)
.arg(&json)
.query_async::<()>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn set_nx<T: Serialize + Send + Sync>(
&self,
key: &str,
value: &T,
ttl_secs: u64,
) -> Result<bool> {
check_ttl_secs(ttl_secs)?;
let json = serde_json::to_string(value).map_err(|e| Error::Msg(e.to_string()))?;
let result: Option<String> = redis::cmd("SET")
.arg(key)
.arg(&json)
.arg("NX")
.arg("EX")
.arg(ttl_secs)
.query_async(&mut self.conn.clone())
.await
.map_err(Self::map_err)?;
Ok(result.is_some())
}
async fn del(&self, key: &str) -> Result<()> {
redis::cmd("DEL")
.arg(key)
.query_async::<()>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn exists(&self, key: &str) -> Result<bool> {
redis::cmd("EXISTS")
.arg(key)
.query_async::<i32>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
.map(|v| v > 0)
}
async fn incr(&self, key: &str, delta: i64) -> Result<i64> {
let result: i64 = if delta == 1 {
redis::cmd("INCR")
.arg(key)
.query_async(&mut self.conn.clone())
.await
.map_err(Self::map_err)?
} else {
redis::cmd("INCRBY")
.arg(key)
.arg(delta)
.query_async(&mut self.conn.clone())
.await
.map_err(Self::map_err)?
};
Ok(result)
}
async fn keys(&self, pattern: &str) -> Result<Vec<String>> {
let mut cursor: u64 = 0;
let mut out: Vec<String> = Vec::new();
let mut seen: HashSet<String> = HashSet::new();
loop {
let (next, keys): (u64, Vec<String>) = redis::cmd("SCAN")
.arg(cursor)
.arg("MATCH")
.arg(pattern)
.arg("COUNT")
.arg(SCAN_COUNT)
.query_async(&mut self.conn.clone())
.await
.map_err(Self::map_err)?;
for k in keys {
if !seen.contains(&k) {
seen.insert(k.clone());
out.push(k);
}
}
cursor = next;
if cursor == 0 {
break;
}
}
Ok(out)
}
async fn delete_pattern(&self, pattern: &str) -> Result<u64> {
let mut cursor: u64 = 0;
let mut total: u64 = 0;
loop {
let (next, keys): (u64, Vec<String>) = redis::cmd("SCAN")
.arg(cursor)
.arg("MATCH")
.arg(pattern)
.arg("COUNT")
.arg(SCAN_COUNT)
.query_async(&mut self.conn.clone())
.await
.map_err(Self::map_err)?;
if !keys.is_empty() {
let mut cmd = redis::cmd("UNLINK");
for k in &keys {
cmd.arg(k);
}
total += cmd
.query_async::<u64>(&mut self.conn.clone())
.await
.map_err(Self::map_err)?;
}
cursor = next;
if cursor == 0 {
break;
}
}
Ok(total)
}
async fn sadd(&self, key: &str, members: &[String]) -> Result<u64> {
if members.is_empty() {
return Ok(0);
}
let mut cmd = redis::cmd("SADD");
cmd.arg(key);
for m in members {
cmd.arg(m);
}
cmd.query_async::<u64>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn srem(&self, key: &str, members: &[String]) -> Result<u64> {
if members.is_empty() {
return Ok(0);
}
let mut cmd = redis::cmd("SREM");
cmd.arg(key);
for m in members {
cmd.arg(m);
}
cmd.query_async::<u64>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn smembers(&self, key: &str) -> Result<Vec<String>> {
redis::cmd("SMEMBERS")
.arg(key)
.query_async::<Vec<String>>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn sismember(&self, key: &str, member: &str) -> Result<bool> {
redis::cmd("SISMEMBER")
.arg(key)
.arg(member)
.query_async::<i32>(&mut self.conn.clone())
.await
.map(|v| v > 0)
.map_err(Self::map_err)
}
async fn expire(&self, key: &str, ttl_secs: u64) -> Result<bool> {
check_ttl_secs(ttl_secs)?;
redis::cmd("EXPIRE")
.arg(key)
.arg(ttl_secs)
.query_async::<i32>(&mut self.conn.clone())
.await
.map(|v| v > 0)
.map_err(Self::map_err)
}
async fn ttl(&self, key: &str) -> Result<Option<u64>> {
let v: i64 = redis::cmd("TTL")
.arg(key)
.query_async(&mut self.conn.clone())
.await
.map_err(Self::map_err)?;
Ok((v > 0).then_some(v as u64))
}
async fn sadd_with_ttl(&self, key: &str, members: &[String], ttl_secs: u64) -> Result<()> {
check_ttl_secs(ttl_secs)?;
if members.is_empty() {
return self.expire(key, ttl_secs).await.map(|_| ());
}
redis::pipe()
.atomic()
.sadd(key, members)
.expire(key, ttl_secs as i64)
.query_async::<()>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn get_raw(&self, key: &str) -> Result<Option<Vec<u8>>> {
redis::cmd("GET")
.arg(key)
.query_async::<Option<Vec<u8>>>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn set_raw(&self, key: &str, value: &[u8]) -> Result<()> {
validate_json(value)?;
redis::cmd("SET")
.arg(key)
.arg(value)
.query_async::<()>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
async fn set_raw_ex(&self, key: &str, value: &[u8], ttl_secs: u64) -> Result<()> {
check_ttl_secs(ttl_secs)?;
validate_json(value)?;
redis::cmd("SETEX")
.arg(key)
.arg(ttl_secs)
.arg(value)
.query_async::<()>(&mut self.conn.clone())
.await
.map_err(Self::map_err)
}
}
fn match_pattern(key: &str, pattern: &str) -> bool {
if !pattern.contains(&['*', '?'][..]) {
return key == pattern;
}
if let Some(prefix) = pattern.strip_suffix('*') {
if !prefix.contains(&['*', '?'][..]) {
return key.starts_with(prefix);
}
}
match_glob(key.as_bytes(), pattern.as_bytes())
}
fn match_glob(key: &[u8], pat: &[u8]) -> bool {
let (mut ki, mut pi) = (0usize, 0usize);
let mut star_pi: Option<usize> = None;
let mut star_ki = 0usize;
while ki < key.len() {
if pi < pat.len() && (pat[pi] == b'?' || pat[pi] == key[ki]) {
ki += 1;
pi += 1;
} else if pi < pat.len() && pat[pi] == b'*' {
star_pi = Some(pi);
star_ki = ki;
pi += 1;
} else if let Some(sp) = star_pi {
pi = sp + 1;
star_ki += 1;
ki = star_ki;
} else {
return false;
}
}
while pi < pat.len() && pat[pi] == b'*' {
pi += 1;
}
pi == pat.len()
}
#[derive(Clone, Debug)]
pub enum SharedCache {
Local(LocalCache),
#[cfg(feature = "redis")]
Redis(RedisCache),
}
impl SharedCache {
pub async fn get_or_insert_with<T, F, Fut>(
&self,
key: &str,
ttl_secs: u64,
load: F,
) -> Result<T>
where
T: DeserializeOwned + Serialize + Send + Sync,
F: FnOnce() -> Fut,
Fut: std::future::Future<Output = Result<T>>,
{
match self {
SharedCache::Local(c) => c.get_or_insert_with(key, ttl_secs, load).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => {
c.get_or_insert_with(key, ttl_secs, load).await
}
}
}
}
#[async_trait]
impl Cache for SharedCache {
async fn get<T: DeserializeOwned + Send>(&self, key: &str) -> Result<Option<T>> {
match self {
SharedCache::Local(c) => c.get(key).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.get(key).await,
}
}
async fn set<T: Serialize + Send + Sync>(&self, key: &str, value: &T) -> Result<()> {
match self {
SharedCache::Local(c) => c.set(key, value).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.set(key, value).await,
}
}
async fn set_ex<T: Serialize + Send + Sync>(
&self,
key: &str,
value: &T,
ttl_secs: u64,
) -> Result<()> {
match self {
SharedCache::Local(c) => c.set_ex(key, value, ttl_secs).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.set_ex(key, value, ttl_secs).await,
}
}
async fn del(&self, key: &str) -> Result<()> {
match self {
SharedCache::Local(c) => c.del(key).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.del(key).await,
}
}
async fn exists(&self, key: &str) -> Result<bool> {
match self {
SharedCache::Local(c) => c.exists(key).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.exists(key).await,
}
}
async fn incr(&self, key: &str, delta: i64) -> Result<i64> {
match self {
SharedCache::Local(c) => c.incr(key, delta).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.incr(key, delta).await,
}
}
async fn keys(&self, pattern: &str) -> Result<Vec<String>> {
match self {
SharedCache::Local(c) => c.keys(pattern).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.keys(pattern).await,
}
}
async fn set_nx<T: Serialize + Send + Sync>(
&self,
key: &str,
value: &T,
ttl_secs: u64,
) -> Result<bool> {
match self {
SharedCache::Local(c) => c.set_nx(key, value, ttl_secs).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.set_nx(key, value, ttl_secs).await,
}
}
async fn delete_pattern(&self, pattern: &str) -> Result<u64> {
match self {
SharedCache::Local(c) => c.delete_pattern(pattern).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.delete_pattern(pattern).await,
}
}
async fn sadd(&self, key: &str, members: &[String]) -> Result<u64> {
match self {
SharedCache::Local(c) => c.sadd(key, members).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.sadd(key, members).await,
}
}
async fn srem(&self, key: &str, members: &[String]) -> Result<u64> {
match self {
SharedCache::Local(c) => c.srem(key, members).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.srem(key, members).await,
}
}
async fn smembers(&self, key: &str) -> Result<Vec<String>> {
match self {
SharedCache::Local(c) => c.smembers(key).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.smembers(key).await,
}
}
async fn sismember(&self, key: &str, member: &str) -> Result<bool> {
match self {
SharedCache::Local(c) => c.sismember(key, member).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.sismember(key, member).await,
}
}
async fn expire(&self, key: &str, ttl_secs: u64) -> Result<bool> {
match self {
SharedCache::Local(c) => c.expire(key, ttl_secs).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.expire(key, ttl_secs).await,
}
}
async fn ttl(&self, key: &str) -> Result<Option<u64>> {
match self {
SharedCache::Local(c) => c.ttl(key).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.ttl(key).await,
}
}
async fn sadd_with_ttl(&self, key: &str, members: &[String], ttl_secs: u64) -> Result<()> {
match self {
SharedCache::Local(c) => c.sadd_with_ttl(key, members, ttl_secs).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.sadd_with_ttl(key, members, ttl_secs).await,
}
}
async fn get_raw(&self, key: &str) -> Result<Option<Vec<u8>>> {
match self {
SharedCache::Local(c) => c.get_raw(key).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.get_raw(key).await,
}
}
async fn set_raw(&self, key: &str, value: &[u8]) -> Result<()> {
match self {
SharedCache::Local(c) => c.set_raw(key, value).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.set_raw(key, value).await,
}
}
async fn set_raw_ex(&self, key: &str, value: &[u8], ttl_secs: u64) -> Result<()> {
match self {
SharedCache::Local(c) => c.set_raw_ex(key, value, ttl_secs).await,
#[cfg(feature = "redis")]
SharedCache::Redis(c) => c.set_raw_ex(key, value, ttl_secs).await,
}
}
fn stats(&self) -> CacheStats {
match self {
SharedCache::Local(c) => c.stats(),
#[cfg(feature = "redis")]
SharedCache::Redis(_) => CacheStats::default(),
}
}
}
pub fn delete_after(cache: SharedCache, key: String, delay: Duration) -> tokio::task::JoinHandle<()> {
tokio::spawn(async move {
tokio::time::sleep(delay).await;
if let Err(e) = cache.del(&key).await {
tracing::warn!(key = %key, error = %e, "延迟双删第二次删除失败");
}
})
}
pub fn delete_pattern_after(
cache: SharedCache,
pattern: String,
delay: Duration,
) -> tokio::task::JoinHandle<()> {
tokio::spawn(async move {
tokio::time::sleep(delay).await;
if let Err(e) = cache.delete_pattern(&pattern).await {
tracing::warn!(pattern = %pattern, error = %e, "延迟双删(模式)第二次删除失败");
}
})
}
pub async fn create_cache(
cache_config: &wordval_config::CacheConfig,
redis_config: &wordval_config::RedisConfig,
) -> Result<SharedCache> {
match cache_config.r#type.as_str() {
"redis" => {
#[cfg(not(feature = "redis"))]
{
let _ = redis_config;
Err(Error::Config(
"cache.type=redis 需要启用 wordval-cache 的 \"redis\" feature(默认启用)"
.into(),
))
}
#[cfg(feature = "redis")]
{
let redis_url = std::env::var("REDIS_URL")
.ok()
.filter(|s| !s.is_empty())
.unwrap_or_else(|| redis_config.url.clone());
tracing::info!(
"使用 Redis 缓存 url={}",
sanitize_redis_url(&redis_url)
);
Ok(SharedCache::Redis(RedisCache::connect(&redis_url).await?))
}
}
"local" => {
tracing::info!("使用本地缓存 capacity={}", cache_config.max_capacity);
let cache = LocalCache::new(cache_config.max_capacity, cache_config.default_ttl);
cache.start_background_cleanup();
Ok(SharedCache::Local(cache))
}
other => Err(Error::Config(format!(
"cache.type 无效: \"{other}\"(支持 \"local\" / \"redis\")"
))),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test]
async fn test_local_cache_get_set() {
let c = LocalCache::new(100, 0);
c.set("key1", &"value1".to_string()).await.unwrap();
let val: Option<String> = c.get("key1").await.unwrap();
assert_eq!(val, Some("value1".to_string()));
c.del("key1").await.unwrap();
let val: Option<String> = c.get("key1").await.unwrap();
assert_eq!(val, None);
}
#[tokio::test]
async fn test_set_ex_expiration() {
let c = LocalCache::new(100, 0);
c.set_ex("temp", &"expire".to_string(), 1).await.unwrap();
let val: Option<String> = c.get("temp").await.unwrap();
assert_eq!(val, Some("expire".to_string()));
tokio::time::sleep(Duration::from_secs(2)).await;
let val: Option<String> = c.get("temp").await.unwrap();
assert_eq!(val, None);
}
#[tokio::test]
async fn test_incr() {
let c = LocalCache::new(100, 0);
assert_eq!(c.incr("counter", 1).await.unwrap(), 1);
assert_eq!(c.incr("counter", 5).await.unwrap(), 6);
assert_eq!(c.incr("counter", -2).await.unwrap(), 4);
}
#[tokio::test]
async fn test_keys_pattern() {
let c = LocalCache::new(100, 0);
c.set("user:1", &"alice").await.unwrap();
c.set("user:2", &"bob").await.unwrap();
c.set("order:1", &"o1").await.unwrap();
let keys = c.keys("user:*").await.unwrap();
assert_eq!(keys.len(), 2);
assert!(keys.contains(&"user:1".to_string()));
assert!(keys.contains(&"user:2".to_string()));
}
#[tokio::test]
async fn test_inflight_guard_cleans_after_cancel() {
let c = LocalCache::new(100, 0);
let handle = tokio::spawn({
let c = c.clone();
async move {
let _ = c
.get_or_insert_with::<String, _, _>("cancel", 60, || async {
tokio::time::sleep(Duration::from_secs(30)).await;
Ok("v".to_string())
})
.await;
}
});
tokio::time::sleep(Duration::from_millis(100)).await;
assert_eq!(
c.inner.inflight.len(),
1,
"回源期间去重表应持有条目"
);
handle.abort();
for _ in 0..50 {
if c.inner.inflight.is_empty() {
break;
}
tokio::time::sleep(Duration::from_millis(20)).await;
}
assert!(
c.inner.inflight.is_empty(),
"取消后去重表条目应被守卫清理,实际剩余 {}",
c.inner.inflight.len()
);
let v: String = c
.get_or_insert_with("cancel", 60, || async { Ok("ok".to_string()) })
.await
.unwrap();
assert_eq!(v, "ok");
}
#[tokio::test]
async fn test_debug_impl() {
let c = LocalCache::new(100, 0);
c.set("secret_key", &"secret_value".to_string()).await.unwrap();
let s = format!("{c:?}");
assert!(s.contains("LocalCache"), "Debug 应含类型名: {s}");
assert!(
!s.contains("secret"),
"Debug 不应输出条目数据: {s}"
);
let shared = SharedCache::Local(c);
assert!(format!("{shared:?}").starts_with("Local("));
}
#[tokio::test]
async fn test_delete_pattern() {
let c = LocalCache::new(100, 0);
c.set("session:a", &"s1").await.unwrap();
c.set("session:b", &"s2").await.unwrap();
c.set("user:1", &"alice").await.unwrap();
let deleted = c.delete_pattern("session:*").await.unwrap();
assert_eq!(deleted, 2);
assert!(!c.exists("session:a").await.unwrap());
assert!(!c.exists("session:b").await.unwrap());
assert!(c.exists("user:1").await.unwrap());
}
}