# 🏗️ Garrison 架构设计文档
> Garrison 是面向 Rust 生态的身份认证鉴权框架。
>
> - 版本:0.9.0-rc.4(发布候选,2026-10-20:会话 key SHA-256 摘要化 + DAO 原子契约修复(set_if_absent / MySQL ensure_table)+ vacuum_expired 原语 + 限流后端 Redis 落地 + v1.0 门禁仓库侧产物 / Cookie 安全默认收紧)
> - 运行时:tokio 1.x
> - Web 适配:axum 0.8 / actix-web 4 / warp 0.4
> - 存储:dbnexus 0.6(SQLite / PostgreSQL / MySQL + auto-migrate;`migrations/duckdb/` 保留四方言迁移文件,但 garrison 无 `db-duckdb` feature,`src/` 内不存在 DuckDB 代码路径,用户无法选择该后端)+ Repository 层(13 trait + `Dbnexus*Repository` 实现,tenant_id 隔离)。例外与补口:`app_user_identifier`(登录标识防重)以 `(id_type, id_value)` 为全局主键,租户维度经 `find_owner_in_tenant` 租户作用域回查——注册唯一约束冲突时同租户返回 `Taken { by_user_id }`、命中他租户行返回中性 `Registered`(不泄露他租户 user_id);找回密码(`account-password-reset`)签发 token 时写入 code-tenant 绑定,reset 校验请求租户与签发租户一致(绑定缺失 fail-closed 拒绝)
> - 缓存:oxcache 0.5(L1 内存 + L2 redis,per-entry TTL + ttl_sync 查询)
> - License:Apache-2.0
> 配置相关字段说明详见 [⚙️ 配置指南](./CONFIGURATION.md);开发规范详见 [🛠️ 开发规范](./DEVELOPMENT.md)。
## 📋 目录
- [架构概览](#-架构概览)
- [模块划分](#-模块划分)
- [关键 trait 关系图](#-关键-trait-关系图)
- [数据流:请求处理链路](#-数据流请求处理链路)
- [设计决策](#-设计决策)
---
## 🎯 架构概览
Garrison 采用 **双抽象层 + 全局单例** 架构,核心设计目标:
1. 业务代码只面向 trait 编程,存储后端可平滑替换;
2. 启动时一次性注入依赖,运行期零状态调用,业务代码通过 `GarrisonManager` 静态 API 即可使用。
### 1.1 双抽象层
- **DAO 抽象层**:`GarrisonDao` trait 屏蔽存储后端差异,底层由 `dbnexus`(数据库)+ `oxcache`(缓存)实现,切换 SQLite / PostgreSQL / MySQL / DuckDB 时上层无需改动。
- **缓存抽象层**:`oxcache` 0.5 提供 L1(oxcache 内存层)+ L2(redis 分布式)两级缓存,支持 per-entry TTL 精细化过期控制,对上层呈现统一 `get / set / remove` 语义。
### 1.2 全局单例
- `GarrisonManager` 通过 `arc_swap::ArcSwapOption` 持有 `Arc<GarrisonLogicDefault>`(读路径无锁,v0.8.1 从 `parking_lot::RwLock` 迁移;v0.5.2 起 `GarrisonLogic` trait 拆分为 `GarrisonCore` base trait + 5 个子 trait:`SessionLogic` / `PermissionLogic` / `TokenLogic` / `MfaLogic` / `PasswordLogic`),启动时调用 `GarrisonManager::builder().build().await` 一次性注入 dao / config / interface。
- `GarrisonLogicFactoryEntry` 通过 `inventory::submit!` 在编译期注册,运行时由 `inventory::iter` 选取默认实现。
- `GarrisonUtil` 暴露静态方法(`login` / `check_login` / `logout` 等),内部全部委托 `GARRISON_MANAGER` 单例,业务侧零状态调用。
### 1.3 双模会话
Garrison 同时维护两种会话维度:
- **Account-Session**:以 `login_id` 为 key,存储账号级长生命周期数据(角色、权限、用户画像)。
- **Token-Session**:以 `token` 为 key,存储该次登录的临时数据(设备、登录时间、临时授权)。
由 `is_share` / `is_concurrent` 配置控制多端共享与并发登录策略。
---
## 🧩 模块划分
Garrison 分为四层模块,由 feature flag 控制编译裁剪:
<div align="center">
<img src="assets/module-layers.svg" alt="模块分层" width="800">
</div>
```mermaid
graph TB
subgraph CoreLayer["核心模块(always on)"]
core[core<br/>token / permission / auth]
stp[stp<br/>GarrisonCore + 5 个子 trait / GarrisonUtil]
session[session<br/>GarrisonSession]
config[config<br/>GarrisonConfig]
context[context<br/>task_local 上下文]
dao[dao<br/>GarrisonDao trait]
strategy[strategy<br/>GarrisonPermissionStrategy]
manager[manager<br/>GarrisonManager 单例]
annotation[annotation<br/>注解枚举]
router[router<br/>GarrisonRouter]
json[json<br/>JSON 模板]
exception[exception<br/>异常类型]
plugin[plugin<br/>插件 trait]
account[account<br/>凭证 / 密码策略 / 锁定 / 认证流]
listener[listener<br/>事件监听器]
error[error<br/>GarrisonError]
health[health<br/>健康检查]
state[state<br/>运行时状态]
i18n[i18n<br/>国际化基础层]
constants[constants<br/>常量定义]
prelude[prelude<br/>预导入]
end
subgraph ProtocolLayer["协议层(feature 门控)"]
protocol-jwt[protocol-jwt]
oauth2[protocol-oauth2]
sso[protocol-sso]
sign[protocol-sign]
apikey[protocol-apikey]
temp[protocol-temp]
oidc[protocol-oidc<br/>0.4.0 新增]
scope-handler[oauth2-scope-handler<br/>0.4.0 新增]
sso-server[protocol-sso-server<br/>0.4.0 新增]
end
subgraph ExtensionLayer["扩展层(feature 门控,0.4.0 新增)"]
alone-cache[alone-cache<br/>多实例隔离]
parameter-query[parameter-query<br/>参数化查询]
end
subgraph SecureLayer["安全层(feature 门控)"]
secure-totp[secure-totp]
secure-sign[secure-sign]
httpbasic[protocol-httpbasic]
httpdigest[protocol-httpdigest]
sms[sms-rate-limit]
email[email-verification]
confusable[secure-confusable]
masking[secure-masking]
sanitize[secure-sanitize]
xss[secure-xss]
end
subgraph InfraLayer["基础设施"]
oxcache[oxcache 0.5<br/>L1 内存 + L2 redis]
dbnexus[dbnexus 0.6<br/>SQLite / PostgreSQL / MySQL + auto-migrate]
sdforge[sdforge 0.5<br/>声明式路由]
trait-kit[trait-kit 0.5<br/>typestate DI]
end
subgraph ServerLayer["服务器层(feature 门控)"]
auth-server[auth-server<br/>独立认证服务器]
oauth2-server[oauth2-server<br/>OAuth2 授权服务器]
grpc[grpc<br/>gRPC 拦截器]
backend-remote[backend-remote<br/>远程后端]
end
subgraph WebLayer["Web 安全层(feature 门控)"]
web-axum[web-axum<br/>axum 适配]
web-actix[web-actix<br/>actix-web 适配]
web-warp[web-warp<br/>warp 适配]
waf[firewall-waf<br/>WAF]
cors[web-cors<br/>CORS]
csrf[web-csrf<br/>CSRF]
end
subgraph Observable["可观测性(feature 门控)"]
listener-events[listener<br/>事件监听]
metrics[metrics-prometheus<br/>Prometheus 指标]
tracing[tracing-log<br/>结构化日志]
otlp[otlp<br/>OTLP 分布式追踪]
end
CoreLayer --> InfraLayer
ProtocolLayer --> CoreLayer
ExtensionLayer --> CoreLayer
SecureLayer --> CoreLayer
Observable --> CoreLayer
ServerLayer --> CoreLayer
ServerLayer --> InfraLayer
WebLayer --> CoreLayer
```
### 2.1 核心模块(always on,无 feature flag)
| 模块 | 职责 |
|------|------|
| `core/` | 核心层:`core/token`(Token 生成校验)、`core/permission`(权限校验)、`core/auth`(登录鉴权) |
| `stp/` | `GarrisonCore` + 5 个子 trait(`SessionLogic` / `PermissionLogic` / `TokenLogic` / `MfaLogic` / `PasswordLogic`)+ `GarrisonInterface` trait + `GarrisonUtil` 静态门面 |
| `session/` | `GarrisonSession` 会话模型(Account + Token 双模) |
| `config/` | `GarrisonConfig` 全局配置 + 热更新 |
| `context/` | `GarrisonContext` 请求上下文抽象 + axum 适配器 + task_local |
| `dao/` | `GarrisonDao` trait + dbnexus 实现 + 契约测试套件(`dao::testing`,多后端同一把尺子) |
| `strategy/` | `GarrisonPermissionStrategy` 权限策略 |
| `manager/` | `GarrisonManager` 全局单例 + inventory 编译期注册 |
| `annotation/` | 鉴权注解枚举 |
| `router/` | `GarrisonRouter` + Interceptor 路由拦截 |
| `json/` | JSON 模板与序列化抽象 |
| `exception/` | 框架异常类型 |
| `plugin/` | `GarrisonPlugin` trait 与编译期注册 |
### 2.2 协议层(feature 门控,默认关闭)
| 模块 | Feature | 说明 | 引入版本 |
|------|---------|------|---------|
| `protocol/jwt` | `protocol-jwt` | JWT 签发与验证(HS256/384/512、RS256/384/512、ES256/384、EdDSA + refresh) | 0.2.0 |
| `protocol/oauth2` | `protocol-oauth2` | OAuth2 四种模式(授权码 / 客户端凭证 / 密码 / RefreshToken) | 0.2.0(0.4.0 扩展 RefreshToken) |
| `protocol/sso` | `protocol-sso` | SSO 单点登录 ticket(一次性 60s TTL) | 0.2.0 |
| `protocol/sign` | `protocol-sign` | API 签名 + nonce 防重放 | 0.2.0 |
| `protocol/apikey` | `protocol-apikey` | API Key 认证(生成/校验/吊销/轮换) | 0.2.0 |
| `protocol/temp` | `protocol-temp` | 临时凭证(issue/get/revoke/consume) | 0.2.0 |
| `protocol/oauth2/oidc` | `protocol-oidc` | OIDC id_token 签发/验证 + discovery + 三重防重放(iss/aud/nonce) | 0.4.0 |
| `protocol/oauth2/scope` | `oauth2-scope-handler` | `ScopeHandler` trait + `ScopeRegistry` 注册表,OAuth2Client 委托校验 | 0.4.0 |
| `protocol/sso/server` | `protocol-sso-server` | `SsoServer` trait + `CenterIdConverter` + `SsoChannel` + `DefaultSsoServer` | 0.4.0 |
| `protocol/sso/saml` | `protocol-sso` | SAML 2.0 骨架:`SamlProvider` trait + `DefaultSamlProvider`(quick-xml 解析) | 0.6.0 |
| `protocol/sso/oidc` | `protocol-sso` | OIDC RP 骨架:`OidcProvider` trait + `DefaultOidcProvider`(discovery + token exchange) | 0.6.0 |
| `protocol/sso/channel` | `cache-redis` + `protocol-sso-server` | `RedisPubSubSsoChannel`:Redis pub/sub 跨实例 SsoChannel 实现 | 0.6.0 |
### 2.3 扩展层(feature 门控,默认关闭,0.4.0 新增)
| 模块 | Feature | 说明 |
|------|---------|------|
| `dao/alone_cache` | `alone-cache` | `AloneCache` 装饰器(实现 GarrisonDao,key_prefix 隔离)+ `AloneCacheManager`(多实例管理) |
| `stp/parameter` | `parameter-query` | `ParameterQuery` trait + `ParameterQueryBuilder`(链式 with_login_id/with_device/with_token + async check_permission/check_role) |
### 2.4 安全层(feature 门控,默认关闭)
| 模块 | Feature | 说明 |
|------|---------|------|
| `secure/totp` | `secure-totp` | TOTP 动态验证码(RFC 6238) |
| `secure/sign` | `secure-sign` | HMAC 签名工具 |
| `secure/httpbasic` | `protocol-httpbasic` | HTTP Basic 认证 |
| `secure/httpdigest` | `protocol-httpdigest` | HTTP Digest 认证 |
| `secure/sms` | `sms-rate-limit` | SMS 验证码限速 |
| `secure/email` | `email-verification` | 邮箱验证码(限速 + 异常检测;`email-verification-smtp` 提供内置 SMTP 发送) |
| `secure/confusable` | `secure-confusable` | Unicode 同形异义字检测 |
| `secure/masking` | `secure-masking` | 敏感数据脱敏(regex 真实脱敏) |
| `secure/sanitize` | `secure-sanitize` | 通用输入消毒 |
| `secure/xss` | `secure-xss` | XSS 防护 |
---
### MFA/step-up 编排基座(stp::mfa)
MFA 编排的核心抽象与数据流:
- **因子账本**:会话内嵌 `AmrEntry{method, aal, completed_at}` 列表 + `auth_time`(主认证时刻)。登录播种 `pwd`/aal 1;step-up 完成 Required Action 后按 `(method, aal)` 升级。签发 token 时账本映射 RFC 8176 `amr` claim(完成顺序去重)与 OIDC `auth_time` claim。
- **chain 三态**:`mfa.global_chain` 全局默认;`per_client_chains` 键缺失回退全局、空数组显式禁用、非空强制集合。chain 引用未知 factor 启动期 fail-closed。
- **Required Action 三段式**:`evaluate`(新鲜度断言:`auth_time`/账本 AAL 过期 → 触发)→ `challenge`(产出客户端动作载荷)→ `process`(验证后升级账本)。TOTP 与 WebAuthn(经 R07 仪式 + 注册表)各一实现。
- **恢复码**:verify 与 consume 分离;consume 经 DAO `compare_and_swap` 原子置已用(防 verify-consume 间竞态双花);误用豁免计数 `recovery_misuse_tolerance`(默认 0)超限锁定 fail-closed。
- **MFA remember cookie**:HMAC 绑定(stage + credential_id + exp),经 R01 cookie 单一构建点产出;有效 cookie 跳过重复 challenge,跨 credential 不通用。
### Back-Channel Logout 投递链路(backchannel-logout)
登出→RP 通知的完整链路(对齐 OIDC Back-Channel Logout 1.0):
1. **签发**(`backchannel::token`):logout token 复用 protocol/jwt 密钥材料,仅含 `sub`/可选 `sid` 与 `events` 声明(`http://schemas.openid.net/event/backchannel-logout`),不携带身份资料。
2. **入队**(`backchannel::listener`):`GarrisonEvent::Logout` 触发,逐 RP 写入 `oauth2_backchannel_queue`。两档派发语义——事务内登出经 `GarrisonEventTx::on_commit` 缓冲(与业务写同生共死,回滚不入队);auto-commit 登出路径走 Immediately 档。
3. **投递**(`backchannel::deliver`):后台任务按 `next_attempt_at` 批量 drain(batch 32),向 RP 端点 POST `logout_token`;单 RP 超时 5s、禁止跟随重定向(防 POST 降 GET 丢 token);失败重试计数递增 + 指数退避,超 MaxTtl(24h)置 `failed` 并 warn 显性化。
架构取舍:RP 端点由部署方按 client 配置(不做 RP discovery fetch,不做推送订阅管理面)——投递保障的边界是「持久化 + 有界重试 + 显性失败」,非「必达」。
## 🔗 关键 trait 关系图
Garrison 的核心抽象通过 trait 解耦,业务方实现 trait 即可接入:
<div align="center">
<img src="assets/architecture-overview.svg" alt="架构总览" width="800">
</div>
```mermaid
graph LR
BC[GarrisonCore<br/>base trait]
SL[SessionLogic<br/>会话逻辑 trait]
PL[PermissionLogic<br/>权限逻辑 trait]
TL[TokenLogic<br/>Token 逻辑 trait]
ML[MfaLogic<br/>MFA 逻辑 trait]
PWL[PasswordLogic<br/>密码逻辑 trait]
BI[GarrisonInterface<br/>业务数据源 trait]
BD[GarrisonDao<br/>持久化抽象 trait]
BS[GarrisonSession<br/>会话模型]
BCtx[GarrisonContext<br/>请求上下文 trait]
BFS[GarrisonPermissionStrategy<br/>权限策略 trait]
BM[GarrisonManager<br/>全局单例]
BU[GarrisonUtil<br/>静态门面]
BU --> BM
BM --> BLD[GarrisonLogicDefault<br/>聚合实现]
BLD --> BC
SL --> BC
PL --> SL
TL --> SL
ML --> SL
PWL --> SL
BLD --> BS
BLD --> BFS
BLD --> BCtx
BS --> BD
BLD --> BI
BD --> oxcache[oxcache 0.5<br/>L1 内存 + L2 redis]
BD --> dbnexus[dbnexus 0.6<br/>SQLite / PostgreSQL / MySQL]
```
### trait 职责说明
| trait | 职责 | 默认实现 |
|-------|------|---------|
| `GarrisonCore` | base trait(1 方法) | `GarrisonLogicDefault` |
| `SessionLogic` | 会话逻辑:登录、登出、校验、kickout(13 方法,继承 GarrisonCore) | `GarrisonLogicDefault` |
| `PermissionLogic` | 权限逻辑:check_permission / check_role / has_permission / has_role / get_permission_list / get_role_list(6 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `TokenLogic` | Token 逻辑:check_access_token / check_client_token / check_temp_token / verify_token / refresh_token(5 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `MfaLogic` | MFA 逻辑:二级认证与账号禁用校验(6 async 方法 + 2 关联函数,继承 SessionLogic) | `GarrisonLogicDefault` |
| `PasswordLogic` | 密码逻辑:login_with_password(1 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `GarrisonInterface` | 业务数据源接入点:查询用户权限、角色等 | 业务方必须实现 |
| `GarrisonDao` | 持久化抽象:session CRUD、token 映射 + `RedisDeploymentMode` 配置 | dbnexus + oxcache 实现 |
| `GarrisonContext` | 请求上下文:读取当前 token、请求头、Cookie | axum adapter 实现 |
| `GarrisonPermissionStrategy` | 权限策略:`check_permission` 判定 | 框架提供默认实现 |
| `SessionExpiryListener` | 会话过期回调:会话过期时触发异步回调(0.6.0 新增) | 框架提供默认实现 |
> 所有 trait 采用 **trait + Default 模式**:框架提供默认实现,业务方可覆盖。任何组件都可被替换为自定义实现,框架默认实现仅在未被覆盖时生效。
---
## 🔄 数据流:请求处理链路
以 axum 集成为例,一个受保护请求的完整处理链路:
<div align="center">
<img src="assets/request-flow.svg" alt="请求处理流程" width="800">
</div>
```mermaid
sequenceDiagram
participant C as Client
participant AX as axum middleware
participant TL as task_local CURRENT_TOKEN
participant BU as GarrisonUtil
participant BM as GarrisonManager
participant BL as GarrisonLogicDefault
participant BS as GarrisonSession
participant BD as GarrisonDao
participant OC as oxcache (L1 内存 + L2 redis)
participant DB as dbnexus (SQLite / PostgreSQL / MySQL / DuckDB)
C->>AX: HTTP 请求 (Header/Cookie: garrison_token)
AX->>TL: 提取 token, CURRENT_TOKEN.scope(token, fut)
AX->>BU: GarrisonUtil::check_login()
BU->>BM: 委托 GARRISON_MANAGER.logic()
BM->>BL: logic.check_login()
BL->>TL: current_token() 读取 token
TL-->>BL: Some(token)
BL->>BS: session.get_token_session(token)
BS->>BD: dao.get_session(token)
BD->>OC: L1 内存命中?
alt L1 命中
OC-->>BD: 命中返回
else L1 未命中
BD->>OC: L2 redis 查询
OC-->>BD: 返回数据
BD->>OC: 回填 L1 (per-entry TTL)
end
BD-->>BS: TokenSession
BS-->>BL: 会话数据
BL->>BL: 校验超时 / 活跃超时 / 并发策略
alt 校验通过
BL-->>BM: Ok(())
BM-->>BU: Ok
BU-->>AX: 通过
AX-->>C: 200 业务响应
else 校验失败
BL-->>BM: Err(GarrisonError::NotLogin)
BM-->>BU: Err
BU-->>AX: Err 抛出
AX-->>C: 401 / 异常 JSON
end
```
---
## 💡 设计决策
### 1. 为什么用 inventory 编译期注册?
**问题**:Rust 无反射,无法在运行时枚举 trait 实现并自动选择。若用运行时注册,需要全局可变状态与锁,增加启动复杂度。
**方案**:
- 使用 `inventory::submit!` 宏在编译期把 `GarrisonLogicFactoryEntry` 注册到全局 link list。
- `GarrisonManager::builder().build().await` 启动时遍历 `inventory::iter::<GarrisonLogicFactoryEntry>()`,按 `name` 选定默认实现。
- 优点:**无反射、无运行时开销、跨 crate 注册**,与 feature flag 配合实现按需启用。
### 2. 为什么用 task_local 上下文?
**问题**:async 请求级 token 在 `Arc<dyn GarrisonLogic>` 中无法通过参数传递(trait 方法签名固定),若用 thread_local 则跨 `.await` 不安全。
**方案**:
- `context` 模块定义 `CURRENT_TOKEN: tokio::task_local`。
- axum middleware 在请求入口提取 token 后 `CURRENT_TOKEN.scope(token, fut)` 设置。
- `GarrisonUtil::current_token()` 通过 `CURRENT_TOKEN.get()` 取值,自动落到当前请求作用域。
- 优点:无锁、无穿透、跨 `.await` 安全。
### 3. 为什么用 trait + Default 模式?
**问题**:框架需要提供「开箱即用」的默认行为,同时允许业务方按需替换任一组件。
**方案**:
- 所有核心抽象(`GarrisonCore` + 5 个子 trait / `GarrisonDao` / `GarrisonContext` / `GarrisonPermissionStrategy` / `GarrisonListener`)均以 trait 定义。
- 框架提供默认实现,业务方实现 trait 后通过 `GarrisonManager::builder().build().await` 注入即可覆盖。
- 优点:扩展点清晰,符合 Rust 的零成本抽象哲学。
### 4. 为什么用双抽象层(DAO + 缓存)?
**问题**:存储后端多样(SQLite/PostgreSQL/MySQL/DuckDB/Redis),缓存策略多变,业务代码不应感知具体后端。
**方案**:
- `GarrisonDao` trait 定义统一接口(`get_session` / `set_session` / `delete_token` 等),底层由 dbnexus + oxcache 实现。
- `oxcache` 作为缓存抽象,L1 为 oxcache 内存层 LRU,L2 为 redis 分布式,per-entry TTL 精细控制。
- 切换存储后端时仅替换 `GarrisonLogicFactoryEntry` 的实现,**上层零改动**。
### 5. 为什么用 feature 门控?
**问题**:协议/安全/可观测层并非所有项目都需要,强行全量编译会带来依赖膨胀。
**方案**:
- 13 个特性域独立编译,通过 `#[cfg(feature = "...")]` 在编译期裁剪。
- 默认 `default = ["backend-embedded"]`(仅启用嵌入式后端),`development` 可一键启用常用组合(cache-memory + db-sqlite + web-axum)。
- 聚合特性 `full` / `production` / `development` 一键启用一组特性。
---
### 6. 为什么 Set-Cookie 收敛单一构建点(`context::cookie`)?
全部 Set-Cookie 写路径(axum / actix / warp 适配器的 `set_cookie*`、axum 续签中间件、CSRF 中间件)统一经 `context::cookie::build_set_cookie_value` 产出,写点不再自行拼接属性串。设计吸收 Keycloak `DefaultCookieProvider.set(CookieType, …)` 的类型化 Cookie 与 Pocket-ID 的 `__Host-` / `__Secure-` 前缀命名,按纯函数自由构建器重设计(无框架依赖,可脱离 HTTP 单测):
- **不变式集中强制,写点无法绕过**:HttpOnly 恒定(`CookieScope` 封闭枚举)、SameSite 白名单 fail-fast(合法值与 `COOKIE_SAME_SITE_VALUES` 一一对应,跨引用测试锁定漂移)、非 Secure 上下文 `None→Lax` 降级(warn 一次)、`production` + Secure 上下文强制 `__Host-`/`__Secure-` 前缀、name/value 注入校验(复用 `validate_cookie_name_value`)+ path/domain 字符纪律(path 拒 `;` 与控制字符,domain 仅主机名字符)。
- **写读同名**:读侧统一入口 `token_cookie_name`(及 CSRF / `CookieType::resolved_name`)与写侧经同一前缀解析,杜绝「写带前缀、读裸名」的功能破坏。
- **名称来自配置**:garrison 的 cookie 名来自配置(`token_name` / CSRF `cookie_name`)而非硬编码枚举,故 `CookieType` 为可构造 pub struct + 便捷构造器(`token(config)` / `session(name, config)`),而非 Keycloak 式硬编码注册表。
- **确定性信号**:写路径无请求上下文可感知 UA / `X-Forwarded-Proto`,以 `config.cookie_secure=false` 作为「非 Secure 上下文」的确定性信号;协议头探测列为后续独立增强,不混入构建点。
### 7. 为什么事件派发分 Immediately / OnCommit 两档(事务绑定)?
**问题**:garrison 既有 DAO 全部经 `Session::connection()` 走 auto-commit 路径,「业务写库 + 广播事件」是两个独立动作——写库成功后事件若丢失(或反向),业务表与事件审计链不一致。
**方案**(`listener` + 任一 db 后端 feature,`GarrisonEventTx` 位于 `dao` 模块):
- **Immediately 档**(`GarrisonListenerManager::broadcast`):事件产生即派发,不与事务绑定;listener 失败仅 warn,适用于可容忍丢失的旁路事件。
- **OnCommit 档**(`GarrisonEventTx` + `broadcast_after_commit`):`begin` 从 `DbPool` 获取独立 `Session` 开启事务,SQL 经 guard `execute`(`Session::execute_raw` 的 in-tx 路由)写入,事件缓冲在 guard 中;`commit(mut self)` 成功后按 FIFO 派发并返回 `DispatchOutcome { dispatched, failed }`(listener `Err`/panic 计入 `failed`,审计链缺口显性化)。
- **事务 guard 生命周期**:`commit` / `rollback` 消耗 `self`(「提交后不可再用」在类型层面表达);rollback、未 commit 即 drop、commit 失败、或 commit 成功后派发中途被取消(tokio 超时 / 任务中止)时缓冲事件(或剩余事件)均不派发(`Drop` 兜底 warn 丢弃条数与事件类型摘要,按 uncommitted / commit-failed / dispatch-cancelled 丢弃原因区分,显性化,取消场景携带已派发/总数;打开事务依赖 dbnexus 级联回滚)。
- **事务路由边界**:经 guard `execute` 的 SQL **加入本事务**;既有 DAO / Repository 经 `session.connection()` 的 SQL **不加入**(auto-commit),混用时由调用方保证顺序。`execute` 走 admin 特权直通通道(dbnexus 对 admin 角色跳过全部表级权限检查、SQL 解析失败同样放行),SQL 内容即权限边界——禁止拼接不可信输入。
「登录日志 SQL 写 + `Login` 事件」是两档机制的典型装配目标(后续接线),当前仅交付机制,不强切既有 37 处 `broadcast` 调用点。
## 六、扩展点
### 1. 自定义 GarrisonDao 实现
替换存储后端(如 PostgreSQL / MongoDB / 自研存储):
```rust
#[async_trait]
impl GarrisonDao for MyDao {
async fn get_session(&self, key: &str) -> GarrisonResult<Option<SessionData>> {
// 自定义查询逻辑
}
// ...
}
```
通过 `GarrisonManager::builder().build().await` 注入即可,上层业务代码零改动。
启用 `testing` feature 后,自定义实现可用契约测试套件验证行为契约
(原子性 / TTL / glob 等,与内置后端同一把尺子):
```rust
garrison::dao_conformance_tests! {
backend: my_dao,
make: || async { MyDao::new().await.map(|d| Arc::new(d) as Arc<dyn GarrisonDao>) },
caps: [basic, atomic],
}
```
能力层与断言内容见 [API_REFERENCE.md](API_REFERENCE.md) `dao::testing` 节。
### 2. 自定义 GarrisonLogicFactoryEntry
替换核心逻辑(如自定义 token 生成规则、自定义登录策略):
```rust
inventory::submit! {
GarrisonLogicFactoryEntry {
name: "my-logic",
factory: || Arc::new(MyLogic) as Arc<GarrisonLogicDefault>,
}
}
```
### 3. 自定义 GarrisonPermissionStrategy
替换权限策略(如基于 ABAC、基于外部策略引擎):
```rust
#[async_trait]
impl GarrisonPermissionStrategy for MyStrategy {
async fn check_permission(&self, login_id: &str, permission: &str) -> GarrisonResult<bool> {
// 自定义权限判定
Ok(/* ... */ true)
}
}
```
---
## 📚 相关文档
| 文档 | 说明 |
|------|------|
| [⚙️ 配置指南](./CONFIGURATION.md) | 完整配置项参考 |
| [🛠️ 开发规范](./DEVELOPMENT.md) | TDD 工作流与代码规范 |
| [🗺️ 路线图](./ROADMAP.md) | 版本演进规划 |
| [🚀 部署指南](./DEPLOYMENT.md) | 生产部署注意事项 |
- 早期领域建模参考
- specmark specs:`specmark/specs/*`