limiteron 0.3.0-rc.7

中文 | English

Rust 统一流量控制框架

✨ 功能特性 • 🚀 快速开始 • 📚 文档 • 💻 示例 • 🤝 参与贡献

---

🚦 统一流量控制

一个 Governor 入口，多维限流与纵深管控协同决策：

---

📋 目录

• ✨ 功能特性
• 🚀 快速开始
• 🎨 特性标志
• 📚 文档
• 💻 示例
• 🏗️ 架构
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 开发路线图
• 🤝 参与贡献
• 📋 更新日志
• 📄 许可证
• 🙏 致谢
• 📞 联系与支持
• ⭐ Star 历史

---

✨ 功能特性

• 决策链（DecisionChain）：按优先级级联执行多条规则，支持短路（src/decision_chain/）
• 标识符匹配：IP、用户 ID、设备 ID、API Key、地理位置（MaxMindDB）、设备信息（woothee）、自定义匹配器（src/matchers/）
• L1 负缓存：仅缓存拒绝/封禁决策，命中不绕过限流与封禁语义（src/l1_cache.rs）
• 分布式限流：DistributedLimiter trait + 内存实现 + Redis Lua 实现（distributed + lua-script）
• 批量 API：批量决策检查、批量令牌预取（BatchTokenPrefetcher）
• 热更新：POST /api/v1/config 原子换配置、配置文件监听（config-watcher）、confers 集成热重载
• 事件系统：EventEmitter / EventDispatcher、Transactional Outbox、Webhook 外发签名
• 探针端点：/healthz、/readyz、/metrics（bypass 认证）
• 国际化：ICU4X locale 感知格式化（i18n）
• 限流预检：Limiter::peek(cost) / remaining() 非消费查询与 IETF RateLimit-* 头数据

---

🚀 快速开始

📦 安装

cargo add limiteron

环境要求：Rust 1.97.1+（见 rust-toolchain.toml）。默认特性为空（default = []），核心限流零外部存储依赖；需要持久化时启用存储特性：

[dependencies]
limiteron = { version = "0.3.0-rc.7", features = ["macros"] }

💡 最小可运行示例

以下示例来自 examples/src/bin/simple_rate_limit.rs，演示最基本的令牌桶限流：

use limiteron::limiters::{Limiter, TokenBucketLimiter};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 容量 10，每秒补充 1 个令牌
    let limiter = TokenBucketLimiter::new(10, 1);

    for i in 0..15 {
        match limiter.allow(1).await {
            Ok(true) => println!("请求 {} 允许", i),
            Ok(false) => println!("请求 {} 被限流", i),
            Err(e) => println!("请求 {} 错误: {:?}", i, e),
        }
    }
    Ok(())
}

运行方式：

cargo run -p limiteron-examples --bin simple_rate_limit

声明式宏（macros 特性，摘自现有示例风格）：

use limiteron::flow_control;

#[flow_control(rate = "100/s", quota = "10000/m", concurrency = 50)]
async fn api_handler(user_id: &str) -> Result<String, limiteron::error::LimiteronError> {
    Ok(format!("处理用户 {} 的请求", user_id))
}

🧭 核心概念

• Governor：主控制器（src/governor.rs），输入 RequestContext，输出 Decision
• FlowControlConfig：version / global / rules 三层配置，支持文件加载与环境变量覆盖（ConfigLoader::load_from_file_with_env）
• Decision：三态结果 Allowed / Rejected / Banned（src/error/mod.rs）
• DecisionChain：按优先级级联执行的责任链，节点即 Limiter（src/decision_chain/）
• 存储抽象：Storage / BanStorage / QuotaStorage（src/storage/），内存实现开箱即用，dbnexus 适配器提供 PostgreSQL / SQLite / MySQL（SQLite 为嵌入式方言：create_schema 按 连接后端自动选择建表 DDL）
• 插件系统：Plugin trait（on_admit / on_reject / on_degrade 决策生命周期钩子）+ PluginRegistry 编译期注册制（src/plugins/）；分发顺序即注册顺序，插件 panic 隔离计数不反向影响限流裁决；动态 .so 明确不做（ABI 无稳定性 + 供应链攻击面，见模块文档安全边界）；内置 LoggingPlugin / CounterPlugin 示例
• 自适应阈值限流：AdaptiveThresholdLimiter（src/limiters/adaptive_threshold.rs）——滑动观测窗口错误率/p95 延迟驱动动态配额（统计启发式非 ML），阈值/步长/冷却期全显式配置

---

🎨 特性标志

Limiteron 默认不启用任何可选功能（default = []），按需组合。以下内容逐项对应 Cargo.toml 的 [features] 段：

特性预设

预设	说明	启用的特性
minimal	核心限流，无外部存储依赖	无
standard	核心功能（封禁 / 配额 / 熔断）	ban-manager、quota-control、circuit-breaker
full	除存储后端外的全部功能（不含 cli）	38 项特性，见 Cargo.toml

注：preset 均不含存储后端，持久化需自行叠加 sqlite / postgres / mysql（dbnexus 驱动互斥，一次构建只能叠加一个）。

⚠️ 文件型 SQLite 部署提示：dbnexus 建立连接时未启用 WAL（根因在 dbnexus 的 create_connection，属外部依赖）。文件库在并发读写场景建议让连接 URL 显式携带 journal_mode=WAL（如 sqlite:data/limiteron.db?journal_mode=WAL，StorageFactoryConfig::sqlite 的 path 原样拼接进连接 URL），否则写并发下可能遭遇 database is locked。

⚠️ 存储驱动互斥：postgres / sqlite / mysql 均走 dbnexus，嵌入式与服务端驱动不可共存于同一构建，请勿使用 --all-features，应使用显式特性组合。

---

📚 文档

文档	说明
📖 用户指南	从安装、核心概念到进阶用法与故障排除的完整教程
📘 API 参考	全部公开 API 的详细说明
🏗️ 架构文档	设计理念、模块划分与扩展机制
❓ FAQ	常见问题解答与故障排除
🧪 测试指南	测试分类、运行命令与覆盖率说明
📈 基准测试规程	cargo bench 口径、基线刷新时机与 criterion 对比用法
🧬 测试场景固化	测试金字塔基线与 E2E 场景定义
📈 覆盖率报告	历史基线数据（v0.1.0 时期生成，待 CI 覆盖率更新）
🔒 安全文档	安全设计、版本支持策略与漏洞报告流程
📋 更新日志	每个版本的变更记录
🤝 贡献指南	如何参与项目开发
📦 docs.rs 在线文档	自动生成的最新 API 文档
📦 crates.io	发布页面

---

💻 示例

examples/ 是 workspace 内的独立子 crate（limiteron-examples），含 21 个可运行示例。运行需要 feature 的示例时先启用对应特性：

cargo run -p limiteron-examples --bin simple_rate_limit
cargo run -p limiteron-examples --features "ban-manager,admin-api" --bin ban_http_api

示例	说明
simple_rate_limit	最基本的令牌桶限流使用方式
rate_limiters	七种限流算法：令牌桶、分片滑动窗口、固定窗口、并发限制器、漏桶、滑动窗口日志、GCRA
macro_usage	flow_control 宏的使用方式与当前版本的限制
governor_demo	Governor 三种构造模式、请求检查、决策解析与统计信息
matchers_demo	标识符提取器、请求上下文与规则匹配器的完整使用流程
decision_chain	责任链决策：组合多个限流器、按优先级执行、支持短路
custom_matchers	自定义匹配器 trait 实现、注册表与内置 Header（前缀/相等）/ Method / TimeWindow / RegexPath（regex-matching 特性）匹配器
authorization_demo	授权提供者 trait 实现与内置 SimpleAuthorizationProvider
graceful_shutdown	监听 Ctrl+C 并调用 Governor::shutdown() 幂等优雅关闭
circuit_breaker	熔断器：故障检测、熔断打开、半开恢复探测与超时恢复
quota_control	配额消费跟踪、限额执行与用量百分比计算
ban_manager	IP / 用户 ID / MAC 目标的封禁创建、查询、更新与移除
ban_file_loader	从 YAML 加载封禁规则并支持文件变更热重载
ban_http_api	启动 AdminServer 并通过 HTTP 调用封禁管理端点
validation_demo	统一验证模块：IP、用户 ID、MAC、API Key、封禁目标校验
storage_factory	通过 StorageFactory 从 DSN 创建 Postgres / MySQL / SQLite 后端
fallback_demo	降级策略管理器：策略配置、故障注入、降级执行与孤岛模式
audit_log_demo	审计日志：事件记录、配置、统计与签名验证
tower_middleware	将 Governor 流量控制集成到 Tower Service 处理链
telemetry_demo	Prometheus 指标采集与 OpenTelemetry 分布式追踪
device_geo_matching	User-Agent 解析、设备识别、IP 地理查询与地理条件匹配

---

🏗️ 架构

Limiteron 采用分层架构：接入层（Tower 中间件、Admin API）将流量交给 Governor 主控制器，经 matchers 提取标识符并匹配规则后，沿规则各自的 decision_chain 决策链级联执行 limiters 限流算法；封禁、配额、熔断、降级作为领域组件参与决策；状态经 storage 抽象落地（默认内存，生产可切换 dbnexus 的 PostgreSQL / SQLite / MySQL 持久化）。

整体架构图、核心决策时序、模块职责表、存储后端清单与扩展机制见架构文档。

---

🎯 核心决策流程

一次 Governor::check(context) 的完整决策路径（提炼自 src/governor.rs）：标识符提取与规则匹配（只计算一次）→ L1 负缓存查询（fail-closed，仅缓存拒绝/封禁决策）→ 按优先级级联执行各规则决策链（任一规则拒绝即拒绝，全部允许才放行）→ 发射限流事件并返回 Allowed / Rejected / Banned。

完整决策时序图与逐条关键语义（含 parallel-checker 下封禁检查先于缓存读取的语义）见架构文档。

---

🔗 生态与集成

Limiteron 与同工作区的兄弟 crate 深度协作，均通过 feature 显式启用、默认不引入：

集成	特性	说明
dbnexus	postgres / sqlite / mysql	数据库抽象层，提供持久化存储适配器与指标传递
oxcache	cache-service / cache-redis / lua-script / ban-sync	统一缓存服务、Redis 缓存后端、Lua 执行、Pub/Sub 封禁广播
trait-kit	kit	LimiteronModule 模块化接入 + 健康/生命周期端口
inklog	inklog	结构化日志（console/file/database sinks），含 SinkRateLimit 限流端口
confers	config-confers / config-confers-reload	配置源加载与热重载（验证失败自动回滚）

另通过 i18n 特性集成 ICU4X 提供 locale 感知格式化。

工作区成员 integrations/limiteron-sdforge 反向提供防护层：limiteron 侧把限流/熔断/封禁以 Guard 三态判定面暴露给 sdforge 应用（该 crate 自身的 sdforge 特性下适配为 ForgeRateLimiter），与 sdforge 侧既有消费适配方向相反、发布节奏独立。

工作区成员 integrations/limiteron-dbnexus 为 dbnexus 提供限流端口适配：实现 dbnexus 0.6.0-rc.6 抽出的 dbnexus-limiter-port 端口（Limiter::check(key)），内部经 LimiterManager per-key 令牌桶判定（deny 携带 Retry-After，后端故障显性上报，fail-open/closed 由消费方决定）——dbnexus 应用在组合根经 RateLimitBackend::External 注入；与 sdforge 桥接同款不发布 crates.io、发布节奏随 limiteron 主仓。

---

🧪 测试

测试策略矩阵（单元 / 集成与端到端 / 属性 / 文档 / 基准五层）与运行命令（与 CI 一致，含覆盖率门禁）见测试指南，分层基线与 E2E 场景定义见测试场景固化。

测试规模（按 #[test] / #[tokio::test] 属性 grep 统计（grep -rEc '#\[(tokio::)?test\b' --include='*.rs'），截至 v0.3.0-rc.7）：

统计项	数量
库内测试函数（src/）	2,489（#[test] 1,551 + #[tokio::test] 938）
外部测试函数（tests/）	607（#[test] 158 + #[tokio::test] 449）
宏 crate 测试（macros/）	47（#[test]）
集成适配 crate 测试（integrations/）	21（#[test] 5 + #[tokio::test] 16）
属性测试组（proptest）	4

---

📊 性能

说明：下表为 2026-01-19（v0.1.0 时期）的实测数据，口径早于 criterion 基准接入——harness = false 缺失导致基线直到 2026-09-30 才首次真实产出（见基准规程）。下表数字保留作为历史对照，当前可复现基线请以 docs/BENCHMARKS.md 的命令与同机复测结果为准。

吞吐量

限流器	实测	目标	达成
TokenBucket	12M+ ops/s	500K ops/s	✅ 24x
FixedWindow	20M+ ops/s	300K ops/s	✅ 66x
ConcurrencyLimiter	12M+ ops/s	200K ops/s	✅ 60x

延迟

分位	TokenBucket	FixedWindow
P50	< 100ns	< 100ns
P95	< 200ns	< 150ns
P99	< 1µs	< 500ns

历史实测数据（口径早于基准设施口径统一，仅供量级参考；现行口径为 fresh 实例放行路径，见 benches/throughput.rs 口径说明）：

TokenBucket: 12,088,759 ops/s
FixedWindow: 19,920,188 ops/s
ConcurrencyLimiter: 11,891,237 ops/s
并发测试：数据一致性 100%，限流正确性 1000/1000

基准设施：仓库自带四组 criterion 基准（均需 full 特性），用于复现与回归检测：

基准	文件	内容
吞吐量	benches/throughput.rs	单线程/并发吞吐量与扩展曲线
延迟	benches/latency.rs	P50/P90/P99/P99.9 延迟测量与操作对比
内存	benches/memory.rs	键规模内存占用、数据结构对比、泄漏检测
回归	benches/regression.rs	历史基准存储与自动对比告警

cargo bench --features full
# 注意：[[bench]] 已设置 harness = false（criterion 0.8 要求），缺失时 bench 落入 libtest 空跑

---

🔒 安全

漏洞报告：请勿通过公开 issue 报告安全漏洞，请使用 GitHub Security Advisories 私密披露通道（"Report a vulnerability"）。维护者承诺 48 小时内确认、7 天内给出初步评估，采用协调披露。完整流程见 SECURITY.md。

安全设计要点（均可在源码与安全文档中对应）：

• 输入防线 — 租户 / 环境标识符消毒（转义 : 防命名空间前缀注入，src/tenant/config.rs）；IP / 用户 ID / MAC 格式校验（src/validation.rs）
• 算法边界 — 令牌桶时间差与补充使用饱和运算封顶；配额窗口内置时钟回退防护
• Admin 自保护 — 管理端点自身限流 + 分桶内存上限 + 多 key 令牌认证与 admin/viewer 角色矩阵（RBAC）
• 只读 Web UI 无认证警示 — admin-ui 内嵌单页仅发起 GET 且经机械守卫（路由表全 GET + 只读投影类型窄化，src/admin/web.rs）；默认绑定 127.0.0.1 且无认证——改为非回环地址会将管理快照暴露给同网段，必须前置带认证的反向代理（服务启动时对非回环绑定发出 warn 日志）
• 数据保护 — secrecy 保护敏感数据、日志脱敏（log-redaction）、审计事件 HMAC-SHA256 链式签名与篡改检测
• 传输防线 — 可信代理 X-Forwarded-For 提取；Webhook 外发签名 + 时间戳防重放 + URL 校验（SSRF）
• 供应链 — rustls-webpki 最低版本锁（CVE-2025-48369）；cargo-deny 校验漏洞/许可证/重复依赖；CI Security 任务与 pre-push 钩子运行 cargo deny check 与 cargo audit

---

🗺️ 开发路线图

---

🤝 参与贡献

欢迎任何形式的贡献！开发环境、TDD 工作流、代码规范与 PR 流程详见贡献指南。

🐛 报告问题

发现了 Bug？ 创建 Issue

💡 功能建议

有好想法？ 发起讨论

🔧 提交代码

想参与开发？ Fork & PR

Rust 1.97.1（rust-toolchain.toml 统一锁定）；lefthook / pre-commit 钩子覆盖 fmt、clippy、供应链检查、私钥扫描与覆盖率门禁。环境搭建、钩子明细与提交规范全文见贡献指南。

---

📋 更新日志

完整变更记录见 CHANGELOG.md。近期版本要点：

• 0.3.0-rc.7（2026-09-28）— ManualCircuitBreaker 手动熔断、capacity-dial 六档容量调光、tower-middleware 拒绝响应工厂与 keyed 快速路径、RetryPolicy 重试前回调、QuotaLimiter 超限窗口查询、manager feature 拆分与非 panic 路径；【安全】CodeQL 明文日志四项收敛（governor 日志脱敏/长度指纹/入口字段降记）；limiters/quota/distributed/governor/resilience 算法与韧性修复；文档一致性门禁
• 0.3.0-rc.5（2026-09-21）— 维护性发布：新增 retry 组件（RetryPolicy 指数退避）与 i18n 整改，无破坏面
• 0.3.0-rc.4（2026-09-14，含原 rc.3 批次）— 多租户贯穿 Governor、CIDR 网段封禁、Admin RBAC、OTLP 追踪导出、MySQL 存储、HTB 分层令牌桶、舱壁隔离、AIMD 自适应限流、limiteron-cli、Webhook 签名、事件 Outbox、封禁跨实例同步（0.3.0-rc.3 版本号跳过未发布，内容随本版发布）
• 0.3.0-rc.2（2026-09-03）— 文档同步至 0.3 线、workspace 依赖路径本地化、Cargo.lock 纳入版本控制
• 0.2.10（2026-07-22）— 新增 76 个边界与异常场景测试、sea-orm 升级至 2.0 稳定版、清理未使用依赖

---

📄 许可证

本项目基于 MIT + Commons Clause 许可证发布，商业使用需单独授权。详见 LICENSE。Copyright (c) 2026 Kirky.X🌠。

---

🙏 致谢

• 🌟 依赖项目 — 本项目构建在这些优秀的项目之上：
  • tokio — 异步运行时
  • dbnexus — 数据库抽象层
  • oxcache — 统一缓存服务
  • trait-kit — trait 集成模块
  • inklog — 结构化日志
  • dashmap — 并发 HashMap
• 👥 贡献者 — 感谢所有贡献者！
• 💬 社区 — 特别感谢社区成员的支持

---

📞 联系与支持

• 🐛 Issues — 报告 Bug 与问题
• 💬 Discussions — 提问与交流想法
• 📦 GitHub 仓库 — 查看源代码
• 🤝 维护者：Kirky.X

---

⭐ Star 历史

💝 支持本项目

如果您觉得这个项目有用，请考虑给它一个 ⭐️！

Built with ❤️ by Kirky.X