Struct BucketBudget 

pub struct BucketBudget {
    pub scope_key: String,
    pub fallback_key: String,
    pub max_distinct: u32,
    pub window: Duration,
}

A cap on the number of distinct bucket keys one scope may create in a window, plus where traffic beyond the cap is charged instead.

Deliberately carries the fallback bucket rather than an “and then refuse” flag: refusing past the cap would hand an attacker a deterministic, global outage of every rate-limited route — the exact failure mode cratestack#846 was fought over. Collapsing onto the fallback throttles the attacker (they now share one bucket) without giving them a lever over anyone else’s availability.

Fields

scope_key: String

Identifies the set of buckets being counted — e.g. one verified peer address. Not itself a bucket key; stores namespace it separately.

fallback_key: String

Bucket charged once the scope is at its cap. Chosen by the caller so that it is a bucket the same caller would have used anyway (the peer’s own ip: bucket), which is what makes the collapse a throttle rather than a bypass.

max_distinct: u32

How many distinct bucket keys this scope may admit while it lives.

window: Duration

Floor on how long the scope’s admission record lives; the store raises it to at least bucket_ttl_secs(config) (cratestack#871 review, blocker 2).

It is a floor rather than a fixed window because a scope that expired before the buckets it admitted did not bound anything: a fresh scope re-admits max_distinct more while the previous generation is still alive, so the real steady state was max_distinct × ceil(bucket_ttl / window) — measured at 21 buckets for a cap of 4 over five 1s windows, and ~184 320 per peer for a non-refilling bucket under the defaults. Tying the lifetime to the buckets’ own TTL makes the scope outlive everything it admitted, so the steady-state bound is max_distinct + 2 per scope.

The window slides per member: each admitted key holds a slot that expires this long after it was last used, refreshed on every hit. So an actively-used credential never loses its slot while its bucket is alive, and a peer whose credentials rotate reclaims the slots of the ones it stopped using rather than being capped at its first max_distinct forever. A shared per-scope deadline could only have one of those two properties, never both.

Implementations

impl BucketBudget

pub fn new( scope_key: impl Into<String>, fallback_key: impl Into<String>, max_distinct: u32, window: Duration, ) -> BucketBudget

Trait Implementations

impl Clone for BucketBudget

fn clone(&self) -> BucketBudget

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BucketBudget

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

Formats the value using the given formatter.

impl Eq for BucketBudget

impl PartialEq for BucketBudget

fn eq(&self, other: &BucketBudget) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for BucketBudget