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.
| Backend | Feature | Provider (both strategies) | Single limiters | Shared across instances |
|---|---|---|---|---|
| Local | none | LocalRateLimiterProvider | AbsoluteLocalRateLimiter, SuppressedLocalRateLimiter | No: each process counts on its own. |
| Redis | redis | RedisRateLimiterProvider | AbsoluteRedisRateLimiter, SuppressedRedisRateLimiter | Yes, exactly; one Redis round trip per request. |
| Hybrid | redis | HybridRateLimiterProvider | AbsoluteHybridRateLimiter, SuppressedHybridRateLimiter | Yes, 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:
PeerIpkeys by the TCP peer, grouping IPv6 clients by/64.RealIpreadsX-Forwarded-For, RFC 7239Forwardedor a CDN header, but only when the TCP peer is one of yourTrustedProxies.Headerkeys by a header such as an API key, optionally hashed.Globalputs every request in one bucket, andCompositejoins two extractors.extractor_fntakes a closure, andKeyExtractoris 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 ontrypema/redis-tokio.json: a JSON rejection responder.metrics: decision counters through themetricsfacade — 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§
- Default
Responder - The default responder:
text/plain,Too many requests, retry in {n}s. - Json
Responder json - A JSON responder:
{"error": "rate_limited", "namespace", "retry_after_seconds"}. - Limiter
Future - The middleware’s service future.
- Rate
Limit Info - Extractor giving handlers the
LimitOutcomes recorded for the request. - Rejection
Info - Everything a rejection response can say about why it happened.
- Trypema
Limiter - The middleware factory: wrap it with
App::wraporScope::wrap. - Trypema
Limiter Builder - Configures one
TrypemaLimiterinstance. - Trypema
Middleware - The middleware service produced by wrapping a
TrypemaLimiter.
Enums§
- Backend
Error Policy - What to do when a Redis or hybrid backend call fails or times out.
- Backend
Failure - Why a Redis or hybrid backend call failed.
- Config
Error - An invalid middleware configuration, reported by
build()and validated constructors. - Error
Action - The decision a
BackendErrorPolicy::Customfunction returns. - Header
Mode - Which rate limit headers responses carry. Bypassed requests never carry any.
- KeyError
- A key-extraction failure, handled according to
KeyErrorPolicy. - KeyError
Policy - What to do when key extraction fails.
- Limit
Outcome - What one middleware instance decided for the current request.
- Strategy
- Which trypema strategy admits requests.
Traits§
- Async
Backend redis - 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. - Provider
Backend - A backend that holds both strategies: a trypema provider.
- Rejection
Responder - Builds rejection responses.
Functions§
- derived_
key - Compute the key the middleware stores state under, for operator access.