Merge branch 'main' into feature/configs

Author: RomanEmreis

volga-rate-limiter/README.md

@@ -2,8 +2,8 @@
 
 A lightweight and efficient rate-limiting library for Rust.
 
-This crate provides in-memory rate limiting algorithms designed
-for high-performance HTTP services and middleware.
+This crate provides rate limiting algorithms with pluggable storage backends,
+designed for high-performance HTTP services and middleware.
 
 ## Overview
 
@@ -16,10 +16,6 @@ Typical use cases include:
 - Applying different limits for anonymous users, authenticated users,
   tenants, or API keys
 
-This crate focuses on **per-node, in-memory** rate limiting.
-It is intentionally simple and fast, and does **not** attempt to
-synchronize state across multiple processes or machines.
-
 ## Algorithms
 
 The following rate-limiting algorithms are provided:
@@ -33,7 +29,7 @@ The following rate-limiting algorithms are provided:
   - Uses a sliding time window with linear weighting
   - Provides smoother request distribution
   - Slightly more expensive than a fixed window
-  
+
 - `TokenBucketRateLimiter`
   - Allows bursts up to a token bucket capacity
   - Enforces a steady average refill rate
@@ -44,16 +40,62 @@ The following rate-limiting algorithms are provided:
   - Smooths traffic with explicit burst tolerance
   - Accurate average rate enforcement
 
+## Pluggable Storage Backends
+
+Each algorithm is generic over a **store trait**, allowing you to swap the
+default in-memory backend for an external one (e.g. Redis) without changing
+the rate limiting logic.
+
+| Algorithm | Store trait | Operation |
+|---|---|---|
+| Fixed Window | `FixedWindowStore` | `check_and_count` |
+| Sliding Window | `SlidingWindowStore` | `check_and_count` |
+| Token Bucket | `TokenBucketStore` | `try_consume` |
+| GCRA | `GcraStore` | `check_and_advance` |
+
+Each rate limiter provides constructors for all combinations:
+
+- `::new()` — system clock + default in-memory store
+- `::with_time_source()` — custom clock + in-memory store
+- `::with_store()` — system clock + custom store
+- `::with_time_source_and_store()` — both custom
+
+The default in-memory stores are backed by `DashMap` and use lock-free
+atomic operations on the hot path.
+
+### Implementing a custom store
+
+Store traits require a single atomic operation. Parameter structs are
+`#[non_exhaustive]` for forward compatibility — access fields by name:
+
+```rust
+use volga_rate_limiter::store::{TokenBucketParams, TokenBucketStore};
+
+struct MyRedisStore { /* ... */ }
+
+impl TokenBucketStore for MyRedisStore {
+    fn try_consume(&self, params: TokenBucketParams) -> bool {
+        let key = params.key;
+        let capacity = params.capacity_scaled;
+        // ... your Redis logic here
+        true
+    }
+}
+```
+
+> **Note:** Backends with built-in TTL support (like Redis) can skip manual
+> eviction — the eviction grace parameters are designed for in-memory stores
+> that perform lazy cleanup.
 
 ## Time Source Abstraction
 
-All rate limiters are built on top of a pluggable [`TimeSource`] abstraction.
+All rate limiters are built on top of a pluggable `TimeSource` abstraction.
 This allows:
 
 - Deterministic and fast unit testing
 - Custom time implementations if needed
 
-The default implementation, [`SystemTimeSource`], is based on
+The default implementation, `SystemTimeSource`, is based on
 `std::time::Instant`.
 
 ## Concurrency Model
@@ -67,17 +109,10 @@ The rate limiters are designed to be:
 Internal state is optimized for frequent reads and updates under
 high contention.
 
-## Scope and Limitations
-
-- This crate implements **in-memory** rate limiting only
-- It does **not** provide distributed coordination
-- For multi-node systems, rate limiting should be combined with
-  external storage or coordination mechanisms (e.g. Redis, gateways)
-
 ## Usage
 
 The rate limiters are intended to be embedded into higher-level
 frameworks or middleware layers.
 
 ## License
-Volga is licensed under the MIT License. Contributions welcome!
+Volga is licensed under the MIT License. Contributions welcome!

volga-rate-limiter/src/lib.rs

@@ -66,13 +66,6 @@
 //! Internal state is optimized for frequent reads and updates under
 //! high contention.
 //!
-//! ## Scope and Limitations
-//!
-//! - This crate implements **in-memory** rate limiting only
-//! - It does **not** provide distributed coordination
-//! - For multi-node systems, rate limiting should be combined with
-//!   external storage or coordination mechanisms (e.g. Redis, gateways)
-//!
 //! ## Usage
 //!
 //! The rate limiters are intended to be embedded into higher-level

volga/src/rate_limiting.rs

@@ -27,8 +27,9 @@ pub use sliding_window::SlidingWindow;
 pub use token_bucket::TokenBucket;
 
 pub use volga_rate_limiter::{
-    FixedWindowRateLimiter, GcraRateLimiter, RateLimiter, SlidingWindowRateLimiter,
-    TokenBucketRateLimiter,
+    FixedWindowParams, FixedWindowRateLimiter, FixedWindowStore, GcraParams, GcraRateLimiter,
+    GcraStore, RateLimiter, SlidingWindowParams, SlidingWindowRateLimiter, SlidingWindowStore,
+    TokenBucketParams, TokenBucketRateLimiter, TokenBucketStore,
 };
 
 pub mod by;