Rate Limiting Deep Dive

Token Bucket Algorithm

ZyveraWeb uses the token bucket algorithm for rate limiting, which is more flexible than a simple fixed-window counter.

How It Works

1. Each IP address has a bucket with N tokens (N = 'requests')
2. Every 'per' duration, the bucket is refilled to N tokens
3. Each request consumes 1 token
4. If the bucket is empty, the request is denied (429)

Key Properties

• Burst allowance: Clients can use all N requests at once (not evenly distributed)
• No penalty for idle: Tokens are not accumulated beyond N
• Fair across IPs: Each IP has its own independent bucket

Cleanup

Stale buckets from inactive IP addresses are periodically cleaned up to prevent memory leaks.

Performance Considerations

• Thread-safe access to rate limiter state
• Per-IP synchronization (no global lock)
• Cleanup runs asynchronously on a timer
• Memory usage grows with the number of unique IPs accessing the server

Tuning Guidelines