English | 中文
中文 | English
Unified Flow Control Framework for Rust
✨ Features • 🚀 Quick Start • 📚 Documentation • 💻 Examples • 🤝 Contributing
One Governor entrypoint where multi-algorithm limiting and layered control decide together:
| 🚦 Multi-Algorithm Limiting token bucket, sliding/fixed window, leaky bucket, sliding window log, concurrency, GCRA, HTB | 🛡️ Layered Control bans, quotas, circuit breaking, fallback on one decision chain | 🔌 Pluggable Foundation in-memory out of the box; persistence via dbnexus, cache via oxcache | 📈 Production Observability Prometheus metrics, OTLP tracing export, HMAC audit chain |
📑 Table of Contents
| 🎯 Rate-limiting algorithm matrix Token bucket, sliding window, sharded sliding window, sliding window log (exact sliding window), fixed window, leaky bucket (water-level meter, dual of token bucket), concurrency control, GCRA, HTB hierarchical token bucket ( src/limiters/) |
🚫 Ban management IP / User / MAC / Geo target bans, CIDR range bans, priority system, YAML bulk loading with hot reload, cross-instance sync ( ban-sync) |
| ⚖️ Quota control Periodic quota allocation, quota alerts, quota overdraw ( src/quota/) |
🧯 Circuit breaking & fallback Automatic failover, state recovery, fallback strategies ( src/circuit/, src/fallback.rs) |
| 🚀 High performance Token bucket at 12M+ ops/s, P99 latency < 1µs (see [Performance](#-performance)) |
🧩 Declarative integration#[flow_control] procedural macro, Tower middleware, Admin REST API, limiteron-cli |
| 🏢 Multi-tenancy tenant+key compound decision keys; cache, bans, and quotas isolated per tenant |
📈 Observability Prometheus metrics, OTLP tracing export, HMAC-SHA256 hash-chained audit log, K8s probe endpoints |
| 🔐 Built-in security Identifier key sanitization, log redaction, signed and replay-protected webhooks, Admin RBAC |
🧠 Decision-chain cascade DecisionChain cascades rules by priority with short-circuit support ( src/decision_chain/) |
For the full capability list and API details see the API Reference.
📄 Code · bash
cargo add limiteronRequirements: Rust 1.97.1+ (see rust-toolchain.toml). The default feature set is empty (default = []) so core rate limiting has zero external storage dependencies; enable a storage feature when persistence is needed:
📄 Code · toml
[dependencies]
limiteron = { version = "0.3", features = ["macros"] }The following example comes from examples/src/bin/simple_rate_limit.rs and demonstrates the most basic token bucket usage:
📄 Code · rust
use limiteron::limiters::{Limiter, TokenBucketLimiter};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Capacity 10, refill 1 token per second
let limiter = TokenBucketLimiter::new(10, 1);
for i in 0..15 {
match limiter.allow(1).await {
Ok(true) => println!("Request {} allowed", i),
Ok(false) => println!("Request {} rate limited", i),
Err(e) => println!("Request {} error: {:?}", i, e),
}
}
Ok(())
}Run it:
📄 Code · bash
cargo run -p limiteron-examples --bin simple_rate_limitFor declarative-macro integration see User Guide · Common Patterns; for core concepts and the full API see the API Reference.
Limiteron enables no optional functionality by default (default = []); compose features as needed. For feature presets (minimal / standard / full), the complete feature list, and the file-backed SQLite deployment note see User Guide · Feature Flags; for feature dependencies see the Architecture document.
📋 Table
| Documentation | Description |
|---|---|
| 📖 User Guide | Complete tutorial from installation and core concepts to advanced usage and troubleshooting |
| 📘 API Reference | Detailed description of all public APIs |
| 🏗️ Architecture | Design philosophy, module breakdown, and extension mechanisms |
| ❓ FAQ | Frequently asked questions and troubleshooting |
| 🧪 Testing Guide | Test categories, commands, and coverage notes |
| 📈 Benchmark Procedure | cargo bench methodology, baseline refresh timing, and criterion comparison usage |
| 🧬 Test Scenarios | Test pyramid baseline and E2E scenario definitions |
| 🔒 Security | Security design, version support policy, and vulnerability reporting process |
| 📋 Changelog | Changes in every release |
| 🤝 Contributing | How to participate in development |
| 📦 docs.rs | Latest API documentation generated by docs.rs |
| 📦 crates.io | Release page |
examples/ is a standalone sub-crate in the workspace (limiteron-examples) containing 21 runnable examples; for the complete example list and run commands see examples/README.md.
Limiteron uses a layered architecture: the access layer (Tower middleware, Admin API) hands traffic to the Governor main controller, which extracts identifiers and matches rules through matchers, then cascades along each rule's decision_chain of limiter algorithm instances; bans, quotas, circuit breaking, and fallback participate in decisions as domain components; state lands through the storage abstraction (in-memory by default, switchable in production to dbnexus persistence for PostgreSQL / SQLite / MySQL).
The full architecture diagram, core decision sequence, module responsibility table, storage backend list, and extension mechanisms live in the Architecture document.
The complete decision path of a single Governor::check(context) call (distilled from src/governor.rs): identifier extraction and rule matching (computed once) → L1 negative-cache lookup (fail-closed, deny/ban decisions only) → priority-ordered cascade across each rule's decision chain (any rule rejecting rejects the request; only unanimous approval passes) → rate-limit event emission and an Allowed / Rejected / Banned outcome.
The full decision sequence diagram and the itemized key semantics (including the parallel-checker ordering where the ban check runs before the cache read) live in the Architecture document.
Limiteron collaborates closely with its sibling crates in the workspace; each integration is feature-gated and excluded by default:
| Integration | Features | Description |
|---|---|---|
| dbnexus | postgres / sqlite / mysql |
Database abstraction layer providing persistent storage adapters and metrics propagation |
| oxcache | cache-service / cache-redis / lua-script / ban-sync |
Unified cache service, Redis cache backend, Lua execution, Pub/Sub ban broadcast |
| trait-kit | kit |
LimiteronModule modular integration + health/lifecycle ports |
| confers | config-confers / config-confers-reload |
Configuration source loading and hot reload (automatic rollback on validation failure) |
For integration design notes on inklog, ICU4X, the sdforge guard layer, and the dbnexus rate-limit port adapter, see the Architecture document · Ecosystem and Integrations.
The testing strategy matrix (unit / integration & E2E / property / doc / benchmark layers) and run commands (identical to CI, including the coverage gate) live in the Testing Guide; the layer baselines and E2E scenario definitions live in Test Scenarios.
For test-scale statistics (grep count via the #[test] / #[tokio::test] attributes) see Testing Guide · Test Statistics.
Historical measurements (v0.1.0-era methodology, order-of-magnitude reference only) and the benchmark-infrastructure details are archived in the Benchmark Procedure · Historical Comparison; for the current reproducible baseline, follow the Running commands in that file together with same-machine re-measurements.
Reporting a vulnerability: please do not report security vulnerabilities through public issues. Use the GitHub Security Advisories private disclosure channel ("Report a vulnerability"). Kirky.X commits to acknowledging reports within 48 hours and providing an initial assessment within 7 days, following coordinated disclosure. See SECURITY.md for the full process.
For the security design highlights (input defenses, algorithm boundaries, Admin self-protection, read-only Web UI warnings, data protection, transport defenses, and supply chain), see the Security document.
| ✅ Completed | Core rate limiting algorithms, ban management, quota control, circuit breaker, the #[flow_control] macro, unit and integration test suites, PostgreSQL / SQLite storage via dbnexus, Governor graceful shutdown and health check, ConfigLoader environment variable overrides (v0.2.0); Tower middleware refinement, event system enhancements, RedisStorage removal with caching unified through oxcache (v0.2.1) |
| ✅ Shipped (released with 0.3.0-rc.4) | Multi-tenancy through Governor, CIDR range bans, Admin RBAC, OTLP tracing export, MySQL storage, distributed limiting, limiteron-cli, and more (see the changelog) |
| ✅ Delivered | Performance optimization and monitoring/tracing improvements — four criterion benchmark suites repaired with unified fresh-instance pass-path methodology (90fb0cb), HeaderMatcher zero-allocation ASCII fast-path hotspot reduction (-10.0%~-33.4% across 12 benchmarks, 4cc7c6f), per-rule/per-limiter dimensional metrics and governor_check span (5422c6d); OTLP trace export shipped with 0.3.0-rc.4 |
| 📋 Planned | Additional storage backends |
| 💡 Future Ideas | "ML-driven rate limiting" was adjudicated and materialized as statistical heuristics (`adaptive-limiting` AIMD concurrency window and `adaptive-threshold` sliding-window dynamic quota, both deterministic threshold logic, not neural networks — see `src/limiters/adaptive_threshold.rs`); the "community plugin system" has landed as compile-time registration (`plugins`, dynamic .so explicitly not supported, see `src/plugins/`) |
Contributions of any kind are welcome! See CONTRIBUTING.md for the development environment, TDD workflow, coding conventions, and the PR process.
|
Found a bug? |
Have a suggestion? |
Want to contribute? |
🔧 Development Environment Baseline
Rust 1.97.1 (pinned in rust-toolchain.toml); lefthook / pre-commit hooks cover fmt, clippy, supply-chain checks, secret scanning, and the coverage gate. See CONTRIBUTING.md for environment setup, hook details, and commit conventions.
See CHANGELOG.md for the full history.
This project is licensed under the MIT License.
Copyright (c) 2026 Kirky.X🌠
- 🌟 Dependencies — Built on these excellent projects:
- tokio — Async runtime
- dbnexus — Database abstraction layer
- oxcache — Unified cache service
- trait-kit — Module standard interfaces and the masking engine (the masking feature of the trait-kit repo, consumed here via log-redaction)
- inklog — Structured logging (per-target bucketed sink rate limiting via the
integrations/limiteron-inklogadapter) - dashmap — Concurrent HashMap
- 👥 Contributors — Thanks to all contributors!
- 💬 Community — Special thanks to community members
- 🐛 Issues — Report bugs and errors
- 💬 Discussions — Ask questions and share ideas
- 📦 GitHub Repository — View the source code
- 🤝 Maintainer: Kirky.X
If you find this project useful, please consider giving it a ⭐️!
Built with ❤️ by Kirky.X