Rate limiting

Token-bucket global limits live under [security.rate_limit]. Per-route limits use [routes.rate_limit] immediately after each [[routes]] entry (TOML associates the subtable with that route). Dynamic.

See examples/config/rate-limit-example.toml on GitHub for a full file.

Strategies

Key limit_by values:

• ip: client IP
• header: value of a named header (limit_by_header)
• route: shared limit per route path
• combined: IP + route

Responses use 429 when exceeded. Counters are in-memory and per process; they are not shared across replicas.

Global default

YAML

security:
  rate_limit:
    enabled: true
    requests_per_second: 1000
    burst: 2000
    window_seconds: 1
    limit_by: "ip"

TOML

[security.rate_limit]
enabled = true
requests_per_second = 1000
burst = 2000
window_seconds = 1
limit_by = "ip"

Per-route override

Only the keys you set override the global; unset keys fall back to global config.

YAML

routes:
  - prefix: "/api"
    backend: "backend-a:9000"
    rate_limit:
      enabled: true
      requests_per_second: 50
      burst: 100
      limit_by: combined
  - prefix: "/public"
    backend: "backend-b:9000"
    rate_limit:
      enabled: false

TOML

[[routes]]
prefix = "/api"
backend = "backend-a:9000"

[routes.rate_limit]
enabled = true
requests_per_second = 50
burst = 100
limit_by = "combined"

[[routes]]
prefix = "/public"
backend = "backend-b:9000"

[routes.rate_limit]
enabled = false   # disable rate limiting for this route

Rate limit by header

YAML

security:
  rate_limit:
    enabled: true
    requests_per_second: 200
    burst: 400
    limit_by: "header"
    limit_by_header: "X-API-Key"

TOML

[security.rate_limit]
enabled = true
requests_per_second = 200
burst = 400
limit_by = "header"
limit_by_header = "X-API-Key"

Related

• IP filtering: [security.ip_filter]
• Security: security headers and forwarding
• Routes: prefix and backend selection
• Configuration overview