Introduction
What is Trypema?
Trypema is a Rust rate limiting library that supports both in-process and Redis-backed distributed enforcement. It provides two complementary strategies -- strict enforcement and probabilistic suppression -- across three provider backends.
The name
The name Trypema is derived from the Koine Greek word "trypematos" (Greek: τρυπήματος), meaning "hole" or "opening." It appears in the phrase "dia trypematos raphidos" ("through the eye of a needle"), spoken by Jesus in three of the four Gospels:
- Matthew 19:24 -- "Again I tell you, it is easier for a camel to go through the eye of a needle than for someone who is rich to enter the kingdom of God."
- Mark 10:25 -- "It is easier for a camel to go through the eye of a needle than for someone who is rich to enter the kingdom of God."
- Luke 18:25 -- "Indeed, it is easier for a camel to go through the eye of a needle than for someone who is rich to enter the kingdom of God."
Just as the eye of a needle is a narrow passage that restricts what can pass through, a rate limiter is a narrow gate that controls the flow of requests into a system.
Providers
Trypema organises rate limiting into three providers, each suited to different deployment scenarios:
| Provider | Backend | Latency | Consistency | Use case |
|---|---|---|---|---|
| Local | In-process DashMap + atomics | Sub-microsecond | Single-process only | CLI tools, single-server APIs |
| Redis | Redis 6.2+ via Lua scripts | Network round-trip per call | Distributed (best-effort) | Multi-process / multi-server |
| Hybrid | Local fast-path + periodic Redis sync | Sub-microsecond (fast-path) | Distributed with sync lag | High-throughput distributed APIs |
Learn more about each provider: Local, Redis, Hybrid.
Strategies
Each provider exposes two strategies that determine how rate limit decisions are made:
- Absolute -- A deterministic sliding-window limiter. Requests under the window capacity are allowed; requests over it are immediately rejected. Simple and predictable. Learn more.
- Suppressed -- A probabilistic strategy inspired by Ably's distributed rate limiting approach. Instead of a hard cutoff, it computes a suppression factor and probabilistically denies a fraction of requests proportional to how far over the limit the key is. This produces smooth degradation rather than a cliff-edge rejection. Learn more.
Key capabilities
- Non-integer rate limits (e.g.,
0.5or5.5requests per second) - Sliding time windows for smooth burst handling (no fixed-window boundary resets)
- Configurable bucket coalescing to trade timing precision for lower overhead
- Automatic background cleanup of stale keys (with
Weakreference -- no leak risk) - Best-effort rejection metadata (
retry_after_ms,remaining_after_waiting) for backoff hints - Feature-flag driven compilation -- zero Redis dependencies when you only need local limiting
Non-goals
This crate is not designed for:
- Strictly linearizable admission control. Concurrent requests may temporarily overshoot limits. This is by design: the library prioritises throughput over strict serialisation.
- Strong consistency in distributed scenarios. Redis-backed limiting is best-effort; multiple clients can exceed limits simultaneously during network partitions or high concurrency.
- Built-in retry logic. Retry/backoff policies are application-specific and left to the caller.
Next steps
- Installation -- add Trypema to your project
- Quickstart (Local) -- get up and running in minutes
- Core Concepts -- understand keys, rate limits, and decisions