limiteron 0.1.1

---

📋 Table of Contents

• ✨ Features
• 🎯 Use Cases
• 🚀 Quick Start
  • Installation
  • Basic Usage
• 📚 Documentation
• 🎨 Examples
• 🏗️ Architecture
• ⚙️ Configuration
• 🧪 Testing
• 📊 Performance
• 🔒 Security
• 🗺️ Roadmap
• 🤝 Contributing
• 📄 License
• 🙏 Acknowledgments

---

✨ Features

🎯 Core Features

• ✅ Multiple Rate Limiting Algorithms - Token bucket, fixed window, sliding window, concurrency control
• ✅ Ban Management - IP ban, automatic ban, ban priority
• ✅ Quota Control - Quota allocation, quota alerts, quota overdraw
• ✅ Circuit Breaker - Automatic failover, state recovery, fallback strategy

⚡ Advanced Features

• 🚀 High Performance - Latency < 200μs P99
• 🔐 Secure and Reliable - Memory safety, SQL injection protection
• 🌐 Multi-Storage Support - PostgreSQL, Redis, in-memory storage
• 📦 Easy to Use - Macro support, clean API

🎨 特性亮点

graph LR
    A[请求] --> B[标识符提取]
    B --> C[限流检查]
    B --> D[封禁检查]
    B --> E[配额检查]
    C --> F[决策链]
    D --> F
    E --> F
    F --> G[允许/拒绝]

    style A fill:#e1f5ff
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#81d4fa
    style E fill:#81d4fa
    style F fill:#4fc3f7
    style G fill:#29b6f6

---

🎯 Use Cases

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

async fn enterprise_api() -> Result<(), Box<dyn std::error::Error>> {
    let limiter = TokenBucketLimiter::new(100, 10); // 100 tokens, refill 10 per second

    // Rate limiting check
    match limiter.allow(1).await {
        Ok(true) => {
            // Process request
            process_request().await;
        }
        Ok(false) => {
            eprintln!("Rate limit exceeded");
        }
        Err(e) => {
            eprintln!("Error: {:?}", e);
        }
    }

    Ok(())
}

async fn process_request() {
    println!("Processing request...");
}

Suitable for enterprise applications requiring high concurrency and reliability.

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::FlowGuardError> {
    // API business logic
    Ok("Success".to_string())
}

Suitable for protecting API services from abuse and DDoS attacks.

use limiteron::ban_manager::{BanManager, BanTarget};
use limiteron::storage::MockBanStorage;
use std::sync::Arc;

async fn web_app() -> Result<(), Box<dyn std::error::Error>> {
    // Create storage and ban manager
    let storage = Arc::new(MockBanStorage::default());
    let ban_manager = BanManager::new(storage, None).await?;

    // Check if user is banned
    let user_target = BanTarget::UserId("user123".to_string());
    if let Some(ban_record) = ban_manager.is_banned(&user_target).await? {
        println!("User is banned: {:?}", ban_record);
        return Err("User is banned".into());
    }

    // Process request
    println!("Processing request for user123");
    Ok(())
}

Suitable for web applications that need to prevent malicious users and crawlers.

---

🚀 Quick Start

Installation

🦀 Cargo

[dependencies]
limiteron = { version = "0.1", features = ["macros"] }

🔧 Features

[dependencies]
limiteron = { version = "0.1", features = ["postgres", "redis", "macros"] }

Feature Flags

🎛️ 可选特性配置

Limiteron 使用 feature flags 来控制功能启用，默认只启用内存存储：

预定义组合

# 最小化：仅核心限流
limiteron = { version = "0.1", features = ["minimal"] }

# 标准：核心 + 基础高级功能
limiteron = { version = "0.1", features = ["standard"] }

# 完整：所有功能
limiteron = { version = "0.1", features = ["full"] }

单独特性

# 存储后端
limiteron = { version = "0.1", features = ["postgres", "redis"] }

# 高级功能
limiteron = { version = "0.1", features = ["ban-manager", "quota-control", "circuit-breaker"] }

# 宏支持
limiteron = { version = "0.1", features = ["macros"] }

特性	描述	默认
memory	内存存储	✅
postgres	PostgreSQL 存储	❌
redis	Redis 存储	❌
ban-manager	封禁管理	❌
quota-control	配额控制	❌
circuit-breaker	熔断器	❌
macros	宏支持	❌
telemetry	遥测和追踪	❌
monitoring	Prometheus 指标	❌

Basic Usage

🎬 5-Minute Quick Start

Step 1: Add Dependency

[dependencies]
limiteron = { version = "0.1", features = ["macros"] }

Step 2: Use Macro

use limiteron::flow_control;

#[flow_control(rate = "10/s")]
async fn api_call() -> Result<String, limiteron::error::FlowGuardError> {
    Ok("Success".to_string())
}

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Step 1: Create limiter
    let limiter = TokenBucketLimiter::new(10, 1); // 10 tokens, refill 1 per second

    // Step 2: Check rate limit
    match limiter.allow(1).await {
        Ok(true) => println!("✅ Request allowed"),
        Ok(false) => println!("❌ Request rate limited"),
        Err(e) => println!("❌ Error: {:?}", e),
    }

    // Step 3: Use with cost
    match limiter.allow(2).await {
        Ok(true) => println!("✅ Request with cost 2 allowed"),
        Ok(false) => println!("❌ Request with cost 2 rate limited"),
        Err(e) => println!("❌ Error: {:?}", e),
    }

    Ok(())
}

---

📚 Documentation

📖 Additional Resources

• 🎓 User Guide - Detailed tutorial
• 🔧 API Reference - API documentation
• ❓ FAQ - Frequently asked questions
• 🐛 Troubleshooting - Common issues and solutions

---

🎨 Examples

💡 Practical Examples

📝 Example 1: Basic Rate Limiting

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let limiter = TokenBucketLimiter::new(10, 1);

    for i in 0..15 {
        match limiter.allow(1).await {
            Ok(true) => println!("Request {} ✅", i),
            Ok(false) => println!("Request {} ❌", i),
            Err(e) => println!("Request {} Error: {:?}", i, e),
        }
    }

    Ok(())
}

Request 0 ✅
Request 1 ✅
...
Request 9 ✅
Request 10 ❌
...
Request 14 ❌
✅ First 10 requests allowed, remaining rate limited

🔥 Example 2: Using Macro

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::FlowGuardError> {
    // API business logic
    Ok(format!("Processing request for user {}", user_id))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let result = api_handler("user123").await?;
    println!("{}", result);
    Ok(())
}

Processing request for user123
✅ Macro automatically handles rate limiting

📂 View All Examples →

---

🏗️ Architecture

System Overview

graph TB
    A[User App] --> B[API Layer]
    B --> C[Governor]
    C --> D[Identifier Extraction]
    C --> E[Decision Chain]
    D --> F[Matchers]
    E --> G[Limiters]
    E --> H[Ban Management]
    E --> I[Quota Control]
    E --> J[Circuit Breaker]
    G --> K[L2/L3 Cache]
    H --> K
    I --> K
    K --> L[Storage Layer]
    L --> M[PostgreSQL]
    L --> N[Redis]
    L --> O[Memory]

    style A fill:#e1f5ff
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#4fc3f7
    style E fill:#4fc3f7
    style F fill:#29b6f6
    style G fill:#29b6f6
    style H fill:#29b6f6
    style I fill:#29b6f6
    style J fill:#29b6f6
    style K fill:#0288d1
    style L fill:#0277bd
    style M fill:#01579b
    style N fill:#01579b
    style O fill:#01579b

Component	Description	Status
Governor	Main controller, end-to-end flow control	✅ Stable
Matchers	Identifier extraction (IP, User ID, Device ID, etc.)	✅ Stable
Limiters	Multiple rate limiting algorithms	✅ Stable
Ban Management	IP ban, automatic ban	✅ Stable
Quota Control	Quota allocation, quota alerts	✅ Stable
Circuit Breaker	Automatic failover, state recovery	✅ Stable
Cache	L2/L3 cache support	✅ Stable
Storage Layer	PostgreSQL, Redis, in-memory	✅ Stable

---

⚙️ Configuration

🎛️ Configuration Options

Basic Configuration

[limiter]
rate_limit = "100/s"
quota_limit = "10000/m"
concurrency_limit = 50

[cache]
l2_capacity = 10000
l3_capacity = 100000

Advanced Configuration

[limiter]
rate_limit = "100/s"
quota_limit = "10000/m"
concurrency_limit = 50

[storage]
type = "redis"
connection_string = "redis://localhost:6379"

[telemetry]
enable_metrics = true
enable_tracing = true

Option	Type	Default	Description
rate_limit	String	"100/s"	Rate limit
quota_limit	String	"10000/m"	Quota limit
concurrency_limit	Integer	50	Concurrency limit
l2_capacity	Integer	10000	L2 cache capacity
l3_capacity	Integer	100000	L3 cache capacity
storage_type	String	"memory"	Storage type
enable_metrics	Boolean	false	Enable metrics
enable_tracing	Boolean	false	Enable tracing

---

🧪 Testing

# Run all tests
cargo test --all-features

# Run specific test
cargo test test_name

# Run integration tests
cargo test --test integration_tests

# Run benchmarks
cargo bench

---

📊 Performance

⚡ Benchmark Results

Note: The following data represents actual benchmark results from comprehensive testing (2026-01-19).

Throughput

Limiter Type	Actual	Target	Achievement
TokenBucket	12M+ ops/s	500K ops/s	✅ 24x
FixedWindow	20M+ ops/s	300K ops/s	✅ 66x
ConcurrencyLimiter	12M+ ops/s	200K ops/s	✅ 60x

Latency

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

Concurrency Test Results

Test Item	Result	Status
Data Consistency	100%	✅ Pass
High Concurrency Stability	50/100 concurrent	✅ Pass
Rate Limit Correctness	1000/1000	✅ Pass

# Run performance tests
cd temp/comprehensive_test
./target/release/functional_test    # Functional tests
./target/release/performance_test   # Performance tests
./target/release/concurrency_test   # Concurrency tests

Sample output:

功能测试: 7/7 Pass (100%)
TokenBucket: 12,088,759 ops/s
FixedWindow: 19,920,188 ops/s
ConcurrencyLimiter: 11,891,237 ops/s
并发测试: 100% 数据一致性

---

🔒 Security

🛡️ Security Features

Security Measures

• ✅ Memory Protection - Rust memory safety guarantees
• ✅ Input Validation - IP address, User ID, MAC address validation
• ✅ SQL Injection Protection - Using parameterized queries
• ✅ Password Protection - Using secrecy library for sensitive data
• ✅ Audit Logging - Complete operation tracking

Reporting Security Issues

Please report security vulnerabilities through GitHub Issues.

---

🗺️ Roadmap

🎯 Development Plan

gantt
    title Limiteron Roadmap
    dateFormat  YYYY-MM
    section Phase 1
    Core Features           :done, 2026-01, 2026-03
    section Phase 2
    Feature Extensions      :active, 2026-03, 2026-06
    section Phase 3
    Performance Optimization :2026-06, 2026-09
    section Phase 4
    Production Ready        :2026-09, 2026-12

✅ Completed

• Core rate limiting
• Ban management
• Quota control
• Circuit breaker
• Unit and integration tests
• Macro support
• PostgreSQL and Redis storage

🚧 In Progress

• Performance optimization
• Monitoring and tracing improvements
• Documentation completion
• Example code additions

📋 Planned

• Lua script enhancements
• Custom matcher extensions
• Additional storage backends
• Web UI management interface

💡 Future Ideas

• Distributed rate limiting
• Machine learning-driven rate limiting
• Additional rate limiting algorithms
• Community plugin system

---

🤝 Contributing

💖 Welcome Contributions!

🐛 Report Issues

Found a bug? Create Issue

💡 Feature Requests

Have a suggestion? Start Discussion

🔧 Submit Code

Want to contribute? Fork & PR

How to Contribute

1. Fork the repository
2. Clone your fork: git clone https://github.com/yourusername/limiteron.git
3. Create a branch: git checkout -b feature/amazing-feature
4. Make your changes
5. Test your changes: cargo test --all-features
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Create a Pull Request

Code Style

• Follow Rust standard coding conventions
• Write comprehensive tests
• Update documentation
• Add examples for new features

---

📄 License

This project is licensed under Apache 2.0:

---

🙏 Acknowledgments

Built with Excellent Tools

Special Thanks

• 🌟 Dependencies - Built on these excellent projects:

  • tokio - Async runtime
  • sqlx - Async SQL toolkit
  • redis - Redis client
  • dashmap - Concurrent HashMap
  • lru - LRU cache

• 👥 Contributors - Thanks to all contributors!

• 💬 Community - Special thanks to community members

---

📞 Contact & Support

Stay Connected

---

⭐ Star History

---

💝 Support This Project

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

Built with ❤️ by Kirky.X

⬆ Back to Top

---

© 2026 Kirky.X. All rights reserved.