FAIRVISOR Docs
⌘K
GitHub fairvisor.com

Rate Limiting

Fairvisor implements token bucket and budget-style limiting with in-memory state per edge instance.

Distributed/global shared limiter state is not supported in the current OSS runtime.

Token bucket model

Each rule with action: rate_limit owns a token bucket identified by:

  • Rule id
  • The value of the group_by expression (e.g. header("X-User-Id"))

Tokens refill continuously at the configured rate. A burst of up to burst tokens can be consumed before throttling begins.

- id: per-user-limit
  match:
    all: true
  action: rate_limit
  params:
    rate: 10          # tokens per second
    burst: 30         # max burst
    group_by: header("X-User-Id")

Period budget counters

For cost-based budgets, Fairvisor uses fixed period counters keyed by rule/key and period start. Supported periods are 5m, 1h, 1d, and 7d.

Multi-instance behavior

Each instance keeps independent counters in ngx.shared.dict.

For N parallel instances handling the same traffic, effective aggregate throughput can approach N× the per-instance limit. Use one of these approaches:

  • single enforcement point for strict global limits
  • split limits across parallel installations (for two installations, set each to 50%)

See HA Installation for a concrete two-installation pattern.

MD