Struct KeyedRatePolicy 

pub struct KeyedRatePolicy<X, K> { /* private fields */ }

Available on crate feature std only.

A limit Policy that rate limits inputs per key: every key gets its own token bucket, lazily created on first use and stored in a bounded, idle-evicting cache.

The typical use is per-client fairness, keying on the client IP with ClientIpRateKey; any InputToRateKey extractor (including plain closures) works.

Modes mirror RatePolicy: KeyedRatePolicy::abort rejects over-budget inputs with RateLimitReached (a 429 path), KeyedRatePolicy::wait paces them. Inputs without a derivable key are allowed through by default. This is convenient for stacks where the key is genuinely optional, but is fail-open when the extractor depends on missing metadata; security limits should set KeyedRatePolicy::set_missing_key_allowed to false and abort them with MissingRateKey instead.

Memory is bounded: at most KeyedRatePolicy::set_max_keys buckets are kept, and buckets idle longer than KeyedRatePolicy::set_idle_timeout are evicted. The idle timeout is clamped to the time it takes to refill the configured burst from empty, so a bucket evicted for idleness and recreated full cannot regain budget any faster than one that stayed cached.

A new key is rejected with RateKeyCapacityReached while max_keys non-idle buckets are live. Live buckets are never evicted to admit another key, because recreating an exhausted bucket full would let callers bypass the rate limit by cycling keys at the memory bound.

Size max_keys for the number of simultaneously active keys after aggregation. The default IPv6 /64 aggregation means one routed /48 can still fill the default 65 536-key capacity; deployments serving larger IPv6 populations can aggregate more broadly with ClientIpRateKey::set_ipv6_prefix and/or raise this bound.

Implementations

impl<X, K> KeyedRatePolicy<X, K>

where K: RateKey,

pub fn wait(extractor: X, rate: Rate) -> Self

Create a new KeyedRatePolicy that paces inputs beyond the given per-key Rate. A known key waits rather than failing when its bucket is empty; a new key can still fail closed when the configured key capacity is exhausted.

pub fn abort(extractor: X, rate: Rate) -> Self

Create a new KeyedRatePolicy that aborts inputs beyond the given per-key Rate with RateLimitReached.

pub fn with_burst(self, burst: u64) -> Self

Override the per-key burst capacity (default: one period worth of units).

Panics

Panics if burst is zero.

pub fn set_burst(&mut self, burst: u64) -> &mut Self

Override the per-key burst capacity (default: one period worth of units).

Panics

Panics if burst is zero.

pub fn with_missing_key_allowed(self, allowed: bool) -> Self

Allow (default) or abort — with MissingRateKey — inputs for which no key can be derived.

pub fn set_missing_key_allowed(&mut self, allowed: bool) -> &mut Self

Allow (default) or abort — with MissingRateKey — inputs for which no key can be derived.

pub fn with_max_keys(self, max_keys: u64) -> Self

Bound the number of tracked keys (default: 65 536). When all tracked buckets are still active, a new key is rejected with RateKeyCapacityReached instead of evicting a live bucket and resetting its budget.

This is an availability bound as well as a memory bound. With the default IPv6 /64 keys, one /48 contains 65 536 distinct keys. Aggregate more broadly or raise this value when that is a realistic share of the expected active client population.

Panics

Panics if max_keys is zero.

pub fn set_max_keys(&mut self, max_keys: u64) -> &mut Self

Bound the number of tracked keys (default: 65 536). When all tracked buckets are still active, a new key is rejected with RateKeyCapacityReached instead of evicting a live bucket and resetting its budget.

This is an availability bound as well as a memory bound. With the default IPv6 /64 keys, one /48 contains 65 536 distinct keys. Aggregate more broadly or raise this value when that is a realistic share of the expected active client population.

Panics

Panics if max_keys is zero.

pub fn with_idle_timeout(self, idle_timeout: Duration) -> Self

Evict buckets idle for this long (default: 1 minute), clamped to at least the time required to refill the burst from empty.

pub fn set_idle_timeout(&mut self, idle_timeout: Duration) -> &mut Self

Evict buckets idle for this long (default: 1 minute), clamped to at least the time required to refill the burst from empty.

Trait Implementations

impl<X: Debug, K> Debug for KeyedRatePolicy<X, K>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<X, K, Input> Policy<Input> for KeyedRatePolicy<X, K>

where X: InputToRateKey<Input, Key = K>, K: RateKey, Input: Send + 'static,

type Guard = ()

The guard type that is returned when the input is allowed to proceed.

type Error = Box<dyn Error + Sync + Send>

The error type that is returned when the input is not allowed to proceed, and should be aborted.

async fn check( &self, input: Input, ) -> PolicyResult<Input, Self::Guard, Self::Error>

Check whether the input is allowed to proceed.