caddy-ratelimit

Distributed rate limiting allows multiple Caddy instances to share rate limit state across a cluster.

Requirements:

• All instances in the cluster must have the exact same rate limit zone configurations.
• All instances must be configured to use the same storage module.

How it works: Instances periodically write their internal state to storage and read the state from other instances. This synchronization is eventually consistent and approximate.

Configuration: Enable it by providing a non-null distributed object in JSON or the distributed subdirective in a Caddyfile. You can tune the following parameters:

• read_interval: How often to read state from storage.
• write_interval: How often to write state to storage.
• purge_age: How long to keep old state.

Note: Default intervals are 5s.

To include the rate_limit module in your Caddy binary, use xcaddy to build a custom version of Caddy with the module included.

$ xcaddy build --with github.com/mholt/caddy-ratelimit

The Key field in a RateLimit configuration determines how rate limiters are allocated.

• Static Key: If you provide a static string like "global", exactly one rate limiter is created for the entire zone. All requests matching the MatcherSetsRaw will share this single bucket.
• Dynamic Key: If you use Caddy placeholders, a unique rate limiter is created for every unique value produced by the placeholder. For example, using "{http.request.remote.host}" will create one rate limiter per unique client IP address.

To enable rate limiting across a cluster of Caddy instances, configure the distributed option.

Requirements:

• All instances in the cluster must share the same storage configuration.
• Rate limit zones must have the exact same configuration across all instances to ensure consistent calculations.

Configuration:

• read_interval: How often to sync state from other instances (defaults to 5s).
• write_interval: How often to sync local state to the storage (defaults to 5s).

The module uses a package-level singleton globalMetrics to ensure metric continuity.

When Caddy reloads, it provisions a fresh metrics registry. The module handles this by re-registering the existing collectors with the new registry via registerMetrics. This mechanism ensures that Prometheus metrics are reported continuously and that their accumulated values remain intact across configuration reloads. If a collector is already registered with a registry, the module gracefully handles the prometheus.AlreadyRegisteredError.

When a rate limit is exceeded, the handler performs several actions that allow for custom responses or logging:

1. HTTP Error: Returns a 429 Too Many Requests status code.
2. Retry-After Header: Sets a Retry-After header indicating how many seconds to wait (including optional jitter).
3. Caddy Replacer: Sets the placeholder {http.rate_limit.exceeded.name} to the name of the zone that was exceeded. You can use this in your Caddyfile or JSON config to customize error responses.
4. Events: Emits a rate_limit_exceeded event containing the zone, wait duration, and remote_ip.

To prevent abuse from clients cycling through different IP addresses within the same network, you can use IPv4Prefix and IPv6Prefix to group rate limit keys by subnet.

• IPv4Prefix: An integer between 0 and 32. A value of 24 will group all addresses in the same /24 subnet into a single rate limit bucket.
• IPv6Prefix: An integer between 0 and 128. A value of 64 will group all addresses in the same /64 network into a single rate limit bucket.

If these are set to 0 (the default), every individual IP address is treated as a unique rate limiter.

The rate_limit directive allows you to define rate limiting zones and global settings within your Caddyfile. It is registered as an HTTP handler directive and is ordered to appear before basic_auth.

rate_limit {
    zone my_zone {
        key "some_key"
        window 1m
        events 100
        match {
            path /api/*
        }
    }
    distributed {
        read_interval 10s
        write_interval 10s
        purge_age 1h
    }
    storage redis
    jitter 0.1
}

To prevent attackers from bypassing per-IP limits by cycling through many addresses in an IPv6 prefix, use the ipv6_prefix option. This groups all addresses within the same network (e.g., a /64) into a single rate limit bucket.

Caddyfile

rate_limit {
	zone per_network {
		key         {remote_host}
		events      100
		window      1m
		ipv6_prefix 64
	}
}

JSON

{
	"handler": "rate_limit",
	"rate_limits": {
		"per_network": {
			"key": "{http.request.remote.host}",
			"window": "1m",
			"max_events": 100,
			"ipv6_prefix": 64
		}
	}
}