Skip to main content

Crate actix_trypema

Crate actix_trypema 

Source
Expand description

actix-web middleware for the trypema sliding-window rate limiter.

One middleware covers every trypema backend: local (in process), Redis (exact limits shared across instances) and hybrid (shared through a local fast path), with either strategy (absolute allow/reject or probabilistic suppression). The backend is trypema’s own provider or limiter, in an Arc. Keys, rates, request costs, headers, rejection responses and backend failure handling are set per middleware instance.

This version needs trypema 3.1. It re-exports trypema, so actix_trypema::trypema::RateLimiterBuilder is the trypema version this crate uses.

The actix-web guide covers every option with examples.

§Quick start

use std::sync::Arc;

use actix_trypema::{TrypemaLimiter, extract::PeerIp};
use actix_trypema::trypema::{RateLimit, RateLimiterBuilder, WindowSize, local::AbsoluteLocalRateLimiter};
use actix_web::{App, web};

// Build the backend ONCE, outside HttpServer::new: inside the server closure every worker
// would get its own limiter, multiplying the effective limit by the worker count.
let backend: Arc<AbsoluteLocalRateLimiter> = RateLimiterBuilder::local()
    .window_size(WindowSize::seconds_or_panic(60))
    .build()?;

let limiter = TrypemaLimiter::builder(backend)
    .namespace("ip")
    .extractor(PeerIp::default())
    .rate(RateLimit::per_second_or_panic(10.0))
    .build()?;

let app = App::new()
    .wrap(limiter.clone())
    .route("/", web::get().to(|| async { "hello" }));

Requests over the limit get 429 Too Many Requests with retry-after, and never reach the handler. Every limiter needs a backend, an extractor, a rate and a namespace ([a-z0-9-]{1,32}), which keeps limiters sharing a backend apart. build reports configuration mistakes as a ConfigError.

§Backends

A backend is an Arc of a trypema provider or of one trypema limiter. Build it with trypema’s RateLimiterBuilder: local(), redis(connection) or hybrid(connection), then the window and other settings, then build() with the type you want.

BackendFeatureProvider (both strategies)Single limitersShared across instances
LocalnoneLocalRateLimiterProviderAbsoluteLocalRateLimiter, SuppressedLocalRateLimiterNo: each process counts on its own.
RedisredisRedisRateLimiterProviderAbsoluteRedisRateLimiter, SuppressedRedisRateLimiterYes, exactly; one Redis round trip per request.
HybridredisHybridRateLimiterProviderAbsoluteHybridRateLimiter, SuppressedHybridRateLimiterYes, eventually; most requests are decided from local state.

With a provider, strategy chooses the strategy (absolute by default). A single limiter runs its own strategy, and its builder has no strategy. A limiter and a provider with the same Redis prefix share their counts.

Redis and hybrid calls are bounded by backend_timeout, and failures follow BackendErrorPolicy: fail open (the default), fail closed, fall back to a local provider, or decide per failure.

A Redis backend gives an exact limit across instances. Every instance that uses the same Redis and prefix shares the count. This login limit fails closed, so a Redis outage rejects logins:

use std::{sync::Arc, time::Duration};

use actix_trypema::{BackendErrorPolicy, TrypemaLimiter, extract::PeerIp};
use actix_trypema::trypema::{
    RateLimit, RateLimiterBuilder, WindowSize,
    redis::{AbsoluteRedisRateLimiter, RedisKey},
};
use actix_web::{App, web};

let connection = redis::Client::open("redis://127.0.0.1:6379/")?
    .get_connection_manager()
    .await?;

let backend: Arc<AbsoluteRedisRateLimiter> = RateLimiterBuilder::redis(connection)
    .prefix(RedisKey::try_from("auth")?)
    .window_size(WindowSize::minutes_or_panic(1))
    .build()?;

let limiter = TrypemaLimiter::builder(backend)
    .namespace("login")
    .extractor(PeerIp::default())
    .rate(RateLimit::per_minute_or_panic(5.0))
    .on_backend_error(BackendErrorPolicy::FailClosed)
    .backend_timeout(Duration::from_millis(100))
    .build()?;

let app = App::new().service(
    web::resource("/login")
        .wrap(limiter.clone())
        .route(web::post().to(|| async { "login" })),
);

A hybrid backend decides most requests from local state and sends the counts to Redis at each sync interval. This API limit falls back to a local provider on the same window while Redis is not available, so each instance then limits on its own:

use std::sync::Arc;

use actix_trypema::{BackendErrorPolicy, TrypemaLimiter, extract::PeerIp};
use actix_trypema::trypema::{
    RateLimit, RateLimiterBuilder, WindowSize,
    hybrid::{AbsoluteHybridRateLimiter, SyncInterval},
    local::LocalRateLimiterProvider,
    redis::RedisKey,
};
use actix_web::{App, web};

let window = WindowSize::minutes_or_panic(1);
let connection = redis::Client::open("redis://127.0.0.1:6379/")?
    .get_connection_manager()
    .await?;

let backend: Arc<AbsoluteHybridRateLimiter> = RateLimiterBuilder::hybrid(connection)
    .prefix(RedisKey::try_from("api")?)
    .window_size(window)
    .sync_interval(SyncInterval::milliseconds_or_panic(50))
    .build()?;

let fallback: Arc<LocalRateLimiterProvider> = RateLimiterBuilder::local()
    .window_size(window)
    .build()?;

let limiter = TrypemaLimiter::builder(backend)
    .namespace("api")
    .extractor(PeerIp::default())
    .rate(RateLimit::per_minute_or_panic(600.0))
    .on_backend_error(BackendErrorPolicy::Fallback(fallback))
    .build()?;

let app = App::new()
    .wrap(limiter.clone())
    .route("/", web::get().to(|| async { "hello" }));

§Keys

The extract module decides who a request counts against:

  • PeerIp keys by the TCP peer, grouping IPv6 clients by /64.
  • RealIp reads X-Forwarded-For, RFC 7239 Forwarded or a CDN header, but only when the TCP peer is one of your TrustedProxies.
  • Header keys by a header such as an API key, optionally hashed.
  • Global puts every request in one bucket, and Composite joins two extractors.
  • extractor_fn takes a closure, and KeyExtractor is the trait for your own extractors.
use std::sync::Arc;

use actix_trypema::{KeyError, TrypemaLimiter, extract::{RealIp, TrustedProxies}};
use actix_trypema::trypema::{RateLimit, RateLimiterBuilder, WindowSize, local::LocalRateLimiterProvider};
use actix_web::HttpMessage;

let backend: Arc<LocalRateLimiterProvider> = RateLimiterBuilder::local()
    .window_size(WindowSize::seconds_or_panic(60))
    .build()?;

// Behind load balancers in 10.0.0.0/16: the client is the first untrusted address in
// X-Forwarded-For, read from the right. Other peers are keyed by their own address.
let per_ip = TrypemaLimiter::builder(backend.clone())
    .namespace("ip")
    .extractor(RealIp::xff(TrustedProxies::new(["10.0.0.0/16"])?))
    .rate(RateLimit::per_minute_or_panic(600.0))
    .build()?;

/// Inserted by your authentication middleware.
#[derive(Clone)]
struct UserId(u64);

// A custom key: the authenticated user. Wrap this limiter inside the authentication layer.
let per_user = TrypemaLimiter::builder(backend)
    .namespace("user")
    .extractor_fn(|req| {
        req.extensions()
            .get::<UserId>()
            .map(|user| user.0.to_string())
            .ok_or(KeyError::InvalidValue { reason: "request is not authenticated" })
    })
    .rate(RateLimit::per_minute_or_panic(300.0))
    .build()?;

When extraction fails, KeyErrorPolicy decides: reject with 400 (the default), bypass, or count the request in one shared bucket.

§Limits and responses

rate_fn sets per-request rates such as plan tiers (rates are sticky per key, so put the tier in the key), cost_fn charges expensive requests more, exclude skips requests, and the suppressed strategy sheds load gradually. HeaderMode picks the rate limit headers, and a RejectionResponder builds the rejection body.

permissive runs a limiter in shadow mode, and handlers read each decision through RateLimitInfo. derived_key returns the key a limiter stores, for resetting or re-rating one client through your backend value.

§Middleware placement

App::wrap runs middleware in reverse registration order: the last .wrap(..) runs first. Put IP-keyed limiters outermost, before authentication, so unauthenticated floods are limited. Put identity-keyed limiters (API key, user id) after the authentication layer that validates the identity. Path parameters are visible to limiters that wrap the scope or resource declaring them. An exclude predicate sees the path as this middleware receives it, so register NormalizePath to run before the limiter when exclusions rely on normalized paths.

§Feature flags

  • redis: the Redis and hybrid backends (two providers and four limiters), on trypema’s tokio Redis client (the runtime actix-web runs on). It turns on trypema/redis-tokio.
  • json: a JSON rejection responder.
  • metrics: decision counters through the metrics facade — every request counts one of admitted, rejected, or bypassed, and backend failures also count as errors — plus a latency histogram for backend calls that await Redis.

Re-exports§

pub use trypema;

Modules§

extract
Key extraction: who a request is rate-limited as.

Structs§

DefaultResponder
The default responder: text/plain, Too many requests, retry in {n}s.
JsonResponderjson
A JSON responder: {"error": "rate_limited", "namespace", "retry_after_seconds"}.
LimiterFuture
The middleware’s service future.
RateLimitInfo
Extractor giving handlers the LimitOutcomes recorded for the request.
RejectionInfo
Everything a rejection response can say about why it happened.
TrypemaLimiter
The middleware factory: wrap it with App::wrap or Scope::wrap.
TrypemaLimiterBuilder
Configures one TrypemaLimiter instance.
TrypemaMiddleware
The middleware service produced by wrapping a TrypemaLimiter.

Enums§

BackendErrorPolicy
What to do when a Redis or hybrid backend call fails or times out.
BackendFailure
Why a Redis or hybrid backend call failed.
ConfigError
An invalid middleware configuration, reported by build() and validated constructors.
ErrorAction
The decision a BackendErrorPolicy::Custom function returns.
HeaderMode
Which rate limit headers responses carry. Bypassed requests never carry any.
KeyError
A key-extraction failure, handled according to KeyErrorPolicy.
KeyErrorPolicy
What to do when key extraction fails.
LimitOutcome
What one middleware instance decided for the current request.
Strategy
Which trypema strategy admits requests.

Traits§

AsyncBackendredis
The Redis and hybrid backends: decided through Redis, under a timeout. Sealed.
Backend
A trypema provider or limiter the middleware can drive, in an Arc.
ProviderBackend
A backend that holds both strategies: a trypema provider.
RejectionResponder
Builds rejection responses.

Functions§

derived_key
Compute the key the middleware stores state under, for operator access.