garrison 0.9.0

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

//! 熔断器适配器。
//!
//! 包装 limiteron `CircuitBreaker`,为 Garrison `BackendRemote` 提供远程调用熔断保护。
//! 当远程 Auth Server 连续失败达到阈值时,熔断器打开并快速拒绝后续请求(不再发起 HTTP
//! 调用),超时后自动进入半开状态探测恢复。
//!
//! # 设计
//!
//! `CircuitBreakerWrapper` 提供 `execute` 方法,将 Garrison 的异步操作包裹在熔断器逻辑中:
//! - 操作成功 → `on_success`(重置/递增成功计数)
//! - 操作失败 → `on_failure`(通过 `GarrisonErrorClassifier` 判断是否计入失败)
//! - 熔断器打开 → 立即返回 `GarrisonError::Network`(消息带 `circuit-open::` 前缀)
//!
//! # 错误语义(`circuit-open::` 前缀约定)
//!
//! `GarrisonError` 无专用 `CircuitOpen` 变体,熔断打开的快速拒绝映射为
//! `GarrisonError::Network`,以 `circuit-open::` 消息前缀区分:
//! - 调用方不应将 `circuit-open::` 前缀的 Network 错误视作瞬时故障重试
//!   (熔断打开意味着上游已判定不可用,重试应等待半开探测);
//! - 无前缀的 `Network` 错误才是真正的网络层失败,可按常规退避重试。

use crate::error::{GarrisonError, GarrisonResult};
// limiteron 0.3.0-rc.6:ErrorClassifier 更名为泛型 FailureClassifier<E>;Garrison 分类器仍以 LimiteronError 为错误域(execute 前经 to_limiteron_error 映射)。
use limiteron::circuit::{
    CircuitBreaker, CircuitBreakerConfig, CircuitCallError, FailureClassifier,
};
use limiteron::error::LimiteronError;
use std::sync::Arc;

/// Garrison 错误分类器,决定哪些错误应计入熔断器的失败计数。
///
/// 判定体当前与 limiteron `DefaultFailureClassifier` 等价(rc.5 时代即如此),刻意保留自定义
/// 实现:隔离上游默认语义漂移(分类口径变化不影响 garrison 的熔断行为契约),演进需显式过本文件 diff。
#[derive(Debug)]
struct GarrisonErrorClassifier;

impl FailureClassifier<LimiteronError> for GarrisonErrorClassifier {
    fn is_counted_as_failure(&self, error: &LimiteronError) -> bool {
        match error {
            // 存储/网络临时错误 → 算失败
            LimiteronError::StorageError(storage_err) => storage_err.is_transient(),
            // 限流/熔断 → 不算(保护机制本身,不应级联触发)
            LimiteronError::LimitError(_) | LimiteronError::CircuitBreakerError(_) => false,
            // 验证错误 → 不算(客户端问题)
            LimiteronError::ValidationError(_) => false,
            // 其他 → 算失败(保守策略)
            _ => true,
        }
    }
}

/// 将 `GarrisonError` 映射为 `LimiteronError`(供熔断器 `execute` 使用)。
///
/// 客户端错误(`InvalidParam`、`NotFound`、`NotLogin` 等)映射为 `ValidationError`
/// 以便 `GarrisonErrorClassifier` 不计入失败计数(避免客户端错误触发熔断)。
fn to_limiteron_error(e: GarrisonError) -> LimiteronError {
    match &e {
        GarrisonError::Network(msg) => LimiteronError::StorageError(
            limiteron::error::StorageError::ConnectionError(msg.clone()),
        ),
        GarrisonError::Dao(msg) => {
            LimiteronError::StorageError(limiteron::error::StorageError::QueryError(msg.clone()))
        },
        // 客户端错误 → ValidationError(不计入熔断失败计数)
        GarrisonError::InvalidParam(msg)
        | GarrisonError::NotLogin(msg)
        | GarrisonError::NotPermission(msg)
        | GarrisonError::NotRole(msg)
        | GarrisonError::InvalidToken(msg) => LimiteronError::ValidationError(msg.clone()),
        _ => LimiteronError::Other(format!("{}", e)),
    }
}

/// 将 `LimiteronError` 映射回 `GarrisonError`。
///
/// 仅消费 `CircuitCallError::Inner` 携带的原始错误(`to_limiteron_error` 的产物:
/// StorageError/ValidationError/Other);`CircuitBreakerError` / `LimitError` 两臂在
/// rc.6 execute 流中不可达(打开拒绝已独立为 `CircuitCallError::Open`,见
/// [`CircuitBreakerWrapper::execute`]),保留以维持对 `LimiteronError` 的全量映射
/// (防御上游语义变化)。
fn to_garrison_error(e: LimiteronError) -> GarrisonError {
    match &e {
        // 熔断器打开 → 远程服务不可达语义
        LimiteronError::CircuitBreakerError(msg) => {
            GarrisonError::Network(format!("circuit-open::{}", msg))
        },
        LimiteronError::StorageError(limiteron::error::StorageError::ConnectionError(msg)) => {
            GarrisonError::Network(msg.clone())
        },
        LimiteronError::LimitError(msg) => {
            GarrisonError::FirewallBlocked(format!("circuit-limited::{}", msg))
        },
        _ => GarrisonError::Internal(format!("circuit-breaker::{}", e)),
    }
}

/// 熔断器包装器,为 Garrison 远程调用提供熔断保护。
///
/// 内部 `CircuitBreaker` 使用 `Arc<RwLock>` + `AtomicU64`,可安全跨线程共享;`CircuitBreakerWrapper` 可直接放入 `Arc` 在多个 `BackendRemote` 实例间共享。
pub struct CircuitBreakerWrapper {
    inner: CircuitBreaker,
}

impl CircuitBreakerWrapper {
    /// 创建熔断器包装器。
    pub fn new(config: CircuitBreakerConfig) -> Self {
        let config = config.error_classifier(Arc::new(GarrisonErrorClassifier));
        Self {
            inner: CircuitBreaker::new(config),
        }
    }

    /// 在熔断器保护下执行异步操作。
    ///
    /// 熔断器关闭/半开 → 执行 `operation`,根据结果更新状态;熔断器打开 → 立即返回
    /// `GarrisonError::Network`(消息带 `circuit-open::` 前缀,见模块文档「错误语义」;
    /// `GarrisonError` 无专用 `CircuitOpen` 变体)。
    pub async fn execute<F, Fut, T>(&self, operation: F) -> GarrisonResult<T>
    where
        F: FnOnce() -> Fut,
        Fut: std::future::Future<Output = GarrisonResult<T>>,
    {
        self.inner
            .execute(|| async { operation().await.map_err(to_limiteron_error) })
            .await
            .map_err(|call_err| match call_err {
                // limiteron rc.6:熔断打开为独立 variant(闭包未执行),
                // 映射保持 `circuit-open::` 前缀契约(见模块文档「错误语义」)
                CircuitCallError::Open => {
                    GarrisonError::Network("circuit-open::circuit breaker is open".to_string())
                },
                CircuitCallError::Inner(e) => to_garrison_error(e),
            })
    }

    /// 查询熔断器是否打开。
    pub async fn is_open(&self) -> bool {
        self.inner.is_open().await
    }

    /// 查询熔断器当前状态。
    pub async fn state(&self) -> limiteron::error::CircuitState {
        self.inner.get_state().await
    }

    /// 重置熔断器到关闭状态。
    pub async fn reset(&self) {
        self.inner.reset().await;
    }

    /// 获取内部熔断器引用(用于高级用法,如获取统计信息)。
    pub fn inner(&self) -> &CircuitBreaker {
        &self.inner
    }
}

impl std::fmt::Debug for CircuitBreakerWrapper {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CircuitBreakerWrapper")
            .finish_non_exhaustive()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use limiteron::circuit::CircuitBreakerConfig;
    use std::time::Duration;

    fn make_config() -> CircuitBreakerConfig {
        CircuitBreakerConfig::new(3, 2, Duration::from_secs(60))
    }

    /// 初始状态为 Closed。
    #[tokio::test]
    async fn initial_state_closed() {
        let wrapper = CircuitBreakerWrapper::new(make_config());
        assert!(!wrapper.is_open().await);
    }

    /// 成功操作不触发熔断。
    #[tokio::test]
    async fn success_does_not_trip() {
        let wrapper = CircuitBreakerWrapper::new(make_config());
        let result = wrapper
            .execute(|| async { Ok::<_, GarrisonError>(42) })
            .await;
        assert_eq!(result.unwrap(), 42);
        assert!(!wrapper.is_open().await);
    }

    /// Network 错误计入失败计数,达到阈值触发熔断。
    #[tokio::test]
    async fn network_errors_trip_breaker() {
        let wrapper = CircuitBreakerWrapper::new(make_config());

        for _ in 0..3 {
            let _ = wrapper
                .execute(|| async {
                    Err::<(), _>(GarrisonError::Network("connection refused".into()))
                })
                .await;
        }

        assert!(wrapper.is_open().await, "3 次 Network 错误后应熔断");
    }

    /// 熔断器打开后,后续调用立即被拒绝。
    #[tokio::test]
    async fn open_breaker_rejects_immediately() {
        let wrapper = CircuitBreakerWrapper::new(make_config());

        for _ in 0..3 {
            let _ = wrapper
                .execute(|| async { Err::<(), _>(GarrisonError::Network("timeout".into())) })
                .await;
        }
        assert!(wrapper.is_open().await);

        // 即使 operation 会成功,熔断器打开时也应被拒绝
        let result = wrapper
            .execute(|| async { Ok::<_, GarrisonError>(42) })
            .await;
        assert!(result.is_err(), "熔断器打开时应拒绝请求");
        // 核心契约锁定:拒绝错误必须是 `circuit-open::` 前缀的 Network
        // (调用方据此区分熔断拒绝与可重试的瞬时网络错误,见模块文档「错误语义」)
        let err = result.unwrap_err();
        assert!(
            matches!(&err, GarrisonError::Network(m) if m.starts_with("circuit-open::")),
            "熔断拒绝应为 circuit-open:: 前缀的 Network 错误,实际: {err:?}"
        );
    }

    /// InvalidParam 错误不计入失败(客户端错误不应触发熔断)。
    #[tokio::test]
    async fn client_errors_not_counted() {
        let config = CircuitBreakerConfig::new(2, 1, Duration::from_secs(60));
        let wrapper = CircuitBreakerWrapper::new(config);

        for _ in 0..5 {
            let _ = wrapper
                .execute(|| async { Err::<(), _>(GarrisonError::InvalidParam("bad input".into())) })
                .await;
        }

        assert!(!wrapper.is_open().await, "客户端错误不应触发熔断");
    }

    /// reset 恢复熔断器。
    #[tokio::test]
    async fn reset_restores() {
        let wrapper = CircuitBreakerWrapper::new(make_config());

        for _ in 0..3 {
            let _ = wrapper
                .execute(|| async { Err::<(), _>(GarrisonError::Network("err".into())) })
                .await;
        }
        assert!(wrapper.is_open().await);

        wrapper.reset().await;
        assert!(!wrapper.is_open().await);
    }

    /// Debug trait 正常输出。
    #[test]
    fn debug_impl() {
        let wrapper = CircuitBreakerWrapper::new(make_config());
        let debug = format!("{:?}", wrapper);
        assert!(debug.contains("CircuitBreakerWrapper"));
    }
}