Concepts
Keys
How Trypema isolates rate limiting state.
Trypema rate limits are keyed: each key maintains independent state.
You decide what a "key" represents (user, IP, tenant, endpoint, API token, etc.).
Examples:
user_123
ip_203_0_113_10
api_v2_search
Choosing good keys
Good keys balance isolation, operability, and bounded cardinality.
Common patterns
| Scope | Example |
|---|---|
| Per user | user_123 |
| Per tenant | tenant_42 |
| Per IP | ip_203_0_113_10 |
| Per endpoint | route_search |
| Combined | `tenant_42 |
Multi-tier keys
If you have tiers (free/pro/enterprise), encode the tier into the key or into your rate selection logic. Example key-only approach:
free|user_123
pro|user_456
High key cardinality (many unique keys) can increase memory usage (local) or Redis memory usage (Redis provider). Use the cleanup loop and avoid attacker-controlled key explosions.
Practical mitigation ideas:
Avoid embedding untrusted high-entropy values (request IDs, full URLs, raw tokens), normalize inputs, prefer stable identifiers (user IDs) over unstable ones (IPs), and enable the cleanup loop if keys churn.
Redis key constraints
When using Redis, keys are wrapped in RedisKey and validated:
They must be non-empty, <= 255 bytes, and must not contain :.
use trypema::redis::RedisKey;
let _ = RedisKey::try_from("user_123".to_string()).unwrap();
let _ = RedisKey::try_from("user:123".to_string());
If you need compound keys with Redis, use a different separator (e.g.
_ or |) and keep the string <= 255 bytes.