actix_trypema/lib.rs
1//! actix-web middleware for the [trypema](https://docs.rs/trypema) sliding-window rate limiter.
2//!
3//! One middleware covers every trypema backend: local (in process), Redis (exact limits shared
4//! across instances) and hybrid (shared through a local fast path), with either strategy
5//! (absolute allow/reject or probabilistic suppression). The backend is trypema's own provider
6//! or limiter, in an `Arc`. Keys, rates, request costs, headers, rejection responses and backend
7//! failure handling are set per middleware instance.
8//!
9//! This version needs trypema 3.1. It re-exports [`trypema`], so
10//! `actix_trypema::trypema::RateLimiterBuilder` is the trypema version this crate uses.
11//!
12//! The [actix-web guide](https://trypema.davidoyinbo.com/actix-web) covers every option with
13//! examples.
14//!
15//! # Quick start
16//!
17//! ```
18//! use std::sync::Arc;
19//!
20//! use actix_trypema::{TrypemaLimiter, extract::PeerIp};
21//! use actix_trypema::trypema::{RateLimit, RateLimiterBuilder, WindowSize, local::AbsoluteLocalRateLimiter};
22//! use actix_web::{App, web};
23//!
24//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
25//! // Build the backend ONCE, outside HttpServer::new: inside the server closure every worker
26//! // would get its own limiter, multiplying the effective limit by the worker count.
27//! let backend: Arc<AbsoluteLocalRateLimiter> = RateLimiterBuilder::local()
28//! .window_size(WindowSize::seconds_or_panic(60))
29//! .build()?;
30//!
31//! let limiter = TrypemaLimiter::builder(backend)
32//! .namespace("ip")
33//! .extractor(PeerIp::default())
34//! .rate(RateLimit::per_second_or_panic(10.0))
35//! .build()?;
36//!
37//! let app = App::new()
38//! .wrap(limiter.clone())
39//! .route("/", web::get().to(|| async { "hello" }));
40//! # let _ = app;
41//! # Ok(())
42//! # }
43//! ```
44//!
45//! Requests over the limit get `429 Too Many Requests` with `retry-after`, and never reach the
46//! handler. Every limiter needs a backend, an extractor, a rate and a namespace
47//! (`[a-z0-9-]{1,32}`), which keeps limiters sharing a backend apart.
48//! [`build`](TrypemaLimiterBuilder::build) reports configuration mistakes as a [`ConfigError`].
49//!
50//! # Backends
51//!
52//! A backend is an `Arc` of a trypema provider or of one trypema limiter. Build it with
53//! trypema's `RateLimiterBuilder`: `local()`, `redis(connection)` or `hybrid(connection)`, then
54//! the window and other settings, then `build()` with the type you want.
55//!
56//! | Backend | Feature | Provider (both strategies) | Single limiters | Shared across instances |
57//! |---|---|---|---|---|
58//! | Local | none | `LocalRateLimiterProvider` | `AbsoluteLocalRateLimiter`, `SuppressedLocalRateLimiter` | No: each process counts on its own. |
59//! | Redis | `redis` | `RedisRateLimiterProvider` | `AbsoluteRedisRateLimiter`, `SuppressedRedisRateLimiter` | Yes, exactly; one Redis round trip per request. |
60//! | Hybrid | `redis` | `HybridRateLimiterProvider` | `AbsoluteHybridRateLimiter`, `SuppressedHybridRateLimiter` | Yes, eventually; most requests are decided from local state. |
61//!
62//! With a provider, [`strategy`](TrypemaLimiterBuilder::strategy) chooses the strategy (absolute
63//! by default). A single limiter runs its own strategy, and its builder has no `strategy`. A
64//! limiter and a provider with the same Redis prefix share their counts.
65//!
66//! Redis and hybrid calls are bounded by `backend_timeout`, and failures follow
67//! [`BackendErrorPolicy`]: fail open (the default), fail closed, fall back to a local provider,
68//! or decide per failure.
69//!
70//! A Redis backend gives an exact limit across instances. Every instance that uses the same
71//! Redis and prefix shares the count. This login limit fails closed, so a Redis outage rejects
72//! logins:
73//!
74//! ```no_run
75//! # #[cfg(feature = "redis")]
76//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
77//! use std::{sync::Arc, time::Duration};
78//!
79//! use actix_trypema::{BackendErrorPolicy, TrypemaLimiter, extract::PeerIp};
80//! use actix_trypema::trypema::{
81//! RateLimit, RateLimiterBuilder, WindowSize,
82//! redis::{AbsoluteRedisRateLimiter, RedisKey},
83//! };
84//! use actix_web::{App, web};
85//!
86//! let connection = redis::Client::open("redis://127.0.0.1:6379/")?
87//! .get_connection_manager()
88//! .await?;
89//!
90//! let backend: Arc<AbsoluteRedisRateLimiter> = RateLimiterBuilder::redis(connection)
91//! .prefix(RedisKey::try_from("auth")?)
92//! .window_size(WindowSize::minutes_or_panic(1))
93//! .build()?;
94//!
95//! let limiter = TrypemaLimiter::builder(backend)
96//! .namespace("login")
97//! .extractor(PeerIp::default())
98//! .rate(RateLimit::per_minute_or_panic(5.0))
99//! .on_backend_error(BackendErrorPolicy::FailClosed)
100//! .backend_timeout(Duration::from_millis(100))
101//! .build()?;
102//!
103//! let app = App::new().service(
104//! web::resource("/login")
105//! .wrap(limiter.clone())
106//! .route(web::post().to(|| async { "login" })),
107//! );
108//! # let _ = app;
109//! # Ok(())
110//! # }
111//! ```
112//!
113//! A hybrid backend decides most requests from local state and sends the counts to Redis at
114//! each sync interval. This API limit falls back to a local provider on the same window while
115//! Redis is not available, so each instance then limits on its own:
116//!
117//! ```no_run
118//! # #[cfg(feature = "redis")]
119//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
120//! use std::sync::Arc;
121//!
122//! use actix_trypema::{BackendErrorPolicy, TrypemaLimiter, extract::PeerIp};
123//! use actix_trypema::trypema::{
124//! RateLimit, RateLimiterBuilder, WindowSize,
125//! hybrid::{AbsoluteHybridRateLimiter, SyncInterval},
126//! local::LocalRateLimiterProvider,
127//! redis::RedisKey,
128//! };
129//! use actix_web::{App, web};
130//!
131//! let window = WindowSize::minutes_or_panic(1);
132//! let connection = redis::Client::open("redis://127.0.0.1:6379/")?
133//! .get_connection_manager()
134//! .await?;
135//!
136//! let backend: Arc<AbsoluteHybridRateLimiter> = RateLimiterBuilder::hybrid(connection)
137//! .prefix(RedisKey::try_from("api")?)
138//! .window_size(window)
139//! .sync_interval(SyncInterval::milliseconds_or_panic(50))
140//! .build()?;
141//!
142//! let fallback: Arc<LocalRateLimiterProvider> = RateLimiterBuilder::local()
143//! .window_size(window)
144//! .build()?;
145//!
146//! let limiter = TrypemaLimiter::builder(backend)
147//! .namespace("api")
148//! .extractor(PeerIp::default())
149//! .rate(RateLimit::per_minute_or_panic(600.0))
150//! .on_backend_error(BackendErrorPolicy::Fallback(fallback))
151//! .build()?;
152//!
153//! let app = App::new()
154//! .wrap(limiter.clone())
155//! .route("/", web::get().to(|| async { "hello" }));
156//! # let _ = app;
157//! # Ok(())
158//! # }
159//! ```
160//!
161//! # Keys
162//!
163//! The [`extract`] module decides who a request counts against:
164//!
165//! - [`PeerIp`](extract::PeerIp) keys by the TCP peer, grouping IPv6 clients by `/64`.
166//! - [`RealIp`](extract::RealIp) reads `X-Forwarded-For`, RFC 7239 `Forwarded` or a CDN header,
167//! but only when the TCP peer is one of your [`TrustedProxies`](extract::TrustedProxies).
168//! - [`Header`](extract::Header) keys by a header such as an API key, optionally hashed.
169//! - [`Global`](extract::Global) puts every request in one bucket, and
170//! [`Composite`](extract::Composite) joins two extractors.
171//! - [`extractor_fn`](TrypemaLimiterBuilder::extractor_fn) takes a closure, and
172//! [`KeyExtractor`](extract::KeyExtractor) is the trait for your own extractors.
173//!
174//! ```
175//! use std::sync::Arc;
176//!
177//! use actix_trypema::{KeyError, TrypemaLimiter, extract::{RealIp, TrustedProxies}};
178//! use actix_trypema::trypema::{RateLimit, RateLimiterBuilder, WindowSize, local::LocalRateLimiterProvider};
179//! use actix_web::HttpMessage;
180//!
181//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
182//! let backend: Arc<LocalRateLimiterProvider> = RateLimiterBuilder::local()
183//! .window_size(WindowSize::seconds_or_panic(60))
184//! .build()?;
185//!
186//! // Behind load balancers in 10.0.0.0/16: the client is the first untrusted address in
187//! // X-Forwarded-For, read from the right. Other peers are keyed by their own address.
188//! let per_ip = TrypemaLimiter::builder(backend.clone())
189//! .namespace("ip")
190//! .extractor(RealIp::xff(TrustedProxies::new(["10.0.0.0/16"])?))
191//! .rate(RateLimit::per_minute_or_panic(600.0))
192//! .build()?;
193//!
194//! /// Inserted by your authentication middleware.
195//! #[derive(Clone)]
196//! struct UserId(u64);
197//!
198//! // A custom key: the authenticated user. Wrap this limiter inside the authentication layer.
199//! let per_user = TrypemaLimiter::builder(backend)
200//! .namespace("user")
201//! .extractor_fn(|req| {
202//! req.extensions()
203//! .get::<UserId>()
204//! .map(|user| user.0.to_string())
205//! .ok_or(KeyError::InvalidValue { reason: "request is not authenticated" })
206//! })
207//! .rate(RateLimit::per_minute_or_panic(300.0))
208//! .build()?;
209//! # let _ = (per_ip, per_user);
210//! # Ok(())
211//! # }
212//! ```
213//!
214//! When extraction fails, [`KeyErrorPolicy`] decides: reject with `400` (the default), bypass, or
215//! count the request in one shared bucket.
216//!
217//! # Limits and responses
218//!
219//! [`rate_fn`](TrypemaLimiterBuilder::rate_fn) sets per-request rates such as plan tiers (rates
220//! are sticky per key, so put the tier in the key), [`cost_fn`](TrypemaLimiterBuilder::cost_fn)
221//! charges expensive requests more, [`exclude`](TrypemaLimiterBuilder::exclude) skips requests,
222//! and the suppressed strategy sheds load gradually. [`HeaderMode`] picks the rate limit headers,
223//! and a [`RejectionResponder`] builds the rejection body.
224//!
225//! [`permissive`](TrypemaLimiterBuilder::permissive) runs a limiter in shadow mode, and handlers
226//! read each decision through [`RateLimitInfo`]. [`derived_key`] returns the key a limiter
227//! stores, for resetting or re-rating one client through your backend value.
228//!
229//! # Middleware placement
230//!
231//! `App::wrap` runs middleware in reverse registration order: the last `.wrap(..)` runs first.
232//! Put IP-keyed limiters outermost, before authentication, so unauthenticated floods are
233//! limited. Put identity-keyed limiters (API key, user id) after the authentication layer that
234//! validates the identity. Path parameters are visible to limiters that wrap the scope or
235//! resource declaring them. An `exclude` predicate sees the path as this middleware receives
236//! it, so register `NormalizePath` to run before the limiter when exclusions rely on
237//! normalized paths.
238//!
239//! # Feature flags
240//!
241//! - `redis`: the Redis and hybrid backends (two providers and four limiters), on trypema's
242//! tokio Redis client (the runtime actix-web runs on). It turns on `trypema/redis-tokio`.
243//! - `json`: a JSON rejection responder.
244//! - `metrics`: decision counters through the `metrics` facade — every request counts one of
245//! admitted, rejected, or bypassed, and backend failures also count as errors — plus a
246//! latency histogram for backend calls that await Redis.
247
248#![cfg_attr(docsrs, feature(doc_cfg))]
249#![deny(missing_docs)]
250#![forbid(unsafe_code)]
251
252#[cfg(feature = "redis")]
253mod async_middleware;
254mod backend;
255mod builder;
256mod client_ip;
257mod error;
258pub mod extract;
259mod key;
260mod middleware;
261mod outcome;
262mod response;
263
264pub use trypema;
265
266#[cfg(feature = "redis")]
267pub use backend::AsyncBackend;
268pub use backend::{Backend, ProviderBackend};
269pub use builder::{HeaderMode, Strategy, TrypemaLimiter, TrypemaLimiterBuilder};
270pub use error::{
271 BackendErrorPolicy, BackendFailure, ConfigError, ErrorAction, KeyError, KeyErrorPolicy,
272};
273pub use key::derived_key;
274pub use middleware::{LimiterFuture, TrypemaMiddleware};
275pub use outcome::{LimitOutcome, RateLimitInfo};
276#[cfg(feature = "json")]
277pub use response::JsonResponder;
278pub use response::{DefaultResponder, RejectionInfo, RejectionResponder};
279
280#[cfg(test)]
281mod tests;