Configuration Types
Trypema uses small validated types instead of unitless numbers. Each constructor names its unit,
rejects zero or invalid values, and has an _or_panic form for known constants.
Core types
| Type | Meaning | Accepted constructor units | Default |
|---|---|---|---|
RateLimit | target usage rate | per second, minute, hour, day, week, or 30-day month | none; supplied to inc and conditional updates |
WindowSize | how far back live usage is counted | seconds through 30-day months | 10 seconds |
BucketSize | interval used to merge nearby increments into one history bucket | milliseconds through 30-day months | 100 milliseconds |
HardLimitFactor | suppressed hard-capacity multiplier | unitless value at least 1.0 | 1.0 |
SuppressionFactorCachePeriod | how long a computed suppression factor may be reused | milliseconds through days | 100 milliseconds |
SyncInterval | hybrid local-to-Redis flush cadence | milliseconds through hours | 10 milliseconds |
WindowSize, BucketSize, HardLimitFactor, and SuppressionFactorCachePeriod configure every
provider through RateLimiterBuilder. SyncInterval exists only on hybrid builder.
Example
use trypema::{
BucketSize, HardLimitFactor, RateLimit, SuppressionFactorCachePeriod, WindowSize,
};
let rate = RateLimit::per_minute_or_panic(300.0); // equivalent to 5 requests/second
let window = WindowSize::minutes_or_panic(1);
let bucket = BucketSize::milliseconds_or_panic(10);
let hard_factor = HardLimitFactor::new_or_panic(1.5);
let cache = SuppressionFactorCachePeriod::milliseconds_or_panic(100);
Capacity and validation
Absolute capacity is rate per second × window seconds, converted to an integer using
truncation. Suppressed hard capacity multiplies that value by HardLimitFactor; its soft target
is base capacity.
BucketSize must be less than or equal to WindowSize. Builder validates this relationship even
when setters are called in another order. One month always means 30 days.
Fallible constructors such as WindowSize::minutes(1) return Result. Use
WindowSize::minutes_or_panic(1) only when value is a trusted constant.
Standard-library Duration
Cleanup timing and rejection waiting time use std::time::Duration, not a Trypema wrapper:
use std::time::Duration;
let cleanup_interval = Duration::from_secs(30);
RateLimitDecision::Rejected::retry_after is a Duration until oldest live bucket expires.