server_rate_limit library
Portable rate-limiting policies, algorithms, backends, and services.
Build a RateLimitPolicySpec for each protected route, compile the specifications with a RateLimiterBackend, and pass the resulting policies to RateLimitService. The service evaluates matching policies in declaration order and returns the first blocking RateLimitOutcome.
A backend owns persistence and concurrency. Use
CacheRateLimiterBackend with a Repository whose store implements
LockProvider when multiple requests or isolates must update a bucket
atomically. Choose RateLimitFailoverMode explicitly for the behavior you
want when that backend is unavailable.
Classes
- CacheRateLimiterBackend
- A cache-backed rate limiter with optional distributed locking.
- CompiledRateLimitPolicy
- Compiled policy ready for runtime enforcement.
- CustomResolver
- Resolves identities using a caller-provided callback.
- HeaderKeyResolver
- Resolves rate-limit identities from a request header.
- IpKeyResolver
- Resolves rate-limit identities from the client IP.
- QuotaConfig
- Rolling quota configuration for a longer-lived limit.
- RateLimitAlgorithmConfig
- Base configuration contract for a rate-limit algorithm.
- RateLimiterBackend
- Storage and concurrency contract used by a rate-limit runtime.
- RateLimitEventCallbacks
- Optional callbacks for observing rate-limit outcomes.
- RateLimitKeyResolver
- Resolves the identity string used for rate limiting.
- RateLimitKeySpec
- Declarative key resolver configuration used by compileRateLimitPolicies.
- RateLimitOutcome
- Result returned by a rate-limit evaluation.
- RateLimitPolicySpec
- Declarative policy configuration that can be compiled into a runtime policy.
- RateLimitRequest
- Request data required by the rate-limit policy runtime.
- RateLimitService
- Evaluates compiled policies for incoming requests.
- RequestMatcher
- Matches requests against an optional method and wildcard path pattern.
- SlidingWindowConfig
- Sliding-window configuration that maintains a strict window boundary.
- TokenBucketConfig
- Token-bucket parameters shared by all backends.
Enums
- RateLimitFailoverMode
- Behavior when the distributed backend becomes unavailable.
- RateLimitKeyKind
- Key resolver strategies supported by RateLimitPolicySpec.
- RateLimitStrategy
- Available enforcement strategies for rate limiting.
Functions
-
buildBucketConfig(
{required int capacity, required Duration refillInterval, double? burstMultiplier}) → TokenBucketConfig - Builds a normalized token-bucket configuration from user parameters.
-
buildRateLimitKeyResolver(
RateLimitKeySpec spec) → RateLimitKeyResolver -
Builds a runtime key resolver from
spec. -
compileRateLimitPolicies(
{required Iterable< RateLimitPolicySpec> specs, required RateLimiterBackend backend, required RateLimitFailoverMode defaultFailover}) → List<CompiledRateLimitPolicy> -
Compiles
specsinto immutable runtime policies. -
compileRateLimitPolicy(
{required RateLimitPolicySpec spec, required RateLimiterBackend backend, required RateLimitFailoverMode defaultFailover}) → CompiledRateLimitPolicy - Compiles one RateLimitPolicySpec into a runtime policy.
Typedefs
- CustomKeyResolver = String? Function(RateLimitRequest request)
- Callback signature for custom request identity resolution.