Algorithm

tokio_rate_limit::algorithm

Trait Algorithm 

Source 
pub trait Algorithm:
    Send
    + Sync
    + Sealed {
    // Required method
    fn check<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<RateLimitDecision>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided method
    fn check_with_cost<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        cost: u64,
    ) -> Pin<Box<dyn Future<Output = Result<RateLimitDecision>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
}
Expand description

Trait for rate limiting algorithms.

Implementations of this trait define how rate limiting decisions are made. The trait is async to allow for potential I/O operations in custom implementations.

§Sealed Trait

This trait is sealed and cannot be implemented outside of this crate. This design allows us to add new methods or change the trait in minor version updates without breaking semver guarantees. If you need a custom algorithm, please open an issue to discuss adding it to the library.

§Available Algorithms

  • TokenBucket - Allows bursts up to capacity, refills at constant rate (zero-copy optimized in v0.4.0)
  • LeakyBucket - Enforces steady rate, smooths traffic (v0.3.0)
  • CachedTokenBucket - Thread-local cached token bucket for hot-key workloads (v0.4.0)

§Future Algorithms

  • Sliding Window - More precise rate limiting

Required Methods§

Source

fn check<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<RateLimitDecision>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Checks if a request for the given key should be permitted.

§Arguments
  • key - A string identifier for the client/resource being rate limited
§Returns

A RateLimitDecision indicating whether the request is permitted and additional metadata about the rate limit status.

Provided Methods§

Source

fn check_with_cost<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, cost: u64, ) -> Pin<Box<dyn Future<Output = Result<RateLimitDecision>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Checks if a request with the given cost should be permitted.

Cost represents the number of tokens to consume. The default implementation uses a cost of 1 (equivalent to check()), but algorithms can override this to support weighted rate limiting.

§Arguments
  • key - A string identifier for the client/resource being rate limited
  • cost - Number of tokens to consume (must be > 0)
§Returns

A RateLimitDecision indicating whether the request is permitted and additional metadata about the rate limit status.

§Default Behavior

The default implementation rejects requests with cost > 1 if there aren’t enough remaining tokens. Algorithms should override this for proper weighted rate limiting support.

Implementors§