Install
This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.
Install straight from GitHub with WP-CLI:
wp plugin install https://github.com/generoi/gds-rate-limiter/archive/refs/heads/master.zipAnswers 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, 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 | |
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.
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
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.
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