garrison 0.9.0

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

//! FlowRegistry inventory 注册:认证流程的编译期注册(`inventory::submit!`)与运行期查询/追加。
//!
//! [`FlowRegistry::from_inventory`] 收集所有 [`FlowRegistration`] 注册项构造查询表;
//! [`FlowRegistry::register`] 可在运行期追加自定义 flow,同名覆盖默认值。

use super::AuthenticationFlow;
use std::collections::HashMap;

/// 认证流程编译期注册项(经 `inventory::submit! { FlowRegistration { name, flow } }` 注册)。
pub struct FlowRegistration {
    /// 流程名称(静态字符串)。
    pub name: &'static str,
    /// 流程构造函数(无参数,返回 [`AuthenticationFlow`])。
    pub flow: fn() -> AuthenticationFlow,
}

inventory::collect!(FlowRegistration);

/// 认证流程注册表:持 `name → AuthenticationFlow` 映射,支持编译期 inventory 收集与运行期追加。
pub struct FlowRegistry {
    /// 流程映射表。
    flows: HashMap<String, AuthenticationFlow>,
}

impl FlowRegistry {
    /// 从 `inventory` 收集所有编译期注册项构造注册表(对每项调用 `flow()` 并以 `name` 为 key 插入)。
    pub fn from_inventory() -> Self {
        let mut flows = HashMap::new();
        for registration in inventory::iter::<FlowRegistration> {
            let flow = (registration.flow)();
            flows.insert(flow.name.clone(), flow);
        }
        Self { flows }
    }

    /// 按名称查询流程,返回 `Option<&AuthenticationFlow>`。
    pub fn get(&self, name: &str) -> Option<&AuthenticationFlow> {
        self.flows.get(name)
    }

    /// 运行期注册流程(以 `flow.name` 为 key);同名覆盖已有值(运行期覆盖编译期默认值)。
    pub fn register(&mut self, flow: AuthenticationFlow) {
        self.flows.insert(flow.name.clone(), flow);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::account::authflow::FlowBuilder;

    /// 测试用编译期注册 flow(用于验证 from_inventory 收集)。
    fn test_registry_flow() -> AuthenticationFlow {
        FlowBuilder::new("test-registry-flow")
            .login("password")
            .build()
    }

    inventory::submit! {
        FlowRegistration {
            name: "test-registry-flow",
            flow: test_registry_flow,
        }
    }

    /// inventory 注册:FlowRegistration 通过 submit! 注册后可被 from_inventory 收集。
    #[test]
    fn inventory_registration_works() {
        let registry = FlowRegistry::from_inventory();
        assert!(registry.get("test-registry-flow").is_some());
    }

    /// from_inventory 收集所有注册 flow。
    #[test]
    fn from_inventory_collects_flows() {
        let registry = FlowRegistry::from_inventory();
        let flow = registry.get("test-registry-flow");
        assert!(flow.is_some());
        let flow = flow.unwrap();
        assert_eq!(flow.name, "test-registry-flow");
        assert_eq!(flow.steps.len(), 1);
    }

    /// get 查询:存在返回 Some,不存在返回 None。
    #[test]
    fn get_returns_none_for_unknown() {
        let registry = FlowRegistry::from_inventory();
        assert!(registry.get("non-existent-flow").is_none());
    }

    /// register 运行期追加 flow 后可被 get 查询。
    #[test]
    fn register_appends_flow() {
        let mut registry = FlowRegistry::from_inventory();
        let custom = FlowBuilder::new("custom-runtime-flow")
            .login("password")
            .mfa(Some("totp"))
            .build();
        registry.register(custom);
        assert!(registry.get("custom-runtime-flow").is_some());
        let flow = registry.get("custom-runtime-flow").unwrap();
        assert_eq!(flow.steps.len(), 2);
    }

    /// 重复注册:register 同名 flow 覆盖旧值。
    #[test]
    fn register_overrides_existing() {
        let mut registry = FlowRegistry::from_inventory();

        let original = FlowBuilder::new("override-target")
            .login("password")
            .build();
        registry.register(original);
        assert_eq!(registry.get("override-target").unwrap().steps.len(), 1);

        let replacement = FlowBuilder::new("override-target")
            .login("password")
            .mfa(Some("totp"))
            .social("wechat")
            .build();
        registry.register(replacement);
        let flow = registry.get("override-target").unwrap();
        assert_eq!(flow.steps.len(), 3);
    }

    /// from_inventory 返回的 registry 初始包含所有编译期注册项。
    #[test]
    fn from_inventory_initial_state() {
        let registry = FlowRegistry::from_inventory();
        // 至少包含本模块注册的 test-registry-flow
        assert!(registry.get("test-registry-flow").is_some());
    }
}