pub struct Quota { /* private fields */ }Expand description
A rate limit: limit requests per period, per key, with a burst ceiling.
A quota describes the sustained rate a key is allowed and how much it may
spend at once. Under the default token-bucket algorithm each key starts with
a full allowance of burst, spends one unit per admitted request, and
accrues limit units back over period — so a key may burst up to burst
immediately and then sustain limit per period thereafter. burst
defaults to limit (the classic “burst equals rate” bucket); raise it with
with_burst to allow larger spikes, or lower it to shape
traffic more tightly.
The convenience constructors per_second and
per_minute are infallible (a limit of 0 yields a
quota that admits nothing). The general rate constructor
validates its inputs and returns a RateLimiterError for values that
cannot describe a working limit.
The window algorithms (fixed and sliding window) admit at most limit per
period and ignore burst; it applies to the token and leaky buckets.
§Examples
use rate_net::Quota;
use std::time::Duration;
let per_sec = Quota::per_second(100);
assert_eq!(per_sec.limit(), 100);
assert_eq!(per_sec.period(), Duration::from_secs(1));
assert_eq!(per_sec.burst(), 100); // defaults to the limit
// 1000 requests per minute, but bursts capped at 50.
let shaped = Quota::rate(1000, Duration::from_secs(60))?.with_burst(50);
assert_eq!(shaped.limit(), 1000);
assert_eq!(shaped.burst(), 50);Implementations§
Source§impl Quota
impl Quota
Sourcepub const fn per_second(limit: u32) -> Self
pub const fn per_second(limit: u32) -> Self
A quota of limit requests per second, per key.
Infallible: a limit of 0 produces a quota that admits nothing, which
is well-defined. Use rate when you want a zero limit
rejected as an error.
§Examples
use rate_net::Quota;
use std::time::Duration;
let quota = Quota::per_second(50);
assert_eq!(quota.limit(), 50);
assert_eq!(quota.period(), Duration::from_secs(1));Sourcepub const fn per_minute(limit: u32) -> Self
pub const fn per_minute(limit: u32) -> Self
A quota of limit requests per minute, per key.
Infallible, with the same zero-limit semantics as
per_second.
§Examples
use rate_net::Quota;
use std::time::Duration;
let quota = Quota::per_minute(600);
assert_eq!(quota.period(), Duration::from_secs(60));Sourcepub const fn rate(
limit: u32,
period: Duration,
) -> Result<Self, RateLimiterError>
pub const fn rate( limit: u32, period: Duration, ) -> Result<Self, RateLimiterError>
A quota of limit requests per arbitrary period, validated.
Use this when the natural window is neither a second nor a minute — for example 5 requests per 100 milliseconds, or 10 000 per hour.
§Errors
RateLimiterError::ZeroQuotaiflimitis0.RateLimiterError::ZeroPeriodifperiodis zero.
§Examples
use rate_net::{Quota, RateLimiterError};
use std::time::Duration;
let quota = Quota::rate(5, Duration::from_millis(100))?;
assert_eq!(quota.limit(), 5);
// A zero limit is rejected.
assert_eq!(
Quota::rate(0, Duration::from_secs(1)),
Err(RateLimiterError::ZeroQuota),
);Sourcepub const fn burst(&self) -> u32
pub const fn burst(&self) -> u32
The burst ceiling: the most a key may spend at once before it must wait
for the rate to refill. Defaults to limit.
Applies to the token and leaky buckets; the window algorithms admit at
most limit per period regardless of burst.
§Examples
use rate_net::Quota;
assert_eq!(Quota::per_second(100).burst(), 100);
assert_eq!(Quota::per_second(100).with_burst(250).burst(), 250);Sourcepub const fn with_burst(self, burst: u32) -> Self
pub const fn with_burst(self, burst: u32) -> Self
Returns a copy with the burst ceiling set to burst.
§Examples
use rate_net::Quota;
// Sustain 1000/min but never let a key spend more than 50 at once.
let quota = Quota::per_minute(1000).with_burst(50);
assert_eq!(quota.limit(), 1000);
assert_eq!(quota.burst(), 50);