Trypema Rate Limiter

Trypema is a Rust sliding-window rate limiter with local, Redis, and hybrid providers. Each provider supports binary admission through the Absolute strategy and gradual probabilistic load shedding through the Suppressed strategy.

Version 2.0.0 is released. It is a breaking redesign: providers are constructed independently, configuration uses validated semantic types, reads expose live state, and conditional writes return structured outcomes.

Provider choice

Redis and hybrid require Redis 7.2+ and exactly one runtime feature: redis-tokio or redis-smol. Admission is best-effort under concurrency; concurrent callers can temporarily overshoot a limit.

Two pressure strategies

Absolute returns an allowed or rejected decision. Rejections include retry_after: Duration, the configured window_size, and remaining_after_waiting, the capacity released when the oldest live bucket expires.

Suppressed progressively increases the probability of shedding work as pressure rises, then uses the hard limit as its final boundary. Reads return a SuppressedRateLimitSnapshot containing total usage, declined usage, and the current suppression factor.

Live state and conditional updates

Absolute get calls return the live total; suppressed reads return a structured snapshot. Unknown keys produce zero-valued results without creating state. Expired history may be evicted lazily during a read.

inc stores a key's computed window capacity when the key is created. Later increments keep that capacity until a matched conditional write replaces it. set_if replaces history after a comparator match; set_if_preserve_history can retain the newest or oldest side. Both return ConditionalSetOutcome, and a matched zero removes the key.

v2 local quickstart

[dependencies]
trypema = "2"

use trypema::{
    BucketSize, RateLimit, RateLimitDecision, RateLimiterBuilder, WindowSize,
    local::LocalRateLimiterProvider,
};

let provider = LocalRateLimiterProvider::builder()
    .window_size(WindowSize::minutes_or_panic(1))
    .bucket_size(BucketSize::milliseconds_or_panic(10))
    .build()
    .unwrap();

let rate = RateLimit::per_second_or_panic(5.0);

match provider.absolute().inc("user_123", &rate, 1) {
    RateLimitDecision::Allowed => {}
    RateLimitDecision::Rejected { retry_after, .. } => {
        println!("retry in {retry_after:?}");
    }
    RateLimitDecision::Suppressed { .. } => unreachable!(),
}

Builders return an Arc and start stale-state cleanup by default. Use disable_cleanup() while building when cleanup is unwanted; start_cleanup_loop() and stop_cleanup_loop() are idempotent after construction.

Redis and hybrid construction

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

Redis and hybrid providers receive a Redis connection directly through their own builders. Hybrid also accepts a validated SyncInterval; smaller values reduce visibility lag and increase Redis work. Its authoritative get synchronizes with Redis and overlays local pending counts, while get_estimate may answer from initialized local state.

Benchmark snapshot

The published benchmarks remain historical measurements, not universal performance promises. They compare fixed workloads across throughput, tail latency, and hot-key contention. Results vary with hardware, runtime, Redis placement, configuration, and competing load. The Redis and hybrid results compare backend cost, not identical behaviour, because the hybrid fast path accepts bounded visibility lag between synchronizations.

• Local 100,000-key workload: Trypema Absolute reached 9.64M ops/s and Suppressed reached 7.61M ops/s, compared with Governor at 6.28M ops/s.
• Redis hot-key workload: Trypema Absolute reached 47.6k ops/s and Suppressed reached 41.0k ops/s, compared with redis-cell at 64.4k ops/s.
• Hybrid hot-key fast path with a 10 ms synchronization interval: Trypema Absolute reached 11.36M ops/s and Suppressed reached 10.57M ops/s, while direct Redis alternatives remained in the tens of thousands of operations per second.

v2 highlights