volga_rate_limiter/lib.rs
1//! # Volga Rate Limiter
2//!
3//! A lightweight and efficient rate-limiting library for Rust.
4//!
5//! This crate provides in-memory rate limiting algorithms designed
6//! for high-performance HTTP services and middleware.
7//!
8//! ## Overview
9//!
10//! Rate limiting is used to control the number of requests that a client
11//! (or a group of clients) can perform within a given time window.
12//! Typical use cases include:
13//!
14//! - Protecting APIs from abuse or accidental overload
15//! - Enforcing fair usage policies
16//! - Applying different limits for anonymous users, authenticated users,
17//! tenants, or API keys
18//!
19//! This crate focuses on **per-node, in-memory** rate limiting.
20//! It is intentionally simple and fast, and does **not** attempt to
21//! synchronize state across multiple processes or machines.
22//!
23//! ## Algorithms
24//!
25//! The following rate-limiting algorithms are provided:
26//!
27//! - [`FixedWindowRateLimiter`]
28//! - Counts requests in discrete, fixed-size time windows
29//! - Very fast and simple
30//! - May allow short bursts at window boundaries
31//!
32//! - [`SlidingWindowRateLimiter`]
33//! - Uses a sliding time window with linear weighting
34//! - Provides smoother request distribution
35//! - Slightly more expensive than a fixed window
36//!
37//! - [`TokenBucketRateLimiter`]
38//! - Allows bursts up to a token bucket capacity
39//! - Enforces a steady average refill rate
40//! - Simple and flexible for bursty traffic
41//!
42//! - [`GcraRateLimiter`]
43//! - Uses the Generic Cell Rate Algorithm (GCRA)
44//! - Smooths traffic with explicit burst tolerance
45//! - Accurate average rate enforcement
46//!
47//! ## Time Source Abstraction
48//!
49//! All rate limiters are built on top of a pluggable [`TimeSource`] abstraction.
50//! This allows:
51//!
52//! - Deterministic and fast unit testing
53//! - Custom time implementations if needed
54//!
55//! The default implementation, [`SystemTimeSource`], is based on
56//! `std::time::Instant`.
57//!
58//! ## Concurrency Model
59//!
60//! The rate limiters are designed to be:
61//!
62//! - Thread-safe
63//! - Lock-free or minimally locking on the hot path
64//! - Safe to share between async tasks and threads
65//!
66//! Internal state is optimized for frequent reads and updates under
67//! high contention.
68//!
69//! ## Usage
70//!
71//! The rate limiters are intended to be embedded into higher-level
72//! frameworks or middleware layers.
73
74mod rate_limiter;
75
76pub use rate_limiter::{
77 FixedWindowParams, FixedWindowRateLimiter, FixedWindowStore, GcraParams, GcraRateLimiter,
78 GcraStore, InMemoryFixedWindowStore, InMemoryGcraStore, InMemorySlidingWindowStore,
79 InMemoryTokenBucketStore, RateLimiter, SlidingWindowParams, SlidingWindowRateLimiter,
80 SlidingWindowStore, SystemTimeSource, TimeSource, TokenBucketParams, TokenBucketRateLimiter,
81 TokenBucketStore,
82};