Getting Started

Quickstart (Hybrid)

High-throughput distributed limiting with a local fast-path and periodic Redis synchronization.

Use the hybrid provider when you want distributed limiting but cannot afford a Redis round-trip on every request.

Add the dependencies

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

Create the limiter

Hybrid uses the same Redis-aware builder as the Redis provider. The main extra knob is sync_interval_ms, which controls how often local increments are flushed to Redis.

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)
    .sync_interval_ms(10)
    .build()
    .unwrap();

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

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

Inspect suppression state

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).sync_interval_ms(10).build().unwrap();
let key = RedisKey::try_from("user_123".to_string()).unwrap();
let rate = RateLimit::try_from(10.0).unwrap();

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

assert!(factor >= 0.0);

What to expect

Most admission decisions are served from local state.
Redis is updated periodically instead of per request.
Lower sync_interval_ms reduces lag but increases Redis load.
Higher sync_interval_ms increases throughput but allows more temporary divergence from Redis.

When to choose Hybrid

Choose hybrid for high-throughput distributed paths where local latency matters more than seeing Redis state on every call.

If you need each decision to go directly to shared remote state, use the Redis provider instead.

Next steps

Quickstart (Redis)

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

Keys

Keys define the subject being rate limited, from a user or API key to a tenant or route.