Module governor::middleware

Additional, customizable behavior for rate limiters.

Rate-limiting middleware follows the principle that basic rate-limiting should be very cheap, and unless users desire more behavior, they should not pay any extra price.

However, if you do desire more information about what the rate-limiter does (or the ability to install hooks in the decision-making process), you can. The RateLimitingMiddleware trait in this module allows you to customize:

• Any additional code that gets run when a rate-limiting decision is made.
• What value is returned in the positive or negative case.

Writing middleware does not let you override rate-limiting decisions: They remain either positive (returning Ok) or negative (returning Err). However, you can override the values returned inside the Result for either decision.

This crate ships two middlewares (named after their behavior in the positive outcome):

• The cheapest still-useful one, NoOpMiddleware, named after its behavior in the positive case. In the positive case it returns Ok(()); in the negative case, Err(NotUntil).

• A more informative middleware, StateInformationMiddleware, which returns Ok(StateSnapshot), or Err(NotUntil).

Using a custom middleware

Middlewares are attached to the RateLimiter at construction time using RateLimiter::with_middleware:

use governor::{RateLimiter, Quota, middleware::StateInformationMiddleware};
let lim = RateLimiter::direct(Quota::per_hour(nonzero!(1_u32)))
    .with_middleware::<StateInformationMiddleware>();

// A positive outcome with additional information:
assert!(
    lim.check()
        // Here we receive an Ok(StateSnapshot):
        .map(|outcome| assert_eq!(outcome.remaining_burst_capacity(), 0))
        .is_ok()
);

// The negative case:
assert!(
    lim.check()
        // Here we receive Err(NotUntil):
        .map_err(|outcome| assert_eq!(outcome.quota().burst_size().get(), 1))
        .is_err()
);

You can define your own middleware by impling RateLimitingMiddleware.

Structs

• NoOpMiddleware
  A middleware that does nothing and returns () in the positive outcome.
• StateInformationMiddleware
  Middleware that returns the state of the rate limiter if a positive decision is reached.
• StateSnapshot
  Information about the rate-limiting state used to reach a decision.

Traits

• RateLimitingMiddleware
  Defines the behavior and return values of rate limiting decisions.