Skip to main content

Crate garrison

Crate garrison 

Source
Expand description

Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text.

§Garrison

Garrison 是一个面向 Rust 生态的一站式身份认证鉴权框架。

§快速开始

最小可用示例:初始化管理器 → 执行登录 → 校验登录状态。

ⓘ
use std::sync::Arc;
use garrison::prelude::*;

// 1. 准备依赖(业务方实现 GarrisonDao / GarrisonInterface)
let dao: Arc<dyn GarrisonDao> = /* oxcache / dbnexus 实现 */;
let config = Arc::new(GarrisonConfig::default_config());
let interface: Arc<dyn GarrisonInterface> = Arc::new(MyInterface);

// 2. 初始化全局管理器(覆盖式注入 dao / config / interface)
GarrisonManager::init(dao, config, interface).unwrap();

// 3. 执行登录:生成 token 并写入会话
//    注意:login / check_login 依赖 task_local 上下文中的当前 token,
//    通常由 web 中间件(如 axum middleware)设置。
let token = GarrisonUtil::login(1001).await.unwrap();

// 4. 校验登录状态
let logged_in = GarrisonUtil::check_login().await.unwrap();
assert!(logged_in);

§特性

Garrison 通过 Cargo feature flags 控制各能力域的编译:

类别Feature说明
默认default空(按需启用所需 feature;all-defaults 可一键启用常用组合)
缓存cache-memory / cache-redis基于 oxcache 0.3 的 L1(内存) + L2(redis),均启用 oxcache(语义别名)
数据库db-sqlite基于 dbnexus 0.2 + auto-migrate
Web 框架web-axum / web-actix / web-warp路由拦截器与 extractor 适配
协议层protocol-jwt / protocol-oauth2 / protocol-sso / protocol-sign / protocol-apikey / protocol-temp鉴权协议插件
安全模块secure-totp / secure-sign / secure-httpbasic / secure-httpdigestTOTP / 签名 / Basic / Digest
可观测性listener / tracing-log / metrics-prometheus事件监听 / 日志 / 指标
聚合full / production / development一键启用一组特性

§模块概览

0.2.0 在 0.1.0 基础上扩展了协议层、安全模块与可插拔扩展点:

  • 核心扩展(always on)
    • core::token:Token trait + TokenStyleFactory(uuid / random_64 / simple / jwt 四种风格)
    • core::auth:AuthLogic trait + DefaultAuthLogic(login_by_token / verify_token / refresh_token)
    • core::permission:PermissionChecker trait + DefaultPermissionChecker
    • plugin:GarrisonPlugin trait + inventory 编译期注册 + GarrisonPluginManager(on_login / on_logout / on_permission_check 钩子)
    • strategy:GarrisonPermissionStrategyDefault 扩展 with_permission_checker / with_role_hierarchy / with_plugin_manager / with_dao(权限缓存)
    • session:GarrisonSession 扩展 SSO / OAuth2 / 临时凭证关联(link_sso_ticket / link_oauth2_token / link_temp_credential)
  • 协议层(特性门控)
    • protocol::jwt:JwtHandler(sign / verify / refresh,HS256/HS512)
    • protocol::oauth2:OAuth2Client(Authorization Code / Client Credentials / Password 三种流程)
    • protocol::sso:SsoClient(ticket 签发 / 校验 / 销毁,一次性 60s TTL)
    • protocol::sign:SignHandler(HMAC-SHA256 签名 + 防重放时间窗口)
    • protocol::apikey:ApiKeyHandler(生成 / 校验 / 吊销 / 轮换)
    • protocol::temp:TempCredentialHandler(issue / get / revoke / consume)
  • 安全模块(特性门控)
    • secure::totp:TotpHandler(RFC 6238,±1 时间窗口偏差)
    • secure::sign:SignVerifier trait
    • secure::httpbasic / secure::httpdigest:HTTP Basic / Digest 认证
  • 可观测性
    • listener:GarrisonEvent + Listener trait + GarrisonListenerManager(Login / Logout / PermissionCheck / Kickout 事件)

§特性域

Garrison 采用 13 个特性域设计:

  • 登录认证 - 基于 Token 的会话管理
  • 权限认证 - RBAC 权限模型
  • Session 会话 - 会话生命周期管理
  • OAuth2 - 第三方授权
  • 单点登录 (SSO) - 跨系统统一登录
  • JWT - JSON Web Token 支持
  • 微服务网关鉴权 - 网关层签名认证
  • API 接口鉴权 - API Key 认证
  • TOTP 动态验证码 - 时间一次性密码
  • Basic 认证 - HTTP Basic Auth
  • Digest 认证 - HTTP Digest Auth
  • 路由拦截鉴权 - Web 框架适配
  • 插件化扩展 - 编译期插件注册

§架构

Garrison 采用双抽象层 + 全局单例的架构:

  • 双抽象层
    • dbnexus:数据库抽象层(SQLite / PostgreSQL / MySQL),由 GarrisonDao trait 屏蔽后端差异
    • oxcache:缓存抽象层(L1 内存 + L2 redis),承载 Token-Session 与 Account-Session
  • GarrisonManager 单例模式

§双抽象层

  • dbnexus - 数据库抽象层(SQLite / PostgreSQL / MySQL)
  • oxcache - 缓存抽象层(L1 内存 + L2 redis)

§使用示例

[dependencies]
garrison = { version = "0.7", features = ["web-axum", "protocol-jwt"] }
use garrison::prelude::*;

// 通过 prelude 引入核心类型
// let _config: GarrisonConfig = GarrisonConfig::default();

Re-exports§

pub use context::tenant::HeaderTenantResolver;
pub use context::tenant::SubdomainTenantResolver;
pub use context::tenant::TenantContext;
pub use context::tenant::TenantResolver;
pub use context::tenant::TenantSource;
pub use context::tenant::TENANT;
pub use context::GarrisonPrincipal;
pub use state::TokenState;
pub use state::UserStatus;
pub use dao::repository::role_hierarchy::RoleHierarchyRecord;
pub use prelude::*;

Modules§

abac
ABAC 策略引擎模块,提供 AbacEngine(基于 Cedar 策略语言)。
account
账号安全引擎模块(吸收 keycloak 安全能力)。
annotation
注解模块,定义鉴权注解枚举。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 注解模块,定义鉴权注解枚举与 axum extractor。
backendbackend-embedded or backend-remote
认证后端抽象模块,提供 AuthBackend trait + BackendEmbedded + BackendRemote。
config
配置模块,提供 GarrisonConfig 全局配置。 Copyright (c) 2024-2026 Kirky.X. All rights reserved. See LICENSE for full license text. 配置模块,提供 GarrisonConfig 全局配置。
constants
常量定义模块,提供 DAO key 前缀等类型安全枚举。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 常量模块,提供框架共享的枚举与常量定义。
context
上下文模块,提供请求/响应/存储上下文抽象。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 上下文模块,提供请求 / 响应 / 存储上下文抽象。
core
核心模块,包含认证、权限、Token 的核心抽象。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 核心模块,包含认证、权限、Token 的核心抽象。
dao
DAO 模块,定义持久化数据访问抽象层。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. DAO 模块,定义持久化数据访问抽象层。
error
错误类型定义模块。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 错误类型定义模块。
exception
异常模块,定义框架异常类型。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 异常模块,定义框架异常类型。
health
健康检查模块,提供 liveness/readiness 探针与依赖项健康检测。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 健康检查模块,提供 liveness/readiness 探针与依赖项健康检测。
i18n
国际化模块,提供异常消息中英文切换(fluent-rs)。
json
JSON 模块,提供 JSON 模板与序列化抽象。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. JSON 模块,提供 JSON 模板与序列化抽象。
manager
管理器模块,提供全局管理器单例。 Copyright (c) 2024-2026 Kirky.X. All rights reserved. See LICENSE for full license text. 管理器模块,提供全局管理器单例与编译期工厂注册。
plugin
插件模块,定义插件 trait 与编译期注册。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 插件模块,定义插件 trait 与编译期注册。
prelude
预导出模块,包含最常用的类型与 trait。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 预导出模块,包含最常用的类型与 trait。
router
路由模块,提供路由器与拦截器抽象。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 路由模块,提供路由器与拦截器抽象。
session
会话模块,提供 GarrisonSession 会话模型。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 会话模块,提供双模会话管理(Account-Session + Token-Session)。
state
状态机模块,定义 Token / User 显式状态机。
stp
Stp 模块,提供 GarrisonLogicDefault / GarrisonInterface / GarrisonUtil + 5 个子 trait。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. Stp 模块,提供核心认证逻辑与工具入口。
strategy
策略模块,提供鉴权策略与防火墙策略。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 策略模块,提供鉴权策略与可插拔权限策略。

Macros§

loc
构造本地化错误文案:优先按 key 查 FTL 翻译,缺失时回退 $fallback 字符串。