Configuration: rate limiting

This page documents the rate_limit directive for configuring token bucket-based rate limiting for HTTP requests. When a client exceeds the configured rate, the server returns a 429 Too Many Requests response with a Retry-After header.

rate_limit⁠#

example.com {
    rate_limit {
        rate 100
        burst 50
        key remote_address
        deny_status 429
        bucket_ttl 600
        max_buckets 100000
    }

    location /api {
        rate_limit {
            rate 10
            burst 5
            key remote_address
            log_rejections
        }
    }
}

You can define multiple rate_limit blocks to apply different rules simultaneously (for example, one per IP and one per API key).

Key types⁠#

The key directive determines which value each bucket uses:

Behavior⁠#

Ferron applies rate limiting with the in-memory backend per server instance by default. For distributed rate limiting across instances, configure a rate_limit_backend block with type redis (Redis or Valkey, same RESP protocol).

Token bucket algorithm⁠#

Each key gets its own token bucket:

• Capacity = rate + burst tokens (bucket starts full)
• Refill rate = rate tokens per second (refilled lazily on each request)
• Consumption = 1 token per request

When the bucket is empty, the server rejects the request with the configured deny_status. The response includes a Retry-After header that shows how many seconds to wait.

Bucket eviction⁠#

To prevent unbounded memory growth from one-shot clients, the module evicts buckets after bucket_ttl seconds of inactivity. The max_buckets setting enforces a hard upper limit. When the registry reaches this limit, the module rejects new requests until it removes stale buckets. max_buckets applies to the in-memory backend only; Redis keys expire via bucket_ttl.

Distributed backend with Redis or Valkey⁠#

Rate limit state is selected by a rate_limit_backend block, a sibling of rate_limit (not nested inside it). A host or location without its own rate_limit_backend block inherits the global one; absent entirely means in-memory. Host isolation: a named host does not inherit rate_limit_backend from the wildcard * host, but it still inherits the global one.

{
    rate_limit_backend {
        type redis
        url redis://127.0.0.1:6379/0
        key_prefix "ferron:rl:"
        timeout 200
        fail_open
    }
}

example.com {
    rate_limit {
        rate 100
        burst 50
        key remote_address
    }
}

Redis uses the same token-bucket semantics as memory via an atomic Lua script (capacity rate + burst, refill rate/sec, key TTL bucket_ttl). All Redis I/O runs on the secondary Tokio runtime, never on primary zincio threads.

Override per location by defining another rate_limit_backend block:

example.com {
    rate_limit_backend {
        type redis
        url redis://127.0.0.1:6379/0
    }

    rate_limit {
        rate 100
        burst 50
    }

    location /internal {
        rate_limit_backend {
            type memory
        }

        rate_limit {
            rate 1000
            burst 100
        }
    }
}

Per-location limits⁠#

rate_limit blocks inside location blocks apply only to requests matching that path. Ferron evaluates both host-level and location-level rules. A request must pass all rules before Ferron serves it.

Rate limit zones⁠#

By default, each host gets its own isolated set of rate limit buckets. Rate limit zones allow multiple hostnames to share the same buckets, or to explicitly opt out of a global zone.

Zone resolution order:

1. If the host-level rate_limit block contains zone "name", the host joins the named zone.
2. If the host has its own rate_limit block (without zone) and a global zone exists, the host gets a per-host zone. This opts out of the global zone.
3. If a global rate_limit block exists without zone blocks, all hosts without explicit zones share the global zone.
4. Otherwise, each host gets its own per-host zone.

Global zone:

{
    rate_limit {
        rate 10
        burst 5
        key remote_address
    }
}

example.com {
    rate_limit {
        rate 10
        burst 5
        key remote_address
    }
}

api.example.com {
    rate_limit {
        rate 50
        burst 10
        key remote_address
    }
}

Both example.com and api.example.com share the same global zone. Buckets use the client IP as the key, so a client hitting both hosts shares the same token pool.

Named zones:

{
    rate_limit {
        zone api
    }
}

api.example.com {
    rate_limit {
        zone api
        rate 50
        burst 10
        key remote_address
    }
}

api-v2.example.com {
    rate_limit {
        zone api
        rate 50
        burst 10
        key remote_address
    }
}

Both api.example.com and api-v2.example.com share the named zone "api" and the same rate limit buckets.

Opting out of the global zone:

{
    rate_limit {
        rate 10
        burst 5
        key remote_address
    }
}

example.com {
    # Inherits global zone
}

internal.example.com {
    rate_limit {
        rate 100
        burst 20
        key remote_address
    }
    # Has its own rate_limit block → per-host zone (opts out of global)
}

Configuration reload⁠#

Ferron stores in-memory rate limit buckets in memory. They do not survive a configuration reload. A reload creates fresh buckets with the new configuration. Redis-backed buckets survive reloads (they live in Redis and expire via bucket_ttl).

Examples⁠#

Basic IP-based rate limiting⁠#

example.com {
    rate_limit {
        rate 10
        burst 5
        key remote_address
    }
}

Allows 15 requests burst, then 10/second sustained per IP.

API key rate limiting⁠#

api.example.com {
    rate_limit {
        rate 50
        burst 100
        key request.header.X-Api-Key
    }
}

Each unique API key gets 150 requests burst, then 50/second.

Strict endpoint with custom status⁠#

example.com {
    location /login {
        rate_limit {
            rate 2
            burst 1
            deny_status 429
        }
    }
}

Limits login to 3 requests burst, then 2/second. Returns 429 when exceeded.

Observability⁠#

Metrics⁠#

The rate limiting module emits the following metrics:

The ferron.ratelimit.zone attribute identifies which rate limit zone the request belongs to. It has the value "global" for the shared global zone. It uses the zone name for named zones and the hostname for per-host zones. The ferron.ratelimit.backend attribute is "memory" or "redis".

Logs⁠#

• INFO: logged for the first rejection of a key, then at most once per minute while the key stays over limit. The raw key value is omitted (it can identify a client); rejection volume remains visible via the ferron.ratelimit.rejected counter.
• DEBUG: per-request Rate limit bucket exhausted logs, only when log_rejections is set.
• WARN: logged when the registry reaches max_buckets capacity and applies backpressure.
• WARN: logged when the Redis backend errors (Rate limit backend error; fail-open allows, fail-closed denies).

Structured logs⁠#

Access log fields⁠#

The rate limiting module contributes the following fields to the HTTP access log line:

Trace spans⁠#

The rate limit stage sets the following attributes on its ferron.stage.rate_limit span: