Getting Started

Quickstart (Redis)

Shared rate limits across processes and servers with one Redis round-trip per check.

Use the Redis provider when multiple instances must see the same limiter state and you want each decision to go straight to Redis.

Add the dependencies

[dependencies]
trypema = { version = "1", features = ["redis-tokio"] }
redis = { version = "1", features = ["aio", "tokio-comp", "connection-manager"] }
tokio = { version = "1", features = ["full"] }

Redis-backed providers require Redis 7.2+ and exactly one runtime feature: redis-tokio or redis-smol.

For Redis-enabled builds, RateLimiter::builder(connection_manager) is the ergonomic setup path. The builder owns the Redis connection configuration up front and build() starts cleanup automatically.

use trypema::{RateLimit, RateLimitDecision, RateLimiter};
use trypema::redis::RedisKey;

let client = redis::Client::open("redis://127.0.0.1:6379/").unwrap();
let connection_manager = client.get_connection_manager().await.unwrap();

let rl = RateLimiter::builder(connection_manager)
    .window_size_seconds(60)
    .rate_group_size_ms(10)
    .hard_limit_factor(1.5)
    .build()
    .unwrap();

let key = RedisKey::try_from("user_123".to_string()).unwrap();
let rate = RateLimit::try_from(5.0).unwrap();

assert!(matches!(
    rl.redis().absolute().inc(&key, &rate, 1).await.unwrap(),
    RateLimitDecision::Allowed
));

Inspect suppression state

Redis and hybrid use RedisKey, and their methods are async because they can touch Redis.

use trypema::{RateLimit, RateLimiter};
use trypema::redis::RedisKey;

let client = redis::Client::open("redis://127.0.0.1:6379/").unwrap();
let connection_manager = client.get_connection_manager().await.unwrap();

let rl = RateLimiter::builder(connection_manager).build().unwrap();
let key = RedisKey::try_from("user_123".to_string()).unwrap();
let rate = RateLimit::try_from(5.0).unwrap();

let _ = rl.redis().suppressed().inc(&key, &rate, 1).await.unwrap();
let factor = rl.redis().suppressed().get_suppression_factor(&key).await.unwrap();

assert!(factor >= 0.0);

What changes compared with local

Topic	Local	Redis
Key type	`&str`	`RedisKey`
Methods	synchronous	async
State	one process	shared through Redis
Latency	lowest	one network round-trip per call

When to choose Redis

Choose Redis when correctness should track shared remote state as closely as this crate offers, and the extra network cost per call is acceptable.

If that Redis round-trip is too expensive, the next page is usually the better fit.

Next steps

Quickstart (Local)

[object Object]

Quickstart (Hybrid)