oxcache 0.5.0-rc.7

// Copyright (c) 2025-2026 Kirky.X🌠
// SPDX-License-Identifier: MIT
//! 缓存键生成器工具类
//!
//! 提供标准化的缓存键生成、验证和管理功能：
//! - 基于模板的键生成
//! - 命名空间/前缀管理
//! - 键验证（拒绝式校验：空键/超长/非法字符；不做改写式规范化）
//! - 长键的哈希指纹生成（[`KeyGenerator::json_hash_key`]，`integrity` 门控）

use crate::error::OxCacheError;
use crate::utils::MAX_CACHE_KEY_LENGTH;

/// 默认命名空间
const DEFAULT_NAMESPACE: &str = "default";

/// 有效的键字符集
const VALID_KEY_CHARS: &[char] = &[
    'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's',
    't', 'u', 'v', 'w', 'x', 'y', 'z', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L',
    'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '0', '1', '2', '3', '4',
    '5', '6', '7', '8', '9', '-', '_', '.', ':', '/', '@',
];

/// 缓存键生成器
///
/// 提供标准化的缓存键生成、验证和管理功能。
/// 支持模板化键生成、命名空间管理、键验证和哈希指纹。
///
/// # 示例
///
/// ```
/// use oxcache::KeyGenerator;
///
/// let generator = KeyGenerator::new()
///     .with_namespace("app:v1");
///
/// let key = generator.generate_full("user:{id}", &[("id", "123")]);
/// assert_eq!(key, "app:v1:user:123");
/// ```
#[derive(Clone, Debug)]
pub struct KeyGenerator {
    namespace: String,
    prefix: String,
    max_key_length: usize,
}

impl Default for KeyGenerator {
    fn default() -> Self {
        Self::new()
    }
}

impl KeyGenerator {
    /// 创建新的键生成器实例
    ///
    /// 使用默认配置（无命名空间、无前缀、256字符最大长度）
    pub fn new() -> Self {
        Self {
            namespace: DEFAULT_NAMESPACE.to_string(),
            prefix: String::new(),
            max_key_length: MAX_CACHE_KEY_LENGTH,
        }
    }

    /// 创建带有应用前缀的键生成器
    ///
    /// # 示例
    ///
    /// ```
    /// use oxcache::KeyGenerator;
    ///
    /// let generator = KeyGenerator::with_prefix("session:");
    /// let key = generator.generate_full("user:{id}", &[("id", "123")]);
    /// assert_eq!(key, "session:user:123");
    /// ```
    pub fn with_prefix(prefix: &str) -> Self {
        Self {
            namespace: DEFAULT_NAMESPACE.to_string(),
            prefix: prefix.to_string(),
            max_key_length: MAX_CACHE_KEY_LENGTH,
        }
    }

    /// 设置命名空间
    pub fn with_namespace(mut self, namespace: &str) -> Self {
        self.namespace = namespace.to_string();
        self
    }

    /// 设置前缀
    pub fn with_prefix_str(mut self, prefix: &str) -> Self {
        self.prefix = prefix.to_string();
        self
    }

    /// 设置最大键长度
    pub fn with_max_key_length(mut self, length: usize) -> Self {
        self.max_key_length = length;
        self
    }

    /// 生成缓存键
    ///
    /// 支持模板语法 {placeholder}，可以从参数中替换值
    ///
    /// # 示例
    ///
    /// ```
    /// use oxcache::KeyGenerator;
    ///
    /// let generator = KeyGenerator::new();
    /// let key = generator.generate("user:{id}", &[("id", "123")]);
    /// assert_eq!(key, "user:123");
    /// ```
    pub fn generate(&self, template: &str, params: &[(&str, &str)]) -> String {
        let mut result = template.to_string();
        for (key, value) in params {
            let placeholder = format!("{{{}}}", key);
            result = result.replace(&placeholder, value);
        }
        result
    }

    /// 生成带有命名空间和前缀的完整缓存键
    ///
    /// 注意：此方法不执行键验证。若需要验证，请使用 [`try_generate_full`](Self::try_generate_full)。
    pub fn generate_full(&self, template: &str, params: &[(&str, &str)]) -> String {
        let key = self.generate(template, params);
        let prefixed = self.apply_prefix(&key);
        self.namespaced_key(&prefixed)
    }

    /// 生成带有命名空间和前缀的完整缓存键，并验证键的有效性
    ///
    /// 与 [`generate_full`](Self::generate_full) 不同，此方法在生成后调用
    /// [`validate_key`](Self::validate_key) 检查键是否为空、是否超长、
    /// 以及是否包含非法字符。
    ///
    /// # Errors
    ///
    /// 返回 [`OxCacheError::InvalidInput`] 当生成的键未通过验证时。
    pub fn try_generate_full(
        &self,
        template: &str,
        params: &[(&str, &str)],
    ) -> Result<String, OxCacheError> {
        let key = self.generate(template, params);
        let prefixed = self.apply_prefix(&key);
        let full_key = self.namespaced_key(&prefixed);
        self.validate_key(&full_key)?;
        Ok(full_key)
    }

    /// 应用前缀到键
    fn apply_prefix(&self, key: &str) -> String {
        if self.prefix.is_empty() {
            key.to_string()
        } else {
            format!("{}{}", self.prefix, key)
        }
    }

    /// 验证键是否有效
    pub fn validate_key(&self, key: &str) -> Result<(), OxCacheError> {
        if key.is_empty() {
            return Err(OxCacheError::InvalidInput(
                "Cache key cannot be empty".to_string(),
            ));
        }
        if key.len() > self.max_key_length {
            return Err(OxCacheError::InvalidInput(format!(
                "Cache key exceeds maximum length of {} characters",
                self.max_key_length
            )));
        }
        for c in key.chars() {
            if !VALID_KEY_CHARS.contains(&c) {
                return Err(OxCacheError::InvalidInput(format!(
                    "Cache key contains invalid character: '{}'",
                    c
                )));
            }
        }
        Ok(())
    }

    /// 生成带有命名空间的键
    pub fn namespaced_key(&self, key: &str) -> String {
        if self.namespace.is_empty() || self.namespace == DEFAULT_NAMESPACE {
            key.to_string()
        } else {
            format!("{}:{}", self.namespace, key)
        }
    }

    /// 基于规范化 JSON 体生成哈希指纹缓存键
    ///
    /// 组装顺序：`parts` 段（`:` 连接）→ body 经
    /// [`canonical_json_string`](crate::canonical_json_string)
    /// 归一化后的 sha256 hex 摘要段 → 前缀/命名空间包装 → 键验证。
    /// 同一 JSON 语义（键序无关）恒得同一键；体变则键变。
    ///
    /// 长键场景以固定长度摘要段替换超长体，避免键超长。
    ///
    /// # Errors
    ///
    /// 返回 [`OxCacheError::InvalidInput`] 当 `parts` 含 `:`（段分隔符，
    /// 会造成不同分组的别名碰撞）或组装出的键未通过
    /// [`validate_key`](Self::validate_key) 时。
    #[cfg(feature = "integrity")]
    pub fn json_hash_key(
        &self,
        parts: &[&str],
        body: &serde_json::Value,
    ) -> Result<String, OxCacheError> {
        use sha2::Digest;
        use std::fmt::Write as _;

        if let Some(part) = parts.iter().find(|p| p.contains(':')) {
            return Err(OxCacheError::InvalidInput(format!(
                "json_hash_key parts must not contain the ':' segment separator: '{part}'"
            )));
        }

        let canonical = super::canonical::canonical_json_string(body);
        let digest = sha2::Sha256::digest(canonical.as_bytes());
        let mut hash = String::with_capacity(digest.len() * 2);
        for byte in digest.iter() {
            let _ = write!(hash, "{byte:02x}");
        }

        let mut segments = Vec::with_capacity(parts.len() + 1);
        segments.extend_from_slice(parts);
        segments.push(&hash);
        let key = segments.join(":");

        let prefixed = self.apply_prefix(&key);
        let full = self.namespaced_key(&prefixed);
        self.validate_key(&full)?;
        Ok(full)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_key_generator_new() {
        let key_gen = KeyGenerator::new();
        assert_eq!(key_gen.namespace, "default");
        assert_eq!(key_gen.prefix, "");
        assert_eq!(key_gen.max_key_length, 256);
    }

    #[test]
    fn test_key_generator_default() {
        let key_gen = KeyGenerator::default();
        assert_eq!(key_gen.namespace, "default");
    }

    #[test]
    fn test_key_generator_with_prefix() {
        let key_gen = KeyGenerator::with_prefix("session:");
        assert_eq!(key_gen.prefix, "session:");
        assert_eq!(key_gen.namespace, "default");
    }

    #[test]
    fn test_key_generator_with_namespace() {
        let key_gen = KeyGenerator::new().with_namespace("myapp");
        assert_eq!(key_gen.namespace, "myapp");
    }

    #[test]
    fn test_key_generator_with_prefix_str() {
        let key_gen = KeyGenerator::new().with_prefix_str("v2:");
        assert_eq!(key_gen.prefix, "v2:");
    }

    #[test]
    fn test_key_generator_with_max_key_length() {
        let key_gen = KeyGenerator::new().with_max_key_length(512);
        assert_eq!(key_gen.max_key_length, 512);
    }

    #[test]
    fn test_key_generator_generate_basic() {
        let key_gen = KeyGenerator::new();
        let key = key_gen.generate("user:{id}", &[("id", "123")]);
        assert_eq!(key, "user:123");
    }

    #[test]
    fn test_key_generator_generate_multiple_params() {
        let key_gen = KeyGenerator::new();
        let key = key_gen.generate(
            "search:{type}:{query}",
            &[("type", "products"), ("query", "laptop")],
        );
        assert_eq!(key, "search:products:laptop");
    }

    #[test]
    fn test_key_generator_generate_no_params() {
        let key_gen = KeyGenerator::new();
        let key = key_gen.generate("static:key", &[]);
        assert_eq!(key, "static:key");
    }

    #[test]
    fn test_key_generator_generate_unreplaced_placeholder() {
        let key_gen = KeyGenerator::new();
        let key = key_gen.generate("user:{id}", &[]);
        assert_eq!(key, "user:{id}");
    }

    #[test]
    fn test_key_generator_generate_full_with_namespace() {
        let key_gen = KeyGenerator::new().with_namespace("app");
        let key = key_gen.generate_full("user:{id}", &[("id", "42")]);
        assert_eq!(key, "app:user:42");
    }

    #[test]
    fn test_key_generator_generate_full_with_prefix() {
        let key_gen = KeyGenerator::with_prefix("cache:").with_namespace("app");
        let key = key_gen.generate_full("user:{id}", &[("id", "1")]);
        assert_eq!(key, "app:cache:user:1");
    }

    #[test]
    fn test_key_generator_generate_full_default_namespace() {
        // Default namespace "default" should not be prefixed
        let key_gen = KeyGenerator::new();
        let key = key_gen.generate_full("user:{id}", &[("id", "1")]);
        assert_eq!(key, "user:1");
    }

    #[test]
    fn test_key_generator_namespaced_key_with_namespace() {
        let key_gen = KeyGenerator::new().with_namespace("myapp");
        assert_eq!(key_gen.namespaced_key("user:1"), "myapp:user:1");
    }

    #[test]
    fn test_key_generator_namespaced_key_default_namespace() {
        let key_gen = KeyGenerator::new();
        assert_eq!(key_gen.namespaced_key("user:1"), "user:1");
    }

    #[test]
    fn test_key_generator_namespaced_key_empty_namespace() {
        let key_gen = KeyGenerator::new().with_namespace("");
        assert_eq!(key_gen.namespaced_key("user:1"), "user:1");
    }

    #[test]
    fn test_key_generator_validate_key_valid() {
        let key_gen = KeyGenerator::new();
        assert!(key_gen.validate_key("user:123").is_ok());
        assert!(key_gen.validate_key("cache/item").is_ok());
        assert!(key_gen.validate_key("session@abc").is_ok());
        assert!(key_gen.validate_key("a.b-c_d").is_ok());
    }

    #[test]
    fn test_key_generator_validate_key_empty() {
        let key_gen = KeyGenerator::new();
        let result = key_gen.validate_key("");
        assert!(result.is_err());
        let err = result.unwrap_err();
        match err {
            crate::error::OxCacheError::InvalidInput(msg) => {
                assert!(msg.contains("cannot be empty"))
            }
            _ => panic!("Expected InvalidInput error"),
        }
    }

    #[test]
    fn test_key_generator_validate_key_too_long() {
        let key_gen = KeyGenerator::new().with_max_key_length(10);
        let result = key_gen.validate_key("this_key_is_way_too_long");
        assert!(result.is_err());
        let err = result.unwrap_err();
        match err {
            crate::error::OxCacheError::InvalidInput(msg) => {
                assert!(msg.contains("maximum length"))
            }
            _ => panic!("Expected InvalidInput error"),
        }
    }

    #[test]
    fn test_key_generator_validate_key_invalid_chars() {
        let key_gen = KeyGenerator::new();
        // Space is not in VALID_KEY_CHARS
        let result = key_gen.validate_key("key with spaces");
        assert!(result.is_err());
        // Null byte
        let result = key_gen.validate_key("key\0null");
        assert!(result.is_err());
        // Newline
        let result = key_gen.validate_key("key\nnewline");
        assert!(result.is_err());
    }

    #[test]
    fn test_key_generator_apply_prefix_empty() {
        let key_gen = KeyGenerator::new();
        assert_eq!(key_gen.apply_prefix("key"), "key");
    }

    #[test]
    fn test_key_generator_apply_prefix_nonempty() {
        let key_gen = KeyGenerator::with_prefix("cache:");
        assert_eq!(key_gen.apply_prefix("key"), "cache:key");
    }

    // ============================================================================
    // try_generate_full 测试
    // ============================================================================

    #[test]
    fn test_try_generate_full_valid_key() {
        let key_gen = KeyGenerator::new().with_namespace("app");
        let result = key_gen.try_generate_full("user:{id}", &[("id", "123")]);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), "app:user:123");
    }

    #[test]
    fn test_try_generate_full_rejects_invalid_chars() {
        let key_gen = KeyGenerator::new();
        // Space is not in VALID_KEY_CHARS
        let result = key_gen.try_generate_full("user:{name}", &[("name", "hello world")]);
        assert!(result.is_err());
    }

    #[test]
    fn test_try_generate_full_rejects_empty_key() {
        let key_gen = KeyGenerator::new();
        let result = key_gen.try_generate_full("{empty}", &[("empty", "")]);
        assert!(result.is_err());
    }

    #[test]
    fn test_try_generate_full_rejects_too_long() {
        let key_gen = KeyGenerator::new().with_max_key_length(10);
        let result = key_gen.try_generate_full("user:{id}", &[("id", "this_is_way_too_long")]);
        assert!(result.is_err());
    }

    // ============================================================================
    // json_hash_key 测试（integrity 门控）
    // ============================================================================

    #[cfg(feature = "integrity")]
    mod json_hash_key_tests {
        use super::*;
        use serde_json::json;

        #[test]
        fn deterministic_and_order_independent() {
            let key_gen = KeyGenerator::new();
            let a = key_gen
                .json_hash_key(&["resp", "v1"], &json!({"b": 1, "a": [1, 2]}))
                .unwrap();
            let b = key_gen
                .json_hash_key(&["resp", "v1"], &json!({"a": [1, 2], "b": 1}))
                .unwrap();
            assert_eq!(a, b);
            assert!(a.starts_with("resp:v1:"));
            // sha256 hex 摘要段固定 64 字符
            assert_eq!(a.len(), "resp:v1:".len() + 64);
        }

        #[test]
        fn body_change_changes_key() {
            let key_gen = KeyGenerator::new();
            let a = key_gen.json_hash_key(&["k"], &json!({"v": 1})).unwrap();
            let b = key_gen.json_hash_key(&["k"], &json!({"v": 2})).unwrap();
            assert_ne!(a, b);
        }

        #[test]
        fn namespace_and_prefix_wrap_hash_key() {
            let key_gen = KeyGenerator::new()
                .with_prefix_str("cache:")
                .with_namespace("app");
            let key = key_gen.json_hash_key(&["resp"], &json!({"v": 1})).unwrap();
            assert!(key.starts_with("app:cache:resp:"));
        }

        #[test]
        fn long_body_yields_fixed_length_key() {
            let key_gen = KeyGenerator::new();
            let big = json!({"data": "x".repeat(10_000)});
            let key = key_gen.json_hash_key(&["k"], &big).unwrap();
            assert!(key.len() < 256);
        }

        #[test]
        fn invalid_parts_char_rejected() {
            let key_gen = KeyGenerator::new();
            let result = key_gen.json_hash_key(&["bad part"], &json!({}));
            match result {
                Err(OxCacheError::InvalidInput(msg)) => {
                    assert!(msg.contains("invalid character"))
                }
                other => panic!("Expected InvalidInput error, got {other:?}"),
            }
        }

        #[test]
        fn empty_parts_yields_hash_only_key() {
            let key_gen = KeyGenerator::new();
            let key = key_gen.json_hash_key(&[], &json!(null)).unwrap();
            assert_eq!(key.len(), 64);
        }

        #[test]
        fn parts_containing_segment_separator_rejected() {
            let key_gen = KeyGenerator::new();
            let body = json!({"v": 1});
            // ["user:admin"] 与 ["user", "admin"] 若都放行会别名到同一键
            let err = key_gen.json_hash_key(&["user:admin"], &body).unwrap_err();
            match err {
                OxCacheError::InvalidInput(msg) => {
                    assert!(msg.contains("':'"))
                }
                other => panic!("Expected InvalidInput error, got {other:?}"),
            }
            // 等价拆分可以正常工作
            assert!(key_gen.json_hash_key(&["user", "admin"], &body).is_ok());
        }
    }
}