secra_cache/

plugin.rs

use async_trait::async_trait;
use redis::AsyncCommands;
use serde::Serialize;
use serde::de::DeserializeOwned;
/// PluginCache 实现
use std::sync::Arc;
use std::time::Duration;

use super::error::CacheError;
use super::manager::CacheManager;
use super::traits::Cache;

/// 插件缓存实例
///
/// 每个插件拥有一个独立的 PluginCache 实例，所有操作自动添加命名空间前缀
pub struct PluginCache {
    /// CacheManager 引用
    manager: Arc<CacheManager>,

    /// 插件 ID
    plugin_id: String,

    /// 命名空间前缀
    namespace: String,
}

impl PluginCache {
    /// 创建新的 PluginCache 实例
    ///
    /// 为指定的插件创建一个独立的缓存实例，所有操作会自动添加命名空间前缀。
    /// 命名空间格式为：`{system_name}:plugin:{plugin_id}:`
    ///
    /// # Arguments
    /// * `manager` - CacheManager 的引用，用于管理 Redis 连接和配置
    /// * `plugin_id` - 插件的唯一标识符，用于构建命名空间前缀
    ///
    /// # Returns
    /// * `Self` - 新创建的 PluginCache 实例
    ///
    /// # 命名空间隔离
    /// 每个插件拥有独立的命名空间，确保不同插件的缓存数据完全隔离，
    /// 防止 Key 冲突和跨插件访问。
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # use std::sync::Arc;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let manager = todo!();
    /// let plugin_cache = PluginCache::new(manager, "my_plugin".to_string());
    /// # Ok(())
    /// # }
    /// ```
    pub(crate) fn new(manager: Arc<CacheManager>, plugin_id: String) -> Self {
        let namespace = format!("{}:plugin:{}:", manager.system_name(), plugin_id);
        Self {
            manager,
            plugin_id,
            namespace,
        }
    }

    /// 构建完整的 Key（添加命名空间前缀）
    ///
    /// 将业务 Key 与插件的命名空间前缀组合，生成完整的缓存 Key。
    /// 在组合之前会先验证业务 Key 的格式。
    ///
    /// # Arguments
    /// * `business_key` - 业务 Key（不包含命名空间前缀）
    ///
    /// # Returns
    /// * `Ok(String)` - 完整的缓存 Key（包含命名空间前缀）
    /// * `Err(CacheError::InvalidKey)` - 业务 Key 格式验证失败
    ///
    /// # 性能优化
    /// * 使用 `String::with_capacity` 预分配容量，减少内存重新分配
    /// * 容量计算为命名空间长度 + 业务 Key 长度，避免扩容
    ///
    /// # 安全性
    /// * 在构建 Key 之前会调用 `validate_business_key` 进行格式验证
    /// * 确保业务 Key 符合安全规范，防止注入攻击
    ///
    /// # Example
    /// 如果命名空间为 `system:plugin:my_plugin:`，业务 Key 为 `user:123`，
    /// 则返回的完整 Key 为 `system:plugin:my_plugin:user:123`
    fn build_key(&self, business_key: &str) -> Result<String, CacheError> {
        // 验证业务 Key 格式
        self.validate_business_key(business_key)?;

        // 性能优化：预分配容量，减少内存重新分配
        let mut full_key = String::with_capacity(self.namespace.len() + business_key.len());
        full_key.push_str(&self.namespace);
        full_key.push_str(business_key);
        Ok(full_key)
    }

    /// 验证业务 Key 格式
    ///
    /// 对业务 Key 进行格式验证，确保符合安全规范和性能要求。
    /// 验证规则包括：非空、长度限制、字符限制、命名空间前缀检查。
    ///
    /// # Arguments
    /// * `key` - 待验证的业务 Key
    ///
    /// # Returns
    /// * `Ok(())` - Key 格式验证通过
    /// * `Err(CacheError::InvalidKey)` - Key 格式验证失败，包含具体错误信息
    ///
    /// # 验证规则
    /// 1. **非空检查**：Key 不能为空字符串
    /// 2. **长度限制**：Key 长度不能超过 200 字符（防止过长的 Key 影响性能）
    /// 3. **字符限制**：只允许 ASCII 字母、数字、下划线(`_`)、连字符(`-`)、冒号(`:`)
    /// 4. **命名空间前缀检查**：Key 不能包含系统命名空间前缀，防止绕过隔离机制
    ///
    /// # 性能优化
    /// * 使用 `as_bytes().iter()` 进行字节级检查，比 `chars()` 迭代更快
    /// * 使用 `is_ascii_alphanumeric()` 进行字符类型判断，避免 Unicode 处理开销
    /// * 提前返回机制，一旦发现不符合规则立即返回错误
    ///
    /// # 安全性
    /// * 防止通过构造特殊 Key 访问其他插件的缓存数据
    /// * 限制字符集，防止注入攻击和特殊字符导致的 Redis 命令注入
    ///
    /// # Errors
    /// * `CacheError::InvalidKey("Key 不能为空")` - Key 为空字符串
    /// * `CacheError::InvalidKey("Key 长度不能超过 200 字符")` - Key 长度超限
    /// * `CacheError::InvalidKey("Key 包含非法字符...")` - Key 包含不允许的字符
    /// * `CacheError::InvalidKey("Key 不能包含命名空间前缀")` - Key 包含命名空间前缀
    fn validate_business_key(&self, key: &str) -> Result<(), CacheError> {
        // 1. 不能为空
        if key.is_empty() {
            return Err(CacheError::InvalidKey("Key 不能为空".to_string()));
        }

        // 2. 长度限制（提前检查，避免后续不必要的操作）
        if key.len() > 200 {
            return Err(CacheError::InvalidKey(
                "Key 长度不能超过 200 字符".to_string(),
            ));
        }

        // 3. 字符限制（只允许字母、数字、下划线、连字符、冒号）
        // 性能优化：使用字节检查，比 chars() 更快
        if !key.as_bytes().iter().all(|&b| {
            b.is_ascii_alphanumeric() || b == b'_' || b == b'-' || b == b':'
        }) {
            return Err(CacheError::InvalidKey(
                "Key 包含非法字符，只允许字母、数字、下划线、连字符、冒号".to_string(),
            ));
        }

        // 4. 不能包含命名空间分隔符（防止绕过隔离）
        // 性能优化：避免 format!，直接检查字符串片段
        let forbidden_prefix = format!("{}:plugin:", self.manager.system_name());
        if key.contains(&forbidden_prefix) {
            return Err(CacheError::InvalidKey(
                "Key 不能包含命名空间前缀".to_string(),
            ));
        }

        Ok(())
    }

    /// 验证权限（确保只能操作自己的 Key）
    ///
    /// 检查给定的完整 Key 是否属于当前插件的命名空间，防止跨插件访问。
    ///
    /// # Arguments
    /// * `full_key` - 完整的缓存 Key（包含命名空间前缀）
    ///
    /// # Returns
    /// * `Ok(())` - Key 属于当前插件，权限验证通过
    /// * `Err(CacheError::PermissionDenied)` - Key 不属于当前插件，权限验证失败
    ///
    /// # 安全性
    /// 此方法用于防止插件通过构造 Key 访问或修改其他插件的缓存数据。
    fn verify_permission(&self, full_key: &str) -> Result<(), CacheError> {
        if !full_key.starts_with(&self.namespace) {
            return Err(CacheError::PermissionDenied(
                "Key 不属于当前插件".to_string(),
            ));
        }
        Ok(())
    }
}

#[async_trait]
impl Cache for PluginCache {
    /// 获取缓存值
    ///
    /// 根据业务 Key 获取缓存中的值，自动添加命名空间前缀。
    /// 如果 Key 不存在或已过期，返回 `None`。
    ///
    /// # Arguments
    /// * `key` - 业务 Key（不包含命名空间前缀）
    ///
    /// # Type Parameters
    /// * `T` - 返回值的类型，必须实现 `DeserializeOwned` trait
    ///
    /// # Returns
    /// * `Ok(Some(T))` - 成功获取到缓存值
    /// * `Ok(None)` - Key 不存在或已过期
    /// * `Err(CacheError)` - 操作失败（如 Key 格式错误、权限不足、反序列化失败等）
    ///
    /// # Errors
    /// * `CacheError::InvalidKey` - Key 格式验证失败
    /// * `CacheError::PermissionDenied` - Key 不属于当前插件
    /// * `CacheError::OperationFailed` - Redis 操作失败
    /// * `CacheError::DeserializationFailed` - JSON 反序列化失败
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let cache = todo!();
    /// let value: Option<String> = cache.get("user:123").await?;
    /// if let Some(v) = value {
    ///     println!("缓存值: {}", v);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    async fn get<T>(&self, key: &str) -> Result<Option<T>, CacheError>
    where
        T: DeserializeOwned,
    {
        let full_key = self.build_key(key)?;
        
        // 安全优化：验证权限（防止通过构造的 key 访问其他插件的缓存）
        self.verify_permission(&full_key)?;
        
        let mut conn = self.manager.get_connection().await?;

        // 从 Redis 获取值
        let json_value: Option<String> = conn
            .get(&full_key)
            .await
            .map_err(|e| CacheError::OperationFailed(e.to_string()))?;

        // 反序列化
        match json_value {
            Some(json) => {
                // 性能优化：使用 from_slice 替代 from_str（如果可能）
                let value: T = serde_json::from_str(&json)
                    .map_err(|e| CacheError::DeserializationFailed(e.to_string()))?;
                Ok(Some(value))
            }
            None => Ok(None),
        }
    }

    /// 设置缓存值
    ///
    /// 将值存储到缓存中，自动添加命名空间前缀。
    /// 如果提供了 TTL，则设置过期时间；否则使用默认 TTL。
    /// 操作完成后会自动将 Key 添加到插件的索引中。
    ///
    /// # Arguments
    /// * `key` - 业务 Key（不包含命名空间前缀）
    /// * `value` - 要缓存的值，必须实现 `Serialize` 和 `Sync` trait
    /// * `ttl` - 可选的过期时间，如果为 `None` 则使用默认 TTL
    ///
    /// # Type Parameters
    /// * `T` - 值的类型，必须实现 `Serialize` 和 `Sync` trait
    ///
    /// # Returns
    /// * `Ok(())` - 成功设置缓存
    /// * `Err(CacheError)` - 操作失败（如 Key 格式错误、权限不足、序列化失败等）
    ///
    /// # Errors
    /// * `CacheError::InvalidKey` - Key 格式验证失败
    /// * `CacheError::PermissionDenied` - Key 不属于当前插件
    /// * `CacheError::OperationFailed` - Redis 操作失败
    /// * `CacheError::SerializationFailed` - JSON 序列化失败
    ///
    /// # 性能说明
    /// * 索引更新是异步非阻塞的，不会影响主操作的性能
    /// * 序列化使用 `serde_json::to_string`，会自动优化内存分配
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # use std::time::Duration;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let cache = todo!();
    /// cache.set("user:123", &"John Doe", Some(Duration::from_secs(3600))).await?;
    /// # Ok(())
    /// # }
    /// ```
    async fn set<T>(&self, key: &str, value: &T, ttl: Option<Duration>) -> Result<(), CacheError>
    where
        T: Serialize + Sync,
    {
        let full_key = self.build_key(key)?;
        
        // 安全优化：验证权限（防止通过构造的 key 设置其他插件的缓存）
        self.verify_permission(&full_key)?;
        
        // 序列化为 JSON 字符串
        // 性能优化：预分配容量（可选，serde_json 会自动优化）
        let json_value = serde_json::to_string(value)
            .map_err(|e| CacheError::SerializationFailed(e.to_string()))?;

        let mut conn = self.manager.get_connection().await?;
        let ttl_secs = self.manager.resolve_ttl(ttl);

        // 设置到 Redis（使用 SET key value EX ttl）
        let _: String = redis::cmd("SET")
            .arg(&full_key)
            .arg(&json_value)
            .arg("EX")
            .arg(ttl_secs)
            .query_async(&mut conn)
            .await
            .map_err(|e| CacheError::OperationFailed(e.to_string()))?;

        // 更新索引（异步非阻塞，不等待完成）
        self.manager
            .add_key_to_index(&self.plugin_id, &full_key)
            .await;

        Ok(())
    }

    /// 删除缓存值
    ///
    /// 从缓存中删除指定的 Key，如果 Key 存在则删除并返回 `true`，
    /// 如果 Key 不存在则返回 `false`。
    /// 删除成功后会自动从插件的索引中移除该 Key。
    ///
    /// # Arguments
    /// * `key` - 业务 Key（不包含命名空间前缀）
    ///
    /// # Returns
    /// * `Ok(true)` - Key 存在且已成功删除
    /// * `Ok(false)` - Key 不存在
    /// * `Err(CacheError)` - 操作失败（如 Key 格式错误、权限不足等）
    ///
    /// # Errors
    /// * `CacheError::InvalidKey` - Key 格式验证失败
    /// * `CacheError::PermissionDenied` - Key 不属于当前插件
    /// * `CacheError::OperationFailed` - Redis 操作失败
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let cache = todo!();
    /// let deleted = cache.delete("user:123").await?;
    /// if deleted {
    ///     println!("缓存已删除");
    /// }
    /// # Ok(())
    /// # }
    /// ```
    async fn delete(&self, key: &str) -> Result<bool, CacheError> {
        let full_key = self.build_key(key)?;

        // 验证权限
        self.verify_permission(&full_key)?;

        let mut conn = self.manager.get_connection().await?;

        // 删除 Key
        let deleted: u64 = conn
            .del(&full_key)
            .await
            .map_err(|e| CacheError::OperationFailed(e.to_string()))?;

        // 从索引中移除
        if deleted > 0 {
            self.manager
                .remove_key_from_index(&self.plugin_id, &full_key)
                .await;
        }

        Ok(deleted > 0)
    }

    /// 检查 Key 是否存在
    ///
    /// 检查指定的 Key 是否存在于缓存中，无论是否已过期。
    ///
    /// # Arguments
    /// * `key` - 业务 Key（不包含命名空间前缀）
    ///
    /// # Returns
    /// * `Ok(true)` - Key 存在
    /// * `Ok(false)` - Key 不存在
    /// * `Err(CacheError)` - 操作失败（如 Key 格式错误、权限不足等）
    ///
    /// # Errors
    /// * `CacheError::InvalidKey` - Key 格式验证失败
    /// * `CacheError::PermissionDenied` - Key 不属于当前插件
    /// * `CacheError::OperationFailed` - Redis 操作失败
    ///
    /// # Note
    /// 此方法只检查 Key 是否存在，不检查是否已过期。
    /// 如果需要检查 Key 是否存在且未过期，建议使用 `get` 方法。
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let cache = todo!();
    /// if cache.exists("user:123").await? {
    ///     println!("Key 存在");
    /// }
    /// # Ok(())
    /// # }
    /// ```
    async fn exists(&self, key: &str) -> Result<bool, CacheError> {
        let full_key = self.build_key(key)?;
        
        // 安全优化：验证权限
        self.verify_permission(&full_key)?;
        
        let mut conn = self.manager.get_connection().await?;

        // 检查 Key 是否存在
        let exists: bool = conn
            .exists(&full_key)
            .await
            .map_err(|e| CacheError::OperationFailed(e.to_string()))?;

        Ok(exists)
    }

    /// 设置 Key 的过期时间
    ///
    /// 为已存在的 Key 设置新的过期时间。如果 Key 不存在，返回 `false`。
    ///
    /// # Arguments
    /// * `key` - 业务 Key（不包含命名空间前缀）
    /// * `ttl` - 新的过期时间
    ///
    /// # Returns
    /// * `Ok(true)` - Key 存在且已成功设置过期时间
    /// * `Ok(false)` - Key 不存在
    /// * `Err(CacheError)` - 操作失败（如 Key 格式错误、权限不足等）
    ///
    /// # Errors
    /// * `CacheError::InvalidKey` - Key 格式验证失败
    /// * `CacheError::PermissionDenied` - Key 不属于当前插件
    /// * `CacheError::OperationFailed` - Redis 操作失败
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # use std::time::Duration;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let cache = todo!();
    /// let success = cache.expire("user:123", Duration::from_secs(7200)).await?;
    /// if success {
    ///     println!("过期时间已更新");
    /// }
    /// # Ok(())
    /// # }
    /// ```
    async fn expire(&self, key: &str, ttl: Duration) -> Result<bool, CacheError> {
        let full_key = self.build_key(key)?;
        
        // 安全优化：验证权限
        self.verify_permission(&full_key)?;
        
        let mut conn = self.manager.get_connection().await?;

        // 设置过期时间
        let result: i64 = redis::cmd("EXPIRE")
            .arg(&full_key)
            .arg(ttl.as_secs() as usize)
            .query_async(&mut conn)
            .await
            .map_err(|e| CacheError::OperationFailed(e.to_string()))?;

        Ok(result == 1)
    }

    /// 获取 Key 的剩余过期时间
    ///
    /// 返回 Key 的剩余过期时间。如果 Key 不存在、已过期或永不过期，返回 `None`。
    ///
    /// # Arguments
    /// * `key` - 业务 Key（不包含命名空间前缀）
    ///
    /// # Returns
    /// * `Ok(Some(Duration))` - Key 存在且有过期时间，返回剩余时间
    /// * `Ok(None)` - Key 不存在、已过期或永不过期
    /// * `Err(CacheError)` - 操作失败（如 Key 格式错误、权限不足等）
    ///
    /// # Errors
    /// * `CacheError::InvalidKey` - Key 格式验证失败
    /// * `CacheError::PermissionDenied` - Key 不属于当前插件
    /// * `CacheError::OperationFailed` - Redis 操作失败
    ///
    /// # Redis TTL 返回值说明
    /// * `-2` - Key 不存在，返回 `None`
    /// * `-1` - Key 存在但永不过期，返回 `None`
    /// * `> 0` - Key 存在且有过期时间，返回剩余秒数
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let cache = todo!();
    /// if let Some(remaining) = cache.ttl("user:123").await? {
    ///     println!("剩余时间: {:?}", remaining);
    /// } else {
    ///     println!("Key 不存在或永不过期");
    /// }
    /// # Ok(())
    /// # }
    /// ```
    async fn ttl(&self, key: &str) -> Result<Option<Duration>, CacheError> {
        let full_key = self.build_key(key)?;
        
        // 安全优化：验证权限
        self.verify_permission(&full_key)?;
        
        let mut conn = self.manager.get_connection().await?;

        // 获取剩余过期时间
        let ttl_secs: isize = redis::cmd("TTL")
            .arg(&full_key)
            .query_async(&mut conn)
            .await
            .map_err(|e| CacheError::OperationFailed(e.to_string()))?;

        match ttl_secs {
            -2 => Ok(None), // Key 不存在
            -1 => Ok(None), // Key 存在但永不过期
            secs if secs > 0 => Ok(Some(Duration::from_secs(secs as u64))),
            _ => Ok(None),
        }
    }

    /// 清空当前插件的所有缓存
    ///
    /// 删除当前插件的所有缓存 Key，包括所有模块的数据。
    /// 此操作会清空插件的索引并删除所有相关的缓存数据。
    ///
    /// # Returns
    /// * `Ok(u64)` - 成功删除的 Key 数量
    /// * `Err(CacheError)` - 操作失败
    ///
    /// # Errors
    /// * `CacheError::OperationFailed` - Redis 操作失败
    ///
    /// # Warning
    /// 此操作不可逆，会删除当前插件的所有缓存数据，请谨慎使用。
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let cache = todo!();
    /// let deleted_count = cache.clear().await?;
    /// println!("已删除 {} 个缓存项", deleted_count);
    /// # Ok(())
    /// # }
    /// ```
    async fn clear(&self) -> Result<u64, CacheError> {
        // 清理当前插件的所有缓存
        self.manager.clear_plugin(&self.plugin_id).await
    }

    /// 清空当前插件的指定模块缓存
    ///
    /// 删除当前插件中指定模块的所有缓存 Key。
    /// 模块名称通常作为 Key 的前缀部分，用于逻辑分组。
    ///
    /// # Arguments
    /// * `module` - 模块名称，用于标识要清理的模块
    ///
    /// # Returns
    /// * `Ok(u64)` - 成功删除的 Key 数量
    /// * `Err(CacheError)` - 操作失败
    ///
    /// # Errors
    /// * `CacheError::OperationFailed` - Redis 操作失败
    ///
    /// # Note
    /// 模块名称应该与 Key 的命名规范一致，通常作为 Key 的前缀使用。
    /// 例如：如果 Key 格式为 `module:user:123`，则模块名称为 `module`。
    ///
    /// # Example
    /// ```no_run
    /// # use secra_cache::*;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let cache = todo!();
    /// let deleted_count = cache.clear_module("user").await?;
    /// println!("已删除 {} 个用户模块缓存项", deleted_count);
    /// # Ok(())
    /// # }
    /// ```
    async fn clear_module(&self, module: &str) -> Result<u64, CacheError> {
        // 清理当前插件的指定模块缓存
        self.manager.clear_module(&self.plugin_id, module).await
    }
}