Reference

API Overview

Key types and entry points.

Trypema's main entry point is RateLimiter.

Full API docs:

GitHub docs.rs crates.io

Create it once (usually in an Arc<RateLimiter>) and access providers + strategies through it.

Core types

RateLimiter, RateLimiterOptions
RateLimit, RateLimitDecision
WindowSizeSeconds, RateGroupSizeMs
HardLimitFactor (suppressed)
SuppressionFactorCacheMs (suppressed)

Notes:

SuppressionFactorCacheMs is validated: try_from(0) fails. Default is 100ms.

Create a rate limiter

Local-only:

use trypema::{HardLimitFactor, RateGroupSizeMs, RateLimiter, RateLimiterOptions, SuppressionFactorCacheMs, WindowSizeSeconds};
use trypema::local::LocalRateLimiterOptions;

let rl = RateLimiter::new(RateLimiterOptions {
    local: LocalRateLimiterOptions {
        window_size_seconds: WindowSizeSeconds::try_from(60).unwrap(),
        rate_group_size_ms: RateGroupSizeMs::try_from(10).unwrap(),
        hard_limit_factor: HardLimitFactor::default(),
        suppression_factor_cache_ms: SuppressionFactorCacheMs::default(),
    },
});

let _ = rl;

Redis-enabled (requires redis-tokio or redis-smol):

use std::sync::Arc;

use trypema::{HardLimitFactor, RateGroupSizeMs, RateLimiter, RateLimiterOptions, SuppressionFactorCacheMs, WindowSizeSeconds};
use trypema::local::LocalRateLimiterOptions;
use trypema::redis::RedisRateLimiterOptions;

// Create Redis connection manager
let client = redis::Client::open("redis://127.0.0.1:6379/").unwrap();
let connection_manager = client.get_connection_manager().await.unwrap();

let rl = Arc::new(RateLimiter::new(RateLimiterOptions {
    local: LocalRateLimiterOptions {
        window_size_seconds: WindowSizeSeconds::try_from(60).unwrap(),
        rate_group_size_ms: RateGroupSizeMs::try_from(10).unwrap(),
        hard_limit_factor: HardLimitFactor::default(),
        suppression_factor_cache_ms: SuppressionFactorCacheMs::default(),
    },
    redis: RedisRateLimiterOptions {
        connection_manager,
        prefix: None,
        window_size_seconds: WindowSizeSeconds::try_from(60).unwrap(),
        rate_group_size_ms: RateGroupSizeMs::try_from(10).unwrap(),
        hard_limit_factor: HardLimitFactor::default(),
        suppression_factor_cache_ms: SuppressionFactorCacheMs::default(),
    },
}));

rl.run_cleanup_loop();

Providers

Local provider: rl.local() (sync, in-process)
Redis provider: rl.redis() (async, Redis-backed)

Strategies

Each provider supports:

Absolute: absolute()
Suppressed: suppressed()

Example (local absolute):

use trypema::{RateLimit, RateLimitDecision};

let rate = RateLimit::try_from(5.0).unwrap();

match rl.local().absolute().inc("user_123", &rate, 1) {
    RateLimitDecision::Allowed => {
        // proceed
    }
    RateLimitDecision::Rejected { retry_after_ms, .. } => {
        let _ = retry_after_ms;
        // backoff
    }
    RateLimitDecision::Suppressed { .. } => unreachable!("absolute strategy does not suppress"),
}

Common methods

inc(key, rate_limit, count): evaluates admission and records usage when admitted.
is_allowed(key): read-only admission preview (absolute strategy).

If your goal is to admit-and-record, call inc(...) and use its returned RateLimitDecision.

Keys

Local provider keys are &str.
Redis provider keys use RedisKey (validated; must be non-empty, <= 255 bytes, and must not contain :).

Errors

Redis-backed methods return Result<_, TrypemaError>.

Common variants include TrypemaError::RedisError, TrypemaError::InvalidRedisKey, and TrypemaError::UnexpectedRedisScriptResult.

Troubleshooting

Common problems and what to check.