1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
//! Copyright (c) 2026 Kirky.X. All rights reserved.
//! See LICENSE for full license text.
//! 路由模块,提供路由器与拦截器抽象。
//!
//! 对应 路由拦截器(`SaInterceptor`),
//! 适配 axum Web 框架的路由层。
//!
//! ## 设计
//!
//! - `GarrisonInterceptor` trait:预处理 hook,根据 annotation 调用 `GarrisonUtil`
//! - `DefaultGarrisonInterceptor`:默认实现,根据 annotation 变体调用对应 API
//! - `GarrisonRouter`:包装 `axum::Router`,提供 `route_protected` 语法糖(cfg `web-axum`)
//! - `GarrisonLayer` middleware:自动从 header/cookie 提取 token + 设置 task_local
use crateAnnotation;
use crateGarrisonResult;
use async_trait;
// ============================================================================
// GarrisonInterceptor trait(always compiled,prelude 重导出依赖)
// ============================================================================
/// 拦截器 trait,定义请求预处理抽象。
///
/// 对应 `SaInterceptor`,根据 annotation 执行鉴权逻辑。
///
/// 实现方在 `pre_handle` 中根据 annotation 调用 `GarrisonUtil::check_login` 等方法。
/// middleware 在执行 handler 前调用此方法,返回 `Err` 时短路返回错误响应。
// ============================================================================
// DefaultGarrisonInterceptor(always compiled)
// ============================================================================
/// 默认拦截器实现,根据 annotation 变体调用对应 `GarrisonUtil` 方法。
///
/// # 注解处理方式
///
/// **直接鉴权(6 个)**:
/// - `CheckLogin` → `GarrisonUtil::check_login()`(未登录返回 `NotLogin`)
/// - `CheckRole(r)` → `GarrisonUtil::check_role(r)`
/// - `CheckPermission(p)` → `GarrisonUtil::check_permission(p)`
/// - `CheckSafe` → `GarrisonUtil::check_safe()`(0.3.0 二级认证)
/// - `CheckDisable` → `GarrisonUtil::check_disable()`(0.3.0 账号禁用)
/// - `CheckApiKey { namespace }` → `GarrisonUtil::check_api_key(namespace)`(0.6.1 API Key 校验)
///
/// **NotImplemented(3 个)**:依赖 HTTP 请求上下文(Authorization header / method / body),
/// 而 `pre_handle` 签名仅有 `path + annotation`,无法获取。Fail Loud(Rule 12)返回
/// `GarrisonError::NotImplemented`,引导用户改用 axum extractor 或 secure 模块直接调用:
/// - `CheckBasicAuth` → 使用 `secure::httpbasic::HttpBasicAuth` 或 axum extractor
/// - `CheckDigestAuth` → 使用 `secure::httpdigest::HttpDigestAuth` 或 axum extractor
/// - `CheckSign` → 使用 `protocol::sign::SignHandler` 或 axum extractor
///
/// **直接放行(no-op)**:
/// - `Ignore` / 逻辑组合注解(`CheckOr` / `CheckAnd` / `CheckNot` / `Mode`)→ no-op
/// (组合逻辑由注解处理器在编译期或路由配置层处理;`Mode` 是配置注解非直接检查)
;
// ============================================================================
// GarrisonRouter(cfg feature = "web-axum")
// ============================================================================
pub use GarrisonRouter;
/// 无 `web-axum` feature 时的占位类型(维持 prelude 重导出可用)。
;
/// 租户解析 middleware 的 re-export。
///
/// 仅在 `web-axum` + `tenant-isolation` 双 feature 启用时可用。
pub use tenant_resolution_middleware;