generoi / gds-rate-limiter
Answers 429 to IPs that flood PHP with uncached requests, before WordPress loads, with APCu, Redis or the object cache, and escalates repeat offenders to Fastly or Cloudflare
Package info
github.com/generoi/gds-rate-limiter
Type:wordpress-muplugin
pkg:composer/generoi/gds-rate-limiter
Requires
- php: >=8.1
Requires (Dev)
- laravel/pint: ^1.17
- php-stubs/wp-cli-stubs: ^2.11
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^9.0
- szepeviktor/phpstan-wordpress: ^2.0
- wp-phpunit/wp-phpunit: ^7.0
- yoast/phpunit-polyfills: ^2.0
Suggests
Provides
None
Conflicts
None
Replaces
None
README
Answers 429 to IPs that flood PHP with uncached requests, before WordPress loads or connects to its database. Only cache misses reach PHP, so it counts what costs the server, not what the page cache serves.
composer require generoi/gds-rate-limiter
It's a must-use plugin, but it does nothing until the site boots it with its
settings, in Bedrock's config/application.php after Config::apply():
use GeneroWP\RateLimiter\RateLimiter; use GeneroWP\RateLimiter\Store\ApcuStore; RateLimiter::boot([ 'disable' => env('DISABLE_RATE_LIMITING'), 'limit' => 45, 'store' => new ApcuStore, 'allow' => ['192.0.2.10', '198.51.100.0/24'], 'bypass_token' => env('RATE_LIMIT_BYPASS_TOKEN'), ]);
How it decides
- A request from an IP or subnet that's banned gets 429 straight away.
- Over
limitrequests in awindowbans the IP forbanseconds. Each further ban withinescalation_windowdoubles it, up tomax_ban; an IP that goes a wholeescalation_windowwithout one starts again. - Over
subnet_limitrequests from one /24 (IPv4) or /64 (IPv6) bans the subnet forsubnet_ban: for a crawl spread over many addresses. It's more lenient and never doubled, as a subnet can hold real people. - With
edgeblocklists set, an IP'sedge_afterth ban withinedge_windowadds it to them, after its 429 has been sent. Only single addresses ever reach the edge, and they stay untilwp rate-limit unblock. - With
site_limitset, the requests let through from all IPs together are counted too: for a crawl spread over addresses in different networks, each underlimit. Going oversite_limitin a window starts a surge ofsurge_forseconds, during which each IP gets onlysurge_limita window, about what one person browsing makes. Over that is a 429 until the window ends, not a ban: no doubling and no edge, so a real visitor caught in a surge loses at most a window. Setsite_limitfrom the site's own traffic, under what its PHP workers can serve; refused requests don't count toward it, so a surge ends once the load does.
The 429 has Retry-After and Cache-Control: no-store, private, and one line
goes to the PHP error log: [Rate Limit] IP: … | Retry-After: …s | URI: … | Method: … | User-Agent: ….
A surge logs once when it starts, [Rate Limit] Surge: … requests in …s over the site limit of …; each IP gets … a window for …s, and not per refusal.
Never limited: logged-in users (a request with a login cookie waits until
WordPress can check it, then runs first on plugins_loaded), allowed
addresses and ranges, a rate_limit_bypass cookie equal to bypass_token
(for e2e runs against production), WP-CLI, WordPress's own requests to the
site (see below), and private or reserved addresses.
A store that fails lets requests through, and so do options boot() can't
read (logged as [Rate Limit] Not booted: …).
Counted like any visitor: REST or admin-ajax clients without a login cookie
(an integration polling the site may need an allow entry), and WooCommerce
shoppers, whose session cookie skips the page cache.
Options
| Option | Default | |
|---|---|---|
limit |
45 | Requests per IP per window |
window |
60 | Seconds |
ban |
120 | The first ban, seconds |
max_ban |
86400 | |
escalation_window |
86400 | |
subnet_limit |
150 | 0 turns it off |
subnet_ban |
300 | |
site_limit |
0 | Requests from all IPs per window before a surge; 0 turns surges off |
surge_limit |
6 | Requests per IP per window during a surge |
surge_for |
300 | Seconds a surge lasts |
allow |
[] |
Addresses and CIDR ranges |
bypass_token |
'' |
|
store |
ApcuStore if APCu is on, else CacheStore |
See below |
client_ip |
RemoteAddr |
See below |
edge |
[] |
Fastly, Cloudflare |
edge_after |
3 | |
edge_window |
1800 | |
crawl_delay |
from limit |
Seconds robots.txt asks known crawlers to wait; 0 turns it off |
disable |
false |
|
log |
error_log |
A callable taking the line |
An unknown option is an error, so a typo can't leave a default in place.
Crawl delay
Declared crawlers such as ClaudeBot, GPTBot or bingbot rotate IPs, and each
one can go over a low limit by itself. So robots.txt asks them (the list is
CrawlDelay::USER_AGENTS) to wait crawl_delay seconds between requests: by
default enough to keep them at two thirds of limit, 5 s at 20 and 2 s at 45.
Googlebot ignores Crawl-delay; Bing and the AI crawlers honour it, so a long
delay slows how fast they pick up new pages.
A crawler follows only the group that names it, so the group repeats the
User-agent: * rules. It's added last on WordPress's robots_txt filter,
after Yoast or The SEO Framework, so a site's own crawl-delay code should go.
A physical robots.txt in the web root bypasses WordPress and this.
Stores
ApcuStore: the server's memory, shared by its PHP workers and every site of a network on them. The fastest; lost on a PHP restart, not shared across servers, and not visible to WP-CLI.RedisStore(host, port, password, database, timeout, prefix): shared across servers. Connects on first use with a 0.5 s timeout. Sites sharing a Redis need their ownprefix, or one site'sflushempties the others'.CacheStore: WordPress's object cache when a drop-in makes it persistent, else transients. It needs WordPress, so every check waits forplugins_loaded; transient counts aren't atomic under a burst, and on a network they're per site, not shared.
Client address
-
RemoteAddr:REMOTE_ADDR, where the host already puts the visitor's address there and no header can change it (Kinsta, behind its Cloudflare). -
VerifiedCdn(secret): the address Fastly (Fastly-Client-IP) or Cloudflare (CF-Connecting-IP) forwards, only when the request carries the shared secret inX-Origin-VerifyorX-Origin-Verify-Cloudflare. Each CDN sets its own header, overwriting a client's, so each secret header unlocks only its own CDN's address header. Without a match (direct-to-origin traffic, or everything while the secret is unset) nothing is limited, so rolling it out in any order is safe.Fastly VCL,
recv:set req.http.X-Origin-Verify = "<secret>";
Both take allowPrivate: true for local development.
Edge blocklists
use GeneroWP\RateLimiter\ClientIp\VerifiedCdn; use GeneroWP\RateLimiter\Edge\Cloudflare; use GeneroWP\RateLimiter\Edge\Fastly; RateLimiter::boot([ 'client_ip' => new VerifiedCdn((string) env('RATE_LIMIT_ORIGIN_SECRET')), 'edge' => array_filter([ env('FASTLY_BLOCKLIST_DICTIONARY_ID') ? new Fastly(env('FASTLY_API_KEY'), env('FASTLY_SERVICE_ID'), env('FASTLY_BLOCKLIST_DICTIONARY_ID')) : null, env('CLOUDFLARE_BLOCKLIST_ID') ? new Cloudflare(env('CLOUDFLARE_API_TOKEN'), env('CLOUDFLARE_ACCOUNT_ID'), env('CLOUDFLARE_BLOCKLIST_ID')) : null, ]), ]);
Fastly: an Edge Dictionaryblocked_ips, refused inrecv:if (table.lookup(blocked_ips, client.ip, "0") == "1") { error 403 "Forbidden"; }Cloudflare: an account IP list, blocked by a WAF custom ruleip.src in $blocked_ips. The token needs Account Filter Lists: Edit.
WP-CLI
wp rate-limit status <ip> # its count, bans and subnet wp rate-limit flush # empty the store wp rate-limit block <ip> # add to the edge blocklists wp rate-limit unblock <ip> wp rate-limit blocklist wp rate-limit token # the header value for the site's own requests
status and flush see Redis and the object cache; APCu lives in the web
server's memory, which WP-CLI doesn't share.
Cache warming
sage-cachetags' warmer
(wp cachetags warm) re-requests purged pages from the server itself. The
mu-plugin adds an X-Cache-Warm header to its requests through the
cachetags/warm/request-headers filter, carrying bypass_token when it's set
and otherwise a token derived from AUTH_KEY, so WP-CLI and the web server
agree on it without configuration.
A request with that token isn't counted, by IP or site-wide. While the site is
busy (surging, or past half of site_limit) it gets a 429 instead, which makes
the warmer stop its run until the next one. Without a site_limit the warmer is
never held back. Nothing else changes: sage-cachetags knows nothing about the
limiter, and a site without the warmer never sends the header.
The site's own requests
WordPress requests its own site for loopbacks (Site Health, the plugin and
theme editors) and to spawn cron. Those leave through the server's outbound
address, which on Kinsta is shared with other sites and changes, so they're
told apart by a header rather than an allow entry: the mu-plugin adds
X-Rate-Limit-Self to every wp_remote_* request to the site's own host,
with a token derived from bypass_token when it's set and otherwise from
AUTH_KEY. A request carrying it is never limited.
A script that requests the site from the server can send it too:
curl -H "X-Rate-Limit-Self: $(wp rate-limit token)" https://example.com/sitemap_index.xml
Development
composer install composer test:unit # the logic, without WordPress; the APCu and Redis tests where those are set up npm install npm run env:start npm run test:php # in wp-env: the cache store and the logged-in check npm run test:e2e # real requests to wp-env's site composer lint composer stan