Skip to content
Kirky-XPublic

About

Rust unified flow-control framework — 9 rate-limit algorithms, banning, quotas, circuit breaker, bulkhead, retry, timeout, adaptive thresholds, Redis Lua distribution, plugins, and Admin API/Web UI behind one Governor decision chain

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

624 Commits

Folders and files

Repository files navigation

English | 中文

Limiteron Logo

Rust 2024 Rustc 1.97.1+ crates.io docs.rs downloads CI coverage license

中文 | English

Unified Flow Control Framework for Rust

✨ Features • 🚀 Quick Start • 📚 Documentation • 💻 Examples • 🤝 Contributing


🚦 Unified Traffic Control

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

📑 Table of Contents

✨ Features

🎯 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.


🚀 Quick Start

📦 Installation

📄 Code · bash
cargo add limiteron

Requirements: 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"] }

💡 Minimal Runnable Example

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_limit

For declarative-macro integration see User Guide · Common Patterns; for core concepts and the full API see the API Reference.


🎨 Feature Flags

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.


📚 Documentation

📋 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

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.


🏗️ Architecture

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.


🎯 Core Decision Flow

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.


🔗 Ecosystem & Integrations

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.


🧪 Testing

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.


📊 Performance

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.


🔒 Security

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.


🗺️ Roadmap

✅ 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/`)

🤝 Contributing

Contributions of any kind are welcome! See CONTRIBUTING.md for the development environment, TDD workflow, coding conventions, and the PR process.

🐛 Report Issues

Found a bug?
Create Issue

💡 Feature Requests

Have a suggestion?
Start Discussion

🔧 Submit Code

Want to contribute?
Fork & PR

🔧 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.


📋 Changelog

See CHANGELOG.md for the full history.


📄 License

This project is licensed under the MIT License.

Copyright (c) 2026 Kirky.X🌠


🙏 Acknowledgments

  • 🌟 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-inklog adapter)
    • dashmap — Concurrent HashMap
  • 👥 Contributors — Thanks to all contributors!
  • 💬 Community — Special thanks to community members

📞 Contact & Support


⭐ Star History

Star History Chart

💝 Support This Project

If you find this project useful, please consider giving it a ⭐️!

Built with ❤️ by Kirky.X

About

Rust unified flow-control framework — 9 rate-limit algorithms, banning, quotas, circuit breaker, bulkhead, retry, timeout, adaptive thresholds, Redis Lua distribution, plugins, and Admin API/Web UI behind one Governor decision chain

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages