Flux Limiter

A high-performance rate limiter based on the Generic Cell Rate Algorithm (GCRA) with nanosecond precision and lock-free concurrent access.

Features

• Mathematically precise: Implements the GCRA algorithm with exact nanosecond timing
• High performance: Lock-free concurrent access using DashMap
• Generic client IDs: Works with any hashable client identifier (String, IpAddr, u64, etc.)
• Rich metadata: Returns detailed decision information for HTTP headers
• Memory efficient: Configurable cleanup of stale client entries
• Robust error handling: Graceful handling of clock failures and configuration errors
• Thread-safe: Safe concurrent use across multiple threads
• Zero allocations: Efficient hot path with minimal overhead

Installation

Add this to your Cargo.toml:

[dependencies]
flux-limiter = "0.7.2"

Quick Start

use flux_limiter::{FluxLimiter, FluxLimiterConfig, SystemClock};

// Create a rate limiter: 10 requests per second with burst of 5
let config = FluxLimiterConfig::new(10.0, 5.0);
let limiter = FluxLimiter::with_config(config, SystemClock).unwrap();

// Check if a request should be allowed
match limiter.check_request("user_123") {
    Ok(decision) => {
        if decision.allowed {
            println!("Request allowed");
        } else {
            println!("Rate limited - retry after {:.2}s",
                     decision.retry_after_seconds.unwrap_or(0.0));
        }
    }
    Err(e) => {
        eprintln!("Rate limiter error: {}", e);
        // Handle error appropriately (e.g., fail-open, fail-closed)
    }
}

Documentation

For comprehensive documentation, including:

• Error handling strategies (fail-open, fail-closed, fallback patterns)
• Configuration guide (rate/burst explained, builder pattern)
• Web framework integration (Axum, Actix, etc.)
• Advanced usage (custom client IDs, memory management, cleanup)
• Production considerations (monitoring, graceful degradation)
• Architecture details (GCRA algorithm, concurrency model, performance)

Please see the full documentation.

License

This project is licensed under the MIT License - see the License.txt file for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.