docs: the Worker's rate limits count per server, as measured

Measured on production after v4.5.1 deployed (2026-10-27, SIN): over one
keep-alive connection each budget held exactly - /api/no-such-route
121 x 404 then 429 with Retry-After, no-store and CORS; /api/human-check
19 then 429 - while requests on fresh connections, which Cloudflare
spreads over many servers, were never refused (175 human checks in 70 s
against a budget of 20). A probe Worker in a remote preview confirmed the
binding itself enforces (limit 5: 6 allowed, then refused).

So the layer stops browsers and connection-reusing scripts; a client that
reconnects for every request is the WAF rule's, which counted exactly
(250). The docs, CLAUDE.md, the module comment, wrangler.jsonc and the
unpublished v4.5.1 entry said "per location, approximate"; they now say
what was measured. The section 3b check used xargs (fresh connections) and
would have shown no 429 - it now sends everything over one connection.
No behaviour change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-10-27 07:10:29 +07:00
1 parent e167d7df02
commit 0240abfd02
5 files changed
+61 -25

No files matched your search

+5 -3
View File
@@ -21,9 +21,11 @@ public-facing version `4.5.0` → `4.5.1`.
the Worker answers `429 Too Many Requests` with `Retry-After: 60` until the
minute is up; the apps can read that answer, where they would otherwise have
seen a network error. An IPv6 address counts by its /64, the block one
subscriber is normally given. Cloudflare counts per data centre and
approximately, so these are ceilings for abuse, never quotas. The limits are
bindings in `web/wrangler.jsonc` and change by pull request.
subscriber is normally given. Cloudflare keeps these counts per server, so
they stop a client that keeps its connection open, as browsers and most
scripts do; one that reconnects for every request is left to the edge rule,
which counts exactly. They are ceilings for abuse, never quotas. The limits
are bindings in `web/wrangler.jsonc` and change by pull request.
- **Two layers, the edge first.** The zone's rate-limiting rule still refuses
a burst before the Worker runs, at no cost, and is the only limit on the
pages themselves; the Worker adds the one-minute window the Free plan's
+9 -3
View File
@@ -455,9 +455,15 @@ scraping pipeline (`scripts/`) driven by GitHub Actions.
- It FAILS OPEN (no binding, no `CF-Connecting-IP`, a throwing `limit()`).
Vitest and `admin/mock` bind no limiter, which is why no other test sees
it; the catalogue must never fail to load because of this layer.
- Counts are per Cloudflare location and approximate: a limit is an abuse
ceiling far above any client (a cold catalogue load is ~16 data requests),
never a quota to tighten.
- Counts are effectively PER SERVER, whatever the docs say about
"per location" (measured 2026-10-27, SIN): over one keep-alive connection
a budget held exactly (121 then 429), with a new connection per request
it refused nothing (175 human checks in 70 s against 20). So it stops
browsers and connection-reusing scripts; a client that reconnects every
time is the WAF rule's (which counted exactly 250). A limit is an abuse
ceiling far above any client (a cold catalogue load is ~16 data
requests), never a quota to tighten. Test it over ONE connection
(`SECURITY_SETUP.md` §3b), or it looks broken.
- Refusals are not logged: Workers Logs has the 429 status, and a line each
would double a flood's log volume.
- A 429 carries CORS only where its route does (`data`, `api`), never on the
+33 -11
View File
@@ -231,9 +231,11 @@ Two limits, in this order:
pages, which never reach the Worker.
2. **The Worker's limits** (3b, `web/worker/lib/rate-limit.ts`) give each
surface the Worker serves its own budget over 60 seconds. They stop a
client that paces itself just under the WAF's 10-second threshold, and they
keep holding if the WAF rule is edited or deleted - the same reason
`BLOCKED_COUNTRIES` sits beside the country rule (section 4).
client that keeps its connection open and paces itself just under the
WAF's 10-second threshold, and they keep holding if the WAF rule is edited
or deleted - the same reason `BLOCKED_COUNTRIES` sits beside the country
rule (section 4). They count per server, not per data centre (3b), so a
client that reconnects for every request is the WAF rule's to stop.
Neither replaces the other. The WAF rule alone cannot tell a human check from
an image, and the Worker alone has already been invoked, and billed, by the
@@ -326,11 +328,26 @@ the admin surface's Access check included:
| `RL_ADMIN` | `/admin`, `/admin/*`, `/api/ingest/*` | 300 |
- **Key:** the client's IPv4 address, or its IPv6 /64 (one subscriber usually
holds a whole /64). Counted per Cloudflare location and approximately - a
few requests over the limit can pass - so these are ceilings for abuse,
never quotas. Each sits well above what a person, the apps or the discovery
workflow sends: a cold catalogue load is about 16 data requests, a person
sends one human check a day, discovery a few ingest calls a run.
holds a whole /64).
- **What it counts, measured 2026-10-27 in Singapore (SIN), not what the docs
imply.** Cloudflare's documentation says counts are per location and
eventually consistent. In practice each count lives on the server running
the Worker and reaches the rest of the data centre too slowly to matter
within a minute:
- over ONE keep-alive connection the limit held exactly: `/api/no-such-route`
121 × `404` then `429`, `/api/human-check` 19 × `405` then `429`;
- with a new connection per request, which Cloudflare spreads over many
servers, it refused nothing: 175 human checks in 70 seconds, budget 20.
So this layer limits a browser (HTTP/2 carries a whole page on one
connection) and any script that reuses its connection, which is most of
them. A client that reconnects for every request pays a TLS handshake each
time and is stopped by the WAF rule, which counted exactly (3a). Either way
these are ceilings for abuse, never quotas. Each sits well above what a
person, the apps or the discovery workflow sends: a cold catalogue load is
about 16 data requests, a person sends one human check a day, discovery a
few ingest calls a run. A strict per-data-centre count would need a Durable
Object on every request - not worth it while the WAF rule exists.
- **Refusal:** HTTP 429, `{"error":"too many requests"}`, `Retry-After: 60`,
`Cache-Control: no-store`. `/api/data/*` and the public API also carry
`Access-Control-Allow-Origin: *`, so the packaged apps see the 429 instead
@@ -353,13 +370,18 @@ the admin surface's Access check included:
within the Cloudflare account: two bindings with one ID share their
counters, across Workers too.
**Check** (after a deploy; spends 130 cheap invocations):
**Check** (after a deploy; spends 130 cheap invocations). One `curl` with
the list on stdin and no `--parallel` sends every request over the same
connection, which is what this layer counts:
```bash
seq 1 130 | xargs -P 10 -I{} curl -s -o /dev/null -w '%{http_code}\n' https://free-steam-games.win/api/no-such-route | sort | uniq -c
for i in $(seq 1 130); do printf 'url = "https://free-steam-games.win/api/no-such-route"\noutput = "/dev/null"\n'; done | curl -s -w '%{http_code}\n' -K - | sort | uniq -c
```
Expected: about 120 × `404`, then `429` for the rest of that minute.
Expected: about 120 × `404`, then `429` for the rest of that minute (measured
2026-10-27: 121 and 19; on Windows `curl.exe`, write `NUL` for `/dev/null`).
A loop or `xargs` of separate `curl`s connects anew each time and may see no
`429` at all - that is the per-server counting above, not a broken limit.
---
+8 -4
View File
@@ -15,10 +15,14 @@
* the WAF rule is all that limits them.
*
* The limits are `ratelimits` bindings in wrangler.jsonc, one per class below.
* Cloudflare counts per location and approximately (a few requests over the
* limit can pass), so a limit here is a ceiling for abuse, never an accurate
* quota - every number sits well above what a person, the apps or the
* discovery workflow sends.
* Cloudflare documents them as per location and eventually consistent; what
* was measured (2026-10-27, SIN) is per SERVER: over one keep-alive connection
* a budget held exactly, with a new connection per request it refused nothing.
* So this stops browsers (HTTP/2, one connection a page) and scripts that
* reuse their connection; one that reconnects every time is the WAF rule's,
* which counts exactly. A limit here is a ceiling for abuse, never a quota -
* every number sits well above what a person, the apps or the discovery
* workflow sends.
*
* FAIL OPEN. A missing binding (Vitest, `admin/mock`, a config that lost one),
* a request without CF-Connecting-IP, or a limit() call that throws lets the
+6 -4
View File
@@ -102,10 +102,12 @@
// still hold if that rule is edited or deleted. They see only the four
// `run_worker_first` prefixes - the prerendered pages are the WAF's alone.
//
// Counts are per Cloudflare location and approximate; the key is the
// client's IPv4 address or IPv6 /64. Over a limit the Worker answers 429
// with Retry-After: 60, so every "period" stays 60 (rate-limit.test.ts
// holds that). A namespace_id must be unique within the Cloudflare account:
// Counts are effectively per server (measured: a budget held exactly over
// one keep-alive connection and not at all across fresh connections), so a
// client that reconnects for every request is the WAF rule's to stop. The
// key is the client's IPv4 address or IPv6 /64. Over a limit the Worker
// answers 429 with Retry-After: 60, so every "period" stays 60
// (rate-limit.test.ts holds that). A namespace_id must be unique within the Cloudflare account:
// two bindings that share one share counters, across Workers too.
//
// RL_DATA /api/data/* a cold catalogue load is ~16 requests