Rate Limiting

ZyveraWeb uses a token bucket algorithm to rate-limit requests per IP address. Each bucket is refilled to its maximum capacity after the time window elapses.

Rate Limit Sections

There are two independent rate limit configurations:

Configuration Format

rate-limit:
  <section>:
    requests: <number>
    per: <duration>

requests

The maximum number of requests allowed within the time window.

per

The time window duration. Accepts the following suffixes:

Examples: 30s, 1m, 5m, 2h, 1d

How It Works

1. Each unique IP address gets its own token bucket.
2. When a request arrives, a token is consumed from that IP's bucket.
3. If no tokens remain, the request is rejected with HTTP 429 Too Many Requests.
4. After the time window (per) elapses, the bucket is refilled to requests tokens.
5. Stale buckets (unused for 2x the window duration) are periodically cleaned up.

Per-Site Rate Limiting

You can also configure rate limits per virtual host site:

sites:
  - domain: "example.com"
    dir: "site/example"
    rate-limit:
      requests: 100
      per: 1m

Example: Aggressive Rate Limiting

rate-limit:
  placeholder:
    requests: 60
    per: 1m
  players:
    requests: 100
    per: 1m

Example: No Effective Limit

rate-limit:
  placeholder:
    requests: 10000
    per: 1s
  players:
    requests: 10000
    per: 1s

Note: Setting very high limits does not disable rate limiting. A truly unlimited mode is not currently supported.