All non-static routes now return Cache-Control: no-store to prevent
Cloudflare edge caching of dynamic API responses. Static assets
(/, /assets/config.js, /assets/styles.css) are exempted to allow
edge caching for performance.
Cloudflare may cache responses based on origin headers or its own
heuristics. Stale cached API/webhook responses would mask real backend
state changes (e.g., stale health probes, cached config reads, cached
webhook receipts). The no-store directive prevents this entirely.
Implementation:
- withNoStore(response) helper appends Cache-Control: no-store header
- Applied to all dynamic routes: /api/*, /webhook/*, /push/*,
/reconcile, /worker, /healthz*, /ready
- Static asset routes (/, /assets/*) exempt
- Error responses (404/405/503) also get no-store
Tests:
- New tests verify no-store presence on dynamic routes
- New tests verify static routes remain exempt
- All 43 tests pass
Docs:
- Both READMEs: updated pass-through semantics, test counts 38->43,
per-file breakdown (index 15->19, lb 12->13)
- retired.md: fixed index.js anchor 77-92->104-117 (drift from this
commit's line additionsBump LB_VERSION to 2026.10.14
GATE-DOCS: 6/6 clean
Two changes requested by the user:
1. Fold the hand-holding quickstart tutorial into README §3 (both
languages). Delete docs/quickstart.md and docs/quickstart.zh-CN.md.
Remove them from all 5 validator DOCS lists, README §6 doc index,
and charter §7 boundary table. The tutorial now lives as
README §3.0–§3.11: prerequisites, create Telegram bot, find chat id,
get JMAP credentials, run backend, sign in, fill config, register
callbacks, enable processing, verify, schedule drain, troubleshoot.
2. Replace 'gateway'/'网关' with 'load balancer'/'负载均衡器' across
all markdown (README, docs/, AGENTS.md, cloudflare-worker/README).
Also fix 4 markdown anchor links whose heading slugs changed.
Also fix charter §8 '18 safe routes' → '19' (was missed in the
earlier reference.md fix).
GATE-DOCS 6/6 PASS (71 anchors, 727 path-refs, 455 sec-refs).
Reframe the Cloudflare Worker gateway across the entry points where a
reader forms an impression of it, in both languages:
- README §2 / §5 (en+zh): the gateway is optional and exists because
Cloudflare's Load Balancer product is not on the free plan. Drop the
comparison row that listed 'only the 19 safelisted paths' against
'every route' as if the safelist were a benefit; replace it with
backend reachability, which is identical either way, and move the
route-count fact to its own neutral row. Add one sentence to §5 that
the gateway is outside the secret boundary.
- deployment.md §10 (en+zh): purpose is load balancing, not protection;
no intent to hide or harden the backends, no access control at the
edge, the allowlist is not a firewall.
- cloudflare-worker README (en+zh): new 'why it exists' / 'why it is
not a security feature' block, plus a 'not a security layer' bullet.
Drop 'access-hiding capability' from the non-capabilities list, since
claiming invisibility as something we refuse to provide implies it is
the interesting axis.
- reference.md §4 / §9.2 (en+zh) and deployment.md zh §2: stop saying
bootstrap and /debug/* are 'not exposed' / 'kept off the public path'.
They are simply not in the route set, which is why a request to the
Worker never reaches them — reachable at the backend's own address
either way.
- charter ARCH-LB-WORKER (en+zh): 'only external entrance' -> 'only
*registered* entrance', which is what C-LB-SINGLE-REG-URL actually
says, and backends stay directly reachable.
SAF-LB-PASSTHRU already records the security-side invariant (no auth
or body rewriting, backend may be directly connected to the public
network), so no new stable ID is needed. No code changes; GATE-DOCS
6/6.
Root README gains §2 "Two ways to run it": a side-by-side table of
Form A (backend origin only) against Form B (behind the Cloudflare Worker
gateway) — what answers, failover, the callback URL to register, the
reachable route surface, which health endpoint to watch, and the docs to
read. Late in the switch: registration is idempotent and re-adding retires
the previous subscription, so the switch is one SPA field, not a migration;
nothing secret moves to the gateway; /api/bootstrap and /debug/* stay
origin-only either way. Later sections renumbered, and the monitoring
paragraph now points at the gateway aggregate GET /healthz-worker instead
of the origin-passthrough /healthz.
cloudflare-worker/README.md rewritten as the canonical English version and
cloudflare-worker/README.zh-CN.md added as its translation, covering the
route safelist (19 paths with per-path methods), the timeout/retry budget
with per-route overrides, bounded failover, the two health endpoints,
callback registration, config, local verification, deploy, and the design
invariants.
Both fixes along the way:
- README.zh-CN said the startup env block has 2 required + 2 optional
variables; the table has 3 rows, 2 required + 1 optional.
- docs/charter.md §8 / registry list now names the zh-CN twin next to the
gateway README.
scripts/docs_check gains the new file in validate_docs, check_tables,
audit_anchors and audit_anchor_semantics so it is checked like every other
document. check_sec_refs resolves §-refs against the document being scanned
when a basename is shared: README.md exists both at the repo root and under
cloudflare-worker/, and the basename-keyed heading map silently dropped one
of them. The gate was passing for the wrong reason before.
GATE-DOCS 6/6 clean: 72 anchors, 454 section refs, 727 path refs.
audit_anchor_semantics still reports the same 7 pre-existing candidates,
none in the new or edited files.
anonsaber