Introduction
Trypema is a Rust rate limiting library for enforcing per-key request rates with either local (in-process) state or Redis-backed shared state for multi-instance deployments.
These docs target Trypema v1.0.
When to use Trypema
Use Trypema when you want a small, composable primitive you can call from HTTP middleware (per user/IP/endpoint), worker queues (per tenant/job type), or internal clients (protect downstream dependencies).
Providers and strategies
You pick a provider (where state lives) and a strategy (how to behave near/over the target rate):
| Choice | Options | When to use |
|---|---|---|
| Provider | Local | Single-process, lowest latency, no shared limits |
| Provider | Redis | Shared limits across multiple processes/hosts |
| Strategy | Absolute | Predictable hard rejection when over limit |
| Strategy | Suppressed | Graceful degradation near capacity, with a hard cutoff |
What you get
Two providers (Local, Redis), two strategies (Absolute, Suppressed), and rejection hints (retry_after_ms, remaining_after_waiting).
- Local limiting can temporarily overshoot under high contention.
- Redis absolute
inc(...)performs the admission check and increment inside a single Lua script. - For any provider, a separate
is_allowed(...)check followed by a laterinc(...)call is not atomic.
A quick decision guide
| If you want... | Start with |
|---|---|
| Single instance + predictable behavior | Local + Absolute |
| Multiple instances + predictable behavior | Redis + Absolute |
| Graceful degradation under spikes | Suppressed (Local or Redis) |
Key design tips
Keys define your isolation boundary. Prefer stable keys, keep cardinality bounded (avoid attacker-controlled explosions), and include enough scope to debug (e.g. tenant_42 or route_search).
If you may see many unique keys over time, enable the cleanup loop to evict inactive keys.
Where to start
If you want predictable rejection, start with Absolute. If you want graceful degradation, use Suppressed. If you run more than one instance, use the Redis provider.