Reference

API Overview

Complete API reference for Trypema — all types, methods, and their signatures across providers and strategies.

This page provides a quick reference for Trypema's public API. For detailed explanations, see the linked concept and guide pages. For full Rustdoc, see docs.rs/trypema.

Entry point: `RateLimiter`

The main entry point. Create one instance, wrap it in Arc, and share it across threads.

use std::sync::Arc;
use trypema::{RateLimiter, RateLimiterOptions};

// let rl = Arc::new(RateLimiter::new(options));

Methods

Method	Description
`RateLimiter::new(options)`	Create a new rate limiter.
`rl.local()`	Access the local provider (`&LocalRateLimiterProvider`).
`rl.redis()`	Access the Redis provider (`&RedisRateLimiterProvider`). Requires `redis-tokio` or `redis-smol`.
`rl.hybrid()`	Access the hybrid provider (`&HybridRateLimiterProvider`). Requires `redis-tokio` or `redis-smol`.
`rl.run_cleanup_loop()`	Start background cleanup with defaults (10 min stale, 30s interval). Idempotent.
`rl.run_cleanup_loop_with_config(stale_after_ms, cleanup_interval_ms)`	Start cleanup with custom timing. Idempotent.
`rl.stop_cleanup_loop()`	Stop the cleanup loop. Idempotent.

Absolute strategy methods

Available on all three providers.

Local (sync)

Method	Signature	Description
`inc`	`inc(key: &str, rate_limit: &RateLimit, count: u64) -> RateLimitDecision`	Check admission and record increment.
`is_allowed`	`is_allowed(key: &str) -> RateLimitDecision`	Check admission without incrementing.

Redis (async)

Method	Signature	Description
`inc`	`async inc(key: &RedisKey, rate_limit: &RateLimit, count: u64) -> Result<RateLimitDecision, TrypemaError>`	Check admission and record increment.
`is_allowed`	`async is_allowed(key: &RedisKey) -> Result<RateLimitDecision, TrypemaError>`	Check admission without incrementing.

Hybrid (async)

Method	Signature	Description
`inc`	`async inc(key: &RedisKey, rate_limit: &RateLimit, count: u64) -> Result<RateLimitDecision, TrypemaError>`	Check admission and record increment.

Suppressed strategy methods

Available on all three providers.

Local (sync)

Method	Signature	Description
`inc`	`inc(key: &str, rate_limit: &RateLimit, count: u64) -> RateLimitDecision`	Check admission and record increment.
`get_suppression_factor`	`get_suppression_factor(key: &str) -> f64`	Get cached suppression factor (read-only).

Redis (async)

Method	Signature	Description
`inc`	`async inc(key: &RedisKey, rate_limit: &RateLimit, count: u64) -> Result<RateLimitDecision, TrypemaError>`	Check admission and record increment.
`get_suppression_factor`	`async get_suppression_factor(key: &RedisKey) -> Result<f64, TrypemaError>`	Get cached suppression factor (read-only).

Hybrid (async)

Method	Signature	Description
`inc`	`async inc(key: &RedisKey, rate_limit: &RateLimit, count: u64) -> Result<RateLimitDecision, TrypemaError>`	Check admission and record increment.
`get_suppression_factor`	`async get_suppression_factor(key: &RedisKey) -> Result<f64, TrypemaError>`	Get cached suppression factor (read-only).

`RateLimitDecision`

Returned by all inc() and is_allowed() calls. See Decisions for full details.

Variant	Returned by	Description
`Allowed`	Both strategies	Request admitted.
`Rejected { window_size_seconds, retry_after_ms, remaining_after_waiting }`	Absolute only	Request denied with backoff hints.
`Suppressed { suppression_factor, is_allowed }`	Suppressed only	Probabilistic admission. Check `is_allowed`.

Configuration types

All types are validated newtypes. Construction via TryFrom returns Result<T, TrypemaError>.

Type	Wraps	Default	Valid range	Description
`RateLimit`	`f64`	(required)	> 0.0	Requests per second.
`WindowSizeSeconds`	`u64`	(required)	>= 1	Sliding window duration.
`RateGroupSizeMs`	`u64`	100	>= 1	Bucket coalescing interval (ms).
`HardLimitFactor`	`f64`	1.0	>= 1.0	Hard cutoff multiplier (suppressed only).
`SuppressionFactorCacheMs`	`u64`	100	>= 1	Factor cache duration (ms, suppressed only).
`SyncIntervalMs`	`u64`	10	>= 1	Hybrid sync interval (ms, hybrid only).
`RedisKey`	`String`	--	Non-empty, <= 255 bytes, no `:`	Validated Redis key.

Error type: `TrypemaError`

Variant	Cause
`RedisError(...)`	Redis connectivity or command failure.
`InvalidRateLimit(...)`	Rate limit <= 0.
`InvalidWindowSizeSeconds(...)`	Window size < 1.
`InvalidRateGroupSizeMs(...)`	Rate group size == 0.
`InvalidHardLimitFactor(...)`	Hard limit factor < 1.0.
`InvalidSuppressionFactorCacheMs(...)`	Suppression factor cache == 0.
`InvalidRedisKey(...)`	Redis key validation failed.
`UnexpectedRedisScriptResult(...)`	Lua script returned unexpected result.
`CustomError(...)`	Internal error.

Project structure

src/
+-- lib.rs                               # Crate root: re-exports, feature gates
+-- rate_limiter.rs                      # RateLimiter facade + RateLimiterOptions
+-- common.rs                            # Shared types (RateLimitDecision, RateLimit, etc.)
+-- error.rs                             # TrypemaError enum
+-- runtime.rs                           # Async runtime abstraction (tokio / smol)
+-- local/
|   +-- mod.rs                           # Local provider module
|   +-- local_rate_limiter_provider.rs   # LocalRateLimiterProvider + LocalRateLimiterOptions
|   +-- absolute_local_rate_limiter.rs   # AbsoluteLocalRateLimiter
|   +-- suppressed_local_rate_limiter.rs # SuppressedLocalRateLimiter
+-- redis/
|   +-- mod.rs                           # Redis provider module
|   +-- common.rs                        # RedisKey, RedisKeyGenerator
|   +-- redis_rate_limiter_provider.rs   # RedisRateLimiterProvider + RedisRateLimiterOptions
|   +-- absolute_redis_rate_limiter.rs   # AbsoluteRedisRateLimiter (Lua scripts)
|   +-- suppressed_redis_rate_limiter.rs # SuppressedRedisRateLimiter (Lua scripts)
+-- hybrid/
    +-- mod.rs                           # Hybrid provider module
    +-- common.rs                        # SyncIntervalMs, committer utilities
    +-- hybrid_rate_limiter_provider.rs  # HybridRateLimiterProvider
    +-- absolute_hybrid_rate_limiter.rs  # AbsoluteHybridRateLimiter (state machine)
    +-- absolute_hybrid_redis_proxy.rs   # Redis I/O proxy for absolute hybrid
    +-- suppressed_hybrid_rate_limiter.rs # SuppressedHybridRateLimiter (state machine)
    +-- suppressed_hybrid_redis_proxy.rs # Redis I/O proxy for suppressed hybrid
    +-- redis_commiter.rs               # RedisCommitter: background batch-flush actor

The file is named redis_commiter.rs (single t) in the source code. This is the actual filename in the repository.

Feature flags

Feature	What it enables
(default)	Local provider only. Zero Redis dependencies.
`redis-tokio`	Redis + Hybrid providers with Tokio runtime.
`redis-smol`	Redis + Hybrid providers with Smol runtime.

redis-tokio and redis-smol are mutually exclusive.

Troubleshooting

Common issues and solutions when using Trypema — Redis connectivity, validation errors, runtime issues, and more.

Benchmark Concepts

How to interpret ops/s, latency percentiles, and workload knobs.