This document describes the design philosophy and constraints behind
adaptiveratelimit.
The goal of this library is to provide simple, safe, and predictable adaptive rate limiting for a single process.
- Rate limits must always respect configured minimums and maximums.
- The limiter must not grow unbounded state over time.
- Adaptation should respond to sustained trends, not transient spikes.
- EWMA is used to smooth latency and error signals.
- Cooldowns are required to prevent oscillation and thrashing.
- The request path (
Allow,Record) should remain lightweight. - Expensive computation belongs in background control loops.
- All public APIs must be safe for concurrent use.
- Background goroutines must be owned and managed by the limiter.
- When the limit is exceeded, requests are explicitly rejected.
- Silent dropping or implicit blocking is discouraged.
- Public APIs should be small and intentional.
- Internals should not be exposed unless there is a clear use case.
- Background loops must stop when
Stop()is called. - No goroutine leaks or runaway timers are acceptable.
This project intentionally does not aim to provide:
- Distributed or global rate limiting
- Cross-process coordination
- Fairness across multiple clients
- Persistent state across restarts
These are better handled by centralized or distributed systems.
- Instance-local design favors simplicity and predictability over global fairness.
- EWMA smoothing favors stability over immediate reaction.
- Cooldowns trade faster adaptation for safer behavior.
These trade-offs are intentional.