use crate::error::{BaseError, Result};
use serde::{de::DeserializeOwned, Serialize};
use std::collections::HashMap;
use std::future::Future;
use std::sync::{Arc, Mutex as StdMutex, Weak};
use std::time::{Duration, SystemTime, UNIX_EPOCH};
use tokio::sync::Mutex;
use yang_db::{JsonCodec, RedisClient, RedisCodec};
const NULL_SENTINEL: &[u8] = b"\x00yang-cache-null";
#[derive(Debug, Clone)]
pub struct CacheConfig {
pub default_ttl: Duration,
pub ttl_jitter_percent: u8,
pub null_ttl: Duration,
pub single_flight: bool,
pub fail_open: bool,
}
impl Default for CacheConfig {
fn default() -> Self {
Self {
default_ttl: Duration::from_secs(300),
ttl_jitter_percent: 10,
null_ttl: Duration::from_secs(60),
single_flight: true,
fail_open: false,
}
}
}
#[derive(Clone)]
pub struct Cache {
client: RedisClient,
config: CacheConfig,
key_locks: Arc<StdMutex<HashMap<String, Weak<Mutex<()>>>>>,
}
enum Lookup {
Hit(Vec<u8>),
Null,
Miss,
}
impl Cache {
pub fn new(client: RedisClient, config: CacheConfig) -> Self {
Self {
client,
config,
key_locks: Arc::new(StdMutex::new(HashMap::new())),
}
}
pub fn client(&self) -> &RedisClient {
&self.client
}
pub fn config(&self) -> &CacheConfig {
&self.config
}
pub async fn get<T: DeserializeOwned>(&self, key: &str) -> Result<Option<T>> {
match self.lookup(key).await? {
Lookup::Hit(bytes) => Ok(Some(JsonCodec.decode(&bytes)?)),
Lookup::Null | Lookup::Miss => Ok(None),
}
}
pub async fn set<T: Serialize>(&self, key: &str, value: &T) -> Result<()> {
self.set_with_ttl(key, value, self.config.default_ttl).await
}
pub async fn set_with_ttl<T: Serialize>(
&self,
key: &str,
value: &T,
ttl: Duration,
) -> Result<()> {
let bytes = JsonCodec.encode(value)?;
self.store(key, &bytes, self.jitter(ttl)).await
}
pub async fn delete(&self, key: &str) -> Result<()> {
let namespaced = self.client.key_for(key);
match self.client.del_bytes(&[namespaced]).await {
Ok(_) => Ok(()),
Err(error) if self.config.fail_open => {
log::warn!("Redis 缓存删除失败(fail-open): {error}");
Ok(())
}
Err(error) => Err(BaseError::RedisOperationFailed(error)),
}
}
pub async fn get_or_load<T, F, Fut>(
&self,
key: &str,
ttl: Option<Duration>,
loader: F,
) -> Result<T>
where
T: Serialize + DeserializeOwned,
F: FnOnce() -> Fut,
Fut: Future<Output = Result<T>>,
{
if let Lookup::Hit(bytes) = self.lookup(key).await? {
return Ok(JsonCodec.decode(&bytes)?);
}
let key_lock = self.key_lock(key);
let guard = if self.config.single_flight {
Some(key_lock.clone().lock_owned().await)
} else {
None
};
let result = async {
if let Lookup::Hit(bytes) = self.lookup(key).await? {
return Ok(JsonCodec.decode(&bytes)?);
}
let value = loader().await?;
let bytes = JsonCodec.encode(&value)?;
self.store(
key,
&bytes,
self.jitter(ttl.unwrap_or(self.config.default_ttl)),
)
.await?;
Ok(value)
}
.await;
drop(guard);
result
}
pub async fn get_or_load_optional<T, F, Fut>(
&self,
key: &str,
ttl: Option<Duration>,
loader: F,
) -> Result<Option<T>>
where
T: Serialize + DeserializeOwned,
F: FnOnce() -> Fut,
Fut: Future<Output = Result<Option<T>>>,
{
match self.lookup(key).await? {
Lookup::Hit(bytes) => return Ok(Some(JsonCodec.decode(&bytes)?)),
Lookup::Null => return Ok(None),
Lookup::Miss => {}
}
let key_lock = self.key_lock(key);
let guard = if self.config.single_flight {
Some(key_lock.clone().lock_owned().await)
} else {
None
};
let result = async {
match self.lookup(key).await? {
Lookup::Hit(bytes) => return Ok(Some(JsonCodec.decode(&bytes)?)),
Lookup::Null => return Ok(None),
Lookup::Miss => {}
}
let value = loader().await?;
match &value {
Some(value) => {
let bytes = JsonCodec.encode(value)?;
self.store(
key,
&bytes,
self.jitter(ttl.unwrap_or(self.config.default_ttl)),
)
.await?;
}
None => {
self.store(key, NULL_SENTINEL, self.config.null_ttl).await?;
}
}
Ok(value)
}
.await;
drop(guard);
result
}
async fn lookup(&self, key: &str) -> Result<Lookup> {
let namespaced = self.client.key_for(key);
match self.client.get_bytes(namespaced).await {
Ok(Some(bytes)) if bytes.as_slice() == NULL_SENTINEL => Ok(Lookup::Null),
Ok(Some(bytes)) => Ok(Lookup::Hit(bytes)),
Ok(None) => Ok(Lookup::Miss),
Err(error) if self.config.fail_open => {
log::warn!("Redis 缓存读取失败(fail-open,按 miss 处理): {error}");
Ok(Lookup::Miss)
}
Err(error) => Err(BaseError::RedisOperationFailed(error)),
}
}
async fn store(&self, key: &str, bytes: &[u8], ttl: Duration) -> Result<()> {
let namespaced = self.client.key_for(key);
let ttl_seconds = i64::try_from(ttl.as_secs().max(1))
.map_err(|_| BaseError::ConfigError("缓存 TTL 超出 i64 范围".to_string()))?;
match self
.client
.setex_bytes(namespaced, ttl_seconds, bytes)
.await
{
Ok(()) => Ok(()),
Err(error) if self.config.fail_open => {
log::warn!("Redis 缓存写入失败(fail-open): {error}");
Ok(())
}
Err(error) => Err(BaseError::RedisOperationFailed(error)),
}
}
fn jitter(&self, ttl: Duration) -> Duration {
jitter_ttl(ttl, self.config.ttl_jitter_percent)
}
fn key_lock(&self, key: &str) -> Arc<Mutex<()>> {
let mut locks = self
.key_locks
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
locks.retain(|_, weak| weak.strong_count() > 0);
if let Some(lock) = locks.get(key).and_then(Weak::upgrade) {
return lock;
}
let lock = Arc::new(Mutex::new(()));
locks.insert(key.to_string(), Arc::downgrade(&lock));
lock
}
}
fn jitter_ttl(ttl: Duration, percent: u8) -> Duration {
let percent = u64::from(percent.min(100));
if percent == 0 {
return ttl;
}
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|duration| u64::from(duration.subsec_nanos()))
.unwrap_or(0);
let extra_percent = nanos % (percent + 1);
let extra_ms = (ttl.as_millis() as u64).saturating_mul(extra_percent) / 100;
ttl + Duration::from_millis(extra_ms)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RateLimitDecision {
pub allowed: bool,
pub current: i64,
pub limit: i64,
pub reset_after_ms: i64,
}
const RATE_LIMIT_SCRIPT: &str = r#"
local current = redis.call('INCR', KEYS[1])
if current == 1 then
redis.call('PEXPIRE', KEYS[1], ARGV[1])
end
return {current, redis.call('PTTL', KEYS[1])}
"#;
#[derive(Debug, Clone)]
pub struct RateLimiter {
client: RedisClient,
prefix: String,
}
impl RateLimiter {
pub fn new(client: RedisClient, prefix: impl Into<String>) -> Self {
Self {
client,
prefix: prefix.into(),
}
}
pub async fn check(
&self,
key: &str,
limit: i64,
window: Duration,
) -> Result<RateLimitDecision> {
if limit <= 0 {
return Err(BaseError::ConfigError("限流 limit 必须大于 0".to_string()));
}
let window_ms = i64::try_from(window.as_millis())
.map_err(|_| BaseError::ConfigError("限流窗口超出 i64 范围".to_string()))?;
if window_ms <= 0 {
return Err(BaseError::ConfigError(
"限流窗口必须大于 0 毫秒".to_string(),
));
}
let cache_key = format!("{}:{}", self.prefix, key);
let namespaced = match self.client.namespace() {
Some(namespace) => namespace.key_str(&cache_key),
None => cache_key,
};
let script = self.client.script(RATE_LIMIT_SCRIPT);
let (current, ttl_ms): (i64, i64) = self
.client
.eval_script(&script, &[namespaced], &[window_ms.to_string()])
.await
.map_err(BaseError::RedisOperationFailed)?;
Ok(RateLimitDecision {
allowed: current <= limit,
current,
limit,
reset_after_ms: ttl_ms.max(0),
})
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn jitter_is_noop_when_percent_is_zero() {
let ttl = Duration::from_secs(100);
assert_eq!(jitter_ttl(ttl, 0), ttl);
}
#[test]
fn jitter_stays_within_configured_percent() {
let ttl = Duration::from_secs(100);
for _ in 0..100 {
let jittered = jitter_ttl(ttl, 10);
assert!(jittered >= ttl);
assert!(jittered <= ttl + Duration::from_secs(10));
}
}
#[test]
fn null_sentinel_is_not_valid_json() {
assert!(serde_json::from_slice::<serde_json::Value>(NULL_SENTINEL).is_err());
}
}