Module bounded_limiter 

Memory-bounded keyed rate limiter (LRU + idle eviction). Memory-bounded keyed rate limiter.

crate::bounded_limiter::BoundedKeyedLimiter wraps a map of per-key governor::DefaultDirectRateLimiter instances behind a hard cap on the number of tracked keys, with an idle-eviction policy and an LRU fallback when the cap is reached.

Why

The governor crate ships a governor::RateLimiter::keyed state store whose memory grows monotonically with the number of distinct keys observed. For server use cases keyed by source IP this is a denial-of-service vector: an attacker spraying packets from spoofed or distinct source addresses can exhaust process memory regardless of the per-key quota.

crate::bounded_limiter::BoundedKeyedLimiter addresses this by:

1. Holding a std::collections::HashMap of K -> Entry where each Entry carries its own direct (per-key) limiter and a last_seen timestamp.
2. Capping the map at max_tracked_keys entries.
3. On insert when the map is full, first pruning entries whose last_seen is older than idle_eviction, then – if still full – evicting the entry with the oldest last_seen (“LRU eviction”). The new key is always inserted; honest new clients are never rejected because the table is full.
4. Updating last_seen on every check (including rate-limit rejections) so an actively-firing attacker cannot dodge eviction by appearing idle.
5. Optionally spawning a best-effort background prune task. Cap enforcement does not depend on this task running – it is purely an optimization that reclaims memory between admission events.

Trade-offs

• When a previously-evicted key reappears it gets a fresh quota. This is documented behaviour: a key under sustained load keeps its last_seen updated and therefore is never evicted; eviction only targets idle keys.
• The map uses std::sync::Mutex (not tokio::sync::Mutex) since admission checks must be synchronous and never .await.
• We do not log inside the critical section.

Structs

BoundedKeyedLimiter

Memory-bounded keyed rate limiter.

Enums

BoundedLimiterError

Reason a BoundedKeyedLimiter::check_key call rejected a request.