[][src]Struct ratelimit_meter::state::keyed::KeyedRateLimiter

pub struct KeyedRateLimiter<K: Eq + Hash + Clone, A: Algorithm = DefaultAlgorithm, H: BuildHasher + Clone = RandomState> { /* fields omitted */ }

An in-memory rate limiter that regulates a single rate limit for multiple keys.

Keyed rate limiters can be used to e.g. enforce a per-IP address or a per-customer request limit on the server side.

This implementation of the keyed rate limiter uses evmap, a read lock-free, concurrent hash map. Addition of new keys (e.g. a new customer making their first request) is synchronized and happens one at a time (it synchronizes writes to minimize the effects from evmap's eventually consistent behavior on key addition), while reads of existing keys all happen simultaneously, then get synchronized by the rate limiting algorithm itself.

use ratelimit_meter::{KeyedRateLimiter};
let mut limiter = KeyedRateLimiter::<&str>::new(nonzero!(1u32), Duration::from_secs(5));
assert_eq!(Ok(()), limiter.check("customer1")); // allowed!
assert_ne!(Ok(()), limiter.check("customer1")); // ...but now customer1 must wait 5 seconds.

assert_eq!(Ok(()), limiter.check("customer2")); // it's customer2's first request!

Expiring old keys

If a key has not been checked in a long time, that key can be expired safely (the next rate limit check for that key would behave as if the key was not present in the map, after all). To remove the unused keys and free up space, use the cleanup method:

use ratelimit_meter::{KeyedRateLimiter};
let mut limiter = KeyedRateLimiter::<&str>::new(nonzero!(100u32), Duration::from_secs(5));
limiter.check("hi there");
// time passes...

// remove all keys that have been expireable for 10 minutes:
limiter.cleanup(Duration::from_secs(600));

Methods

impl<A, K> KeyedRateLimiter<K, A> where
    A: Algorithm,
    K: Eq + Hash + Clone
[src]

Construct a new rate limiter that allows capacity cells per time unit through.

Examples

use ratelimit_meter::{KeyedRateLimiter};
let _limiter = KeyedRateLimiter::<&str>::new(nonzero!(100u32), Duration::from_secs(5));

Construct a new keyed rate limiter that allows capacity cells per second.

Examples

Constructing a rate limiter keyed by &str that lets through 100 cells per second:

use ratelimit_meter::{KeyedRateLimiter, GCRA};
let _limiter = KeyedRateLimiter::<&str, GCRA>::per_second(nonzero!(100u32));

Return a constructor that can be used to construct a keyed rate limiter with the builder pattern.

Tests if a single cell for the given key can be accommodated at Instant::now(). If it can be, check updates the rate limiter state on that key to account for the conforming cell and returns Ok(()).

If the cell is non-conforming (i.e., it can't be accomodated at this time stamp), check_at returns Err with information about the earliest time at which a cell could be considered conforming under that key.

Tests if n cells for the given key can be accommodated at the current time stamp. If (and only if) all cells in the batch can be accomodated, the MultiDecider updates the rate limiter state on that key to account for all cells and returns Ok(()).

If the entire batch of cells would not be conforming but the rate limiter has the capacity to accomodate the cells at any point in time, check_n_at returns error NegativeMultiDecision::BatchNonConforming, holding the number of cells and the rate limiter's negative outcome result.

If n exceeds the bucket capacity, check_n_at returns NegativeMultiDecision::InsufficientCapacity, indicating that a batch of this many cells can never succeed.

Tests whether a single cell for the given key can be accommodated at the given time stamp. See check.

Tests if n cells for the given key can be accommodated at the given time (Instant::now()), using check_n

Removes the keys from this rate limiter that can be expired safely and returns the keys that were removed.

To be eligible for expiration, a key's rate limiter state must be at least min_age past its last relevance (see RateLimitState.last_touched).

This method works in two parts, but both parts block new keys from getting added while they're running:

  • First, it collects the keys that are eligible for expiration.
  • Then, it expires these keys.

Note that this only affects new keys that need to be added. Rate-limiting operations on existing keys continue concurrently.

Race conditions

Since this is happening concurrently with other operations, race conditions can & will occur. It's possible that cells are accounted between the time cleanup_at is called and their expiry. These cells will lost.

The time window in which this can occur is hopefully short enough that this is an acceptable risk of loss in accuracy.

Removes the keys from this rate limiter that can be expired safely at the given time stamp. See cleanup. It returns the list of expired keys.

Trait Implementations

impl<K: Clone + Eq + Hash + Clone, A: Clone + Algorithm, H: Clone + BuildHasher + Clone> Clone for KeyedRateLimiter<K, A, H> where
    A::BucketState: Clone
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl<A, K> Debug for KeyedRateLimiter<K, A> where
    A: Algorithm,
    K: Eq + Hash + Clone
[src]

Formats the value using the given formatter. Read more

Auto Trait Implementations

impl<K, A, H> Send for KeyedRateLimiter<K, A, H> where
    H: Send,
    K: Send,
    <A as Algorithm>::BucketState: Send

impl<K, A = LeakyBucket, H = RandomState> !Sync for KeyedRateLimiter<K, A, H>

Blanket Implementations

impl<T, U> Into for T where
    U: From<T>, 
[src]

Performs the conversion.

impl<T> ToOwned for T where
    T: Clone
[src]

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T> From for T
[src]

Performs the conversion.

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from)

Performs the conversion.

impl<T> Borrow for T where
    T: ?Sized
[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut for T where
    T: ?Sized
[src]

Mutably borrows from an owned value. Read more

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from)

Performs the conversion.

impl<T> Any for T where
    T: 'static + ?Sized
[src]

🔬 This is a nightly-only experimental API. (get_type_id)

this method will likely be replaced by an associated static

Gets the TypeId of self. Read more

impl<T> Erased for T