garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! Credit 计量配置。
//!
//! 提供 `CreditConfig`(主配置)与 `CreditAlertConfig`(告警配置)。

use serde::{Deserialize, Serialize};

use super::cycle::CreditCycle;
use super::schedule::CreditSchedule;

/// Credit 计量配置。
///
/// 控制 credit 计量引擎的行为:配额上限、周期模式、资源权重、告警阈值。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreditConfig {
    /// 每租户每月 credit 配额(0 = 不限制)。
    pub credit_limit: u64,
    /// 配额周期模式。
    pub cycle: CreditCycle,
    /// 资源权重表。
    pub schedule: CreditSchedule,
    /// 多级告警阈值(百分比,如 [80, 90, 100]),必须升序排列。
    pub alert_thresholds: Vec<u8>,
    /// 是否启用 SQL 流水持久化(false = 仅 KV 热数据)。
    pub persist_history: bool,
}

impl Default for CreditConfig {
    fn default() -> Self {
        Self {
            credit_limit: 10_000,
            cycle: CreditCycle::Fixed { day_of_month: 1 },
            schedule: CreditSchedule::default(),
            alert_thresholds: vec![80, 90, 100],
            persist_history: false,
        }
    }
}

impl CreditConfig {
    /// 校验配置合法性。
    ///
    /// `alert_thresholds` 必须非空(空阈值表会静默禁用所有告警)、每项 ∈ [0, 100]
    /// 且严格升序;[`CreditAlertConfig`] 作为告警配置时同规则。
    pub fn validate(&self) -> Result<(), String> {
        validate_thresholds(&self.alert_thresholds, "credit-alert-thresholds")
    }
}

/// Credit 告警配置。
///
/// 独立于 `CreditConfig`,允许复用告警策略。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreditAlertConfig {
    /// 多级告警阈值(百分比,如 [80, 90, 100]),必须升序排列。
    pub thresholds: Vec<u8>,
    /// 同一阈值的最小触发间隔(秒),避免重复广播。
    pub cooldown_seconds: u64,
}

impl CreditAlertConfig {
    /// 校验告警配置合法性(阈值规则与 [`CreditConfig::validate`] 同源)。
    ///
    /// `thresholds` 必须非空(空阈值表会静默禁用所有告警)、每项 ∈ [0, 100] 且严格升序。
    pub fn validate(&self) -> Result<(), String> {
        validate_thresholds(&self.thresholds, "credit-alert-thresholds")
    }
}

/// 告警阈值表的共享校验(`CreditConfig` 与 `CreditAlertConfig` 同源)。
///
/// `prefix` 用于错误消息前缀,便于定位来自哪个配置结构。
fn validate_thresholds(thresholds: &[u8], prefix: &str) -> Result<(), String> {
    if thresholds.is_empty() {
        return Err(format!("{}-empty::", prefix));
    }
    for (i, &t) in thresholds.iter().enumerate() {
        if t > 100 {
            return Err(format!("{}-range::{}::{}", prefix, i, t));
        }
        if i > 0 && t <= thresholds[i - 1] {
            return Err(format!(
                "{}-order::[{}]={}::[{}]={}",
                prefix,
                i,
                t,
                i - 1,
                thresholds[i - 1]
            ));
        }
    }
    Ok(())
}

impl Default for CreditAlertConfig {
    fn default() -> Self {
        Self {
            thresholds: vec![80, 90, 100],
            cooldown_seconds: 3600,
        }
    }
}

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

    /// CreditConfig::default() 各字段取默认值。
    #[test]
    fn test_credit_config_default_values() {
        let config = CreditConfig::default();
        assert_eq!(config.credit_limit, 10_000);
        assert_eq!(config.cycle, CreditCycle::Fixed { day_of_month: 1 });
        assert_eq!(config.schedule.default_weight(), 1);
        assert_eq!(config.alert_thresholds, vec![80, 90, 100]);
        assert!(!config.persist_history);
    }

    /// validate() 对合法配置返回 Ok(含边界值 0 与 100)。
    #[test]
    fn test_validate_ok_with_boundary_values() {
        let config = CreditConfig {
            alert_thresholds: vec![0, 50, 100],
            ..CreditConfig::default()
        };
        assert!(config.validate().is_ok(), "0 与 100 均在合法范围");
    }

    /// validate() 对空 alert_thresholds 返回 Err。
    #[test]
    fn test_validate_empty_thresholds_err() {
        let config = CreditConfig {
            alert_thresholds: vec![],
            ..CreditConfig::default()
        };
        let err = config.validate().unwrap_err();
        assert!(
            err.contains("credit-alert-thresholds-empty"),
            "实际错误: {}",
            err
        );
    }

    /// validate() 对超过 100 的阈值返回 Err(>100 边界)。
    #[test]
    fn test_validate_threshold_over_100_err() {
        let config = CreditConfig {
            alert_thresholds: vec![50, 101],
            ..CreditConfig::default()
        };
        let err = config.validate().unwrap_err();
        assert!(
            err.contains("credit-alert-thresholds-range") && err.contains("101"),
            "实际错误: {}",
            err
        );
    }

    /// validate() 对相等阈值(非严格升序)返回 Err。
    #[test]
    fn test_validate_equal_thresholds_err() {
        let config = CreditConfig {
            alert_thresholds: vec![80, 80],
            ..CreditConfig::default()
        };
        let err = config.validate().unwrap_err();
        assert!(
            err.contains("credit-alert-thresholds-order"),
            "实际错误: {}",
            err
        );
    }

    /// validate() 对降序阈值返回 Err。
    #[test]
    fn test_validate_descending_thresholds_err() {
        let config = CreditConfig {
            alert_thresholds: vec![90, 80],
            ..CreditConfig::default()
        };
        let err = config.validate().unwrap_err();
        assert!(
            err.contains("credit-alert-thresholds-order"),
            "实际错误: {}",
            err
        );
    }

    /// validate() 对默认阈值 [80, 90, 100] 返回 Ok。
    #[test]
    fn test_validate_default_config_ok() {
        assert!(CreditConfig::default().validate().is_ok());
    }

    /// CreditAlertConfig::validate 对合法阈值返回 Ok。
    #[test]
    fn test_alert_config_validate_ok() {
        let alert = CreditAlertConfig {
            thresholds: vec![10, 50, 100],
            cooldown_seconds: 60,
        };
        assert!(alert.validate().is_ok());
    }

    /// CreditAlertConfig::validate 拒绝空 thresholds(空表会静默禁用所有告警)。
    #[test]
    fn test_alert_config_validate_empty_err() {
        let alert = CreditAlertConfig {
            thresholds: vec![],
            cooldown_seconds: 60,
        };
        let err = alert.validate().unwrap_err();
        assert!(
            err.contains("credit-alert-thresholds-empty"),
            "实际错误: {}",
            err
        );
    }

    /// CreditAlertConfig::validate 拒绝越界与乱序阈值。
    #[test]
    fn test_alert_config_validate_range_and_order_err() {
        let over = CreditAlertConfig {
            thresholds: vec![50, 101],
            cooldown_seconds: 60,
        };
        assert!(over
            .validate()
            .unwrap_err()
            .contains("credit-alert-thresholds-range"));

        let unsorted = CreditAlertConfig {
            thresholds: vec![90, 80],
            cooldown_seconds: 60,
        };
        assert!(unsorted
            .validate()
            .unwrap_err()
            .contains("credit-alert-thresholds-order"));
    }

    /// CreditConfig serde 往返(TOML)保持字段一致。
    #[test]
    fn test_credit_config_serde_roundtrip() {
        let mut schedule = CreditSchedule::with_default(2).unwrap();
        schedule.insert("sms", 5).unwrap();
        let config = CreditConfig {
            credit_limit: u64::MAX,
            cycle: CreditCycle::Rolling { days: 7 },
            schedule,
            alert_thresholds: vec![10, 20],
            persist_history: true,
        };
        let serialized = toml::to_string(&config).unwrap();
        let deserialized: CreditConfig = toml::from_str(&serialized).unwrap();
        assert_eq!(deserialized.credit_limit, u64::MAX);
        assert_eq!(deserialized.cycle, CreditCycle::Rolling { days: 7 });
        assert_eq!(deserialized.schedule.weight_for("sms"), 5);
        assert_eq!(deserialized.alert_thresholds, vec![10, 20]);
        assert!(deserialized.persist_history);
    }

    /// CreditAlertConfig::default() 各字段取默认值。
    #[test]
    fn test_credit_alert_config_default_values() {
        let alert = CreditAlertConfig::default();
        assert_eq!(alert.thresholds, vec![80, 90, 100]);
        assert_eq!(alert.cooldown_seconds, 3600);
    }

    /// CreditAlertConfig serde 往返(TOML)保持字段一致。
    #[test]
    fn test_credit_alert_config_serde_roundtrip() {
        let alert = CreditAlertConfig {
            thresholds: vec![50],
            cooldown_seconds: 0,
        };
        let serialized = toml::to_string(&alert).unwrap();
        let deserialized: CreditAlertConfig = toml::from_str(&serialized).unwrap();
        assert_eq!(deserialized.thresholds, vec![50]);
        assert_eq!(deserialized.cooldown_seconds, 0);
    }

    /// CreditConfig 的 Debug 输出包含类型名。
    #[test]
    fn test_credit_config_debug() {
        let debug = format!("{:?}", CreditConfig::default());
        assert!(debug.contains("CreditConfig"), "实际: {}", debug);
    }

    /// CreditAlertConfig 的 Debug 输出包含类型名。
    #[test]
    fn test_credit_alert_config_debug() {
        let debug = format!("{:?}", CreditAlertConfig::default());
        assert!(debug.contains("CreditAlertConfig"), "实际: {}", debug);
    }
}