Crate rater 

Rater - High-Performance Rate Limiter for Rust

A blazing-fast, lock-free rate limiting library that helps you control the flow of requests in your application. Think of it as a traffic controller that ensures your system doesn’t get overwhelmed by too many requests at once.

What is Rate Limiting?

Rate limiting is like having a bouncer at a club - it controls how many requests can enter your system within a specific time period. This prevents abuse, ensures fair usage, and protects your services from being overwhelmed.

The Token Bucket Algorithm

This library uses the token bucket algorithm, which works like a vending machine:

    Token Bucket Visualization:

    Time 0:    [🪙🪙🪙🪙🪙] (5 tokens available)
    Request 1: [🪙🪙🪙🪙] ✅ (takes 1 token)
    Request 2: [🪙🪙🪙] ✅ (takes 1 token)
    Time +1s:  [🪙🪙🪙🪙🪙] (refilled to max)
    Request 3: [🪙🪙🪙🪙] ✅ (takes 1 token)

• Tokens = Permission to make a request
• Bucket = Container holding a limited number of tokens
• Refill = Tokens are added back at a steady rate

Features

• 🔒 Lock-free Implementation - Multiple threads can use it simultaneously without blocking
• ⚡ Blazing Fast - Optimized for your CPU architecture (uses PAUSE on Intel, YIELD on ARM)
• 🔄 Smart Refilling - Automatically adjusts when under heavy load
• 🌐 Per-IP Limiting - Different limits for different users/IPs
• 📊 Real-time Metrics - Monitor performance and detect issues
• 🛡️ Thread-Safe - Safe to share across threads without extra synchronization

Quick Start

Basic Rate Limiting

use rater::RateLimiter;

// Create a rate limiter:
// - 100 tokens maximum capacity (burst limit)
// - Refills 10 tokens every second
let limiter = RateLimiter::new(100, 10);

// Try to process a request
if limiter.try_acquire() {
    println!("✅ Request approved - processing...");
    // Your request handling code here
} else {
    println!("⛔ Rate limited - try again later");
    // Return 429 Too Many Requests
}

Advanced Usage with Builder Pattern

use rater::{RateLimiterBuilder, MemoryOrdering};

let limiter = RateLimiterBuilder::new()
    .max_tokens(1000)           // Maximum burst size
    .refill_rate(100)           // Tokens per interval
    .refill_interval_ms(1000)   // Refill every second
    .memory_ordering(MemoryOrdering::AcquireRelease)  // Memory consistency
    .build();

// Acquire multiple tokens at once (for expensive operations)
if limiter.try_acquire_n(5) {
    println!("Acquired 5 tokens for expensive operation");
}

Per-IP Rate Limiting

use rater::{IpRateLimiterManager, RateLimiterConfig};
use std::net::IpAddr;

// Create a manager that handles rate limiting per IP address
let config = RateLimiterConfig::per_second(10);  // 10 requests per second per IP
let manager = IpRateLimiterManager::new(config);

// In your request handler:
let client_ip: IpAddr = "192.168.1.100".parse().unwrap();

if manager.try_acquire(client_ip) {
    // Process request
} else {
    // Rate limit this specific IP
}

Architecture Overview

                   ┌─────────────────────────┐
                   │   Your Application      │
                   └──────────┬──────────────┘
                              │
                   ┌──────────▼──────────────┐
                   │    Rate Limiter API     │
                   ├──────────────────────────┤
                   │  • try_acquire()         │
                   │  • try_acquire_n()       │
                   │  • metrics()             │
                   └──────────┬───────────────┘
                              │
               ┌──────────────┴───────────────┐
               │                               │
    ┌──────────▼──────────┐       ┌───────────▼──────────┐
    │   Token Bucket      │       │   IP Manager         │
    ├─────────────────────┤       ├──────────────────────┤
    │ • Atomic tokens     │       │ • Per-IP limiters    │
    │ • Auto refill       │       │ • Auto cleanup       │
    │ • Lock-free CAS     │       │ • LRU eviction       │
    └─────────────────────┘       └──────────────────────┘

Performance Characteristics

Operation	Time Complexity	Space Complexity
try_acquire()	O(1)*	O(1)
try_acquire_n()	O(1)*	O(1)
refill	O(1)*	O(1)
metrics	O(1)	O(1)

*Amortized constant time with bounded retries under contention

Common Use Cases

1. API Rate Limiting - Prevent API abuse and ensure fair usage
2. Database Protection - Limit queries to prevent overload
3. Microservice Communication - Control inter-service request rates
4. Background Job Processing - Throttle job execution rates
5. Resource Access Control - Limit access to expensive resources

Thread Safety

All types are thread-safe and can be shared across threads:

• RateLimiter - Safe to share via Arc<RateLimiter>
• IpRateLimiterManager - Safe to share via Arc<IpRateLimiterManager>

Memory Ordering

Choose the right memory ordering for your use case:

• Relaxed - Fastest, use when exact ordering doesn’t matter
• AcquireRelease - Balanced (default), ensures proper synchronization
• Sequential - Strongest guarantees, use when strict ordering is critical

Examples

See the examples/ directory for complete examples:

• basic.rs - Simple rate limiting
• ip_limiting.rs - Per-IP rate limiting with cleanup

Safety

This crate uses unsafe code only for:

• Platform-specific CPU pause instructions (for efficient spinning)
• Cache alignment optimizations (to prevent false sharing)

All unsafe code is thoroughly tested and documented.

Modules

prelude

Prelude module for convenient imports.

Structs

IpRateLimiterManager

IP-based rate limiting manager for per-client limits Manager for per-IP rate limiting.

ManagerStats

IP-based rate limiting manager for per-client limits Statistics for the IP rate limiter manager.

RateLimiter

Core rate limiter implementing the token bucket algorithm Lock-free token bucket rate limiter.

RateLimiterBuilder

Builder pattern for creating rate limiters with custom configuration.

RateLimiterConfig

Configuration types for customizing rate limiter behavior Configuration for rate limiter instances.

RateLimiterMetrics

Metrics and health monitoring for observability Comprehensive metrics for rate limiter performance analysis.

Enums

HealthStatus

Metrics and health monitoring for observability Health status indicator for the rate limiter.

MemoryOrdering

Configuration types for customizing rate limiter behavior Memory ordering strategy for atomic operations.

Constants

MSRV

Minimum supported Rust version.

VERSION

Version information for the crate.

Functions

cpu_relax

Utility functions for time and CPU optimizations CPU-specific relaxation hint for spin loops.

current_time_ms

Utility functions for time and CPU optimizations Returns the current time in milliseconds since UNIX epoch.

current_time_ns

Utility functions for time and CPU optimizations Returns the current time in nanoseconds since UNIX epoch.

current_time_us

Utility functions for time and CPU optimizations Returns the current time in microseconds since UNIX epoch.

Type Aliases

SharedIpManager

An IP rate limiter manager wrapped in Arc for convenient thread-safe sharing.

SharedRateLimiter

A rate limiter wrapped in Arc for convenient thread-safe sharing.