From b148f9163509a5846ca9f5772f747eddd650cb7a Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 27 Oct 2026 05:55:18 +0700 Subject: [PATCH] =?UTF-8?q?docs:=20rate=20limits=20are=20approximate=20?= =?UTF-8?q?=E2=80=94=20measured=20on=20production=20(#159)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cloudflare's Rate Limiting binding checks a locally cached count per edge machine and syncs it in the background. On production one keep-alive connection hits the limits almost exactly (120 pages, then 429s), but 300 requests on fresh parallel connections in 13 s all passed. Say so in DEPLOYMENT.md and the rate-limit.ts header instead of "overshoot slightly", and document a one-connection curl test for production. Co-authored-by: Claude Opus 5.5 --- docs/DEPLOYMENT.md | 19 ++++++++++++++----- worker/rate-limit.ts | 8 +++++--- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 5d9d1d3..9be2183 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -243,10 +243,16 @@ Three [Rate Limiting bindings](https://developers.cloudflare.com/workers/runtime gets a JSON 429 `{"ok":false,"error":"rate_limited"}`; both carry `Retry-After: 60` and `Cache-Control: no-store`. The app treats a 429 from the verify endpoint as "check unavailable" and lets the user continue. -- Counters live per Cloudflare data centre and update asynchronously, so a - burst can overshoot slightly before the 429s start. If the limiter itself - fails the request goes through (`ratelimit.error` in the logs): a broken - counter must not take the site down. +- The limits are approximate. Counts are kept per Cloudflare data centre, and + each edge machine checks a locally cached count that syncs in the + background. Measured on production (2026-10-27): on one keep-alive + connection they hold almost exactly (120 pages, then 429s), but 300 + requests on fresh parallel connections in 13 s all passed, because they + spread over many machines before the counts caught up. They throttle + browsers, crawlers and simple scripts; a strict cap would need a Durable + Object or a WAF rule (below). +- If the limiter itself fails the request goes through (`ratelimit.error` in + the logs): a broken counter must not take the site down. - Every request that reaches the Worker is billed as a Worker request, refused ones included. The limits keep floods off the API and slow scrapers; volumetric attacks are Cloudflare's DDoS protection's job, in front of the @@ -258,7 +264,10 @@ Three [Rate Limiting bindings](https://developers.cloudflare.com/workers/runtime `namespace_id` unique within the Cloudflare account. - To see it work locally, run `npm run preview:cf` and then `for i in $(seq 70); do curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8787/api/health; done | sort | uniq -c` - — 60 × 200, then 429s for the rest of the minute. + — 60 × 200, then 429s for the rest of the minute. Against production, send + the burst over one connection so it reaches one machine, e.g. + `curl -s -w '%{http_code}\n' $(printf -- '-o /dev/null https://jsonprism.poli0981.dev/api/health %.0s' $(seq 100)) | sort | uniq -c` + (this throttles your own address for a minute). ## Workers Logs diff --git a/worker/rate-limit.ts b/worker/rate-limit.ts index 4aecb82..91e19b9 100644 --- a/worker/rate-limit.ts +++ b/worker/rate-limit.ts @@ -4,9 +4,11 @@ * files count against SITE_LIMITER, /api/* against API_LIMITER, and the * human-check endpoint also against its own VERIFY_LIMITER. * - * Cloudflare counts per data centre and updates the counters asynchronously, - * so a burst can overshoot slightly before the 429s start. The limits stop - * floods and scrapers; people never get near them. + * Cloudflare's counts are approximate: each edge machine checks a locally + * cached per-data-centre count that syncs in the background, so a burst + * spread over many fresh connections can pass well beyond the limit before + * the 429s start (see docs/DEPLOYMENT.md). The limits throttle browsers, + * crawlers and simple scripts; people never get near them. */ import { json, logEvent, text } from './http';