[jonocodes]

Closes #86.

Problem

When the CORS proxy is maxed out (Cloudflare free plan, error 1027), saves and images fail with no explanation. The 1027 page comes from Cloudflare's edge, not our worker, so it has no CORS headers. The browser then reports a bare TypeError with no status, and the governor's 429 breaker never tripped.

What this does

Detection (src/utils/net/proxyHealth.ts, pure and unit-tested):

• When a proxied fetch fails at the network level (no visible status, timeouts included) or gets a 429, the governor asks a health monitor whether the proxy is at fault.
• The monitor probes the configured prefix with an empty target, once with CORS and once with no-cors. Our worker answers that probe with a CORS 400, for public, path-token and query-token prefixes, and also behind the Restrict the public CORS proxy to allowlisted calling sites #118 origin allowlist.
• How the probe results are read:

Probe result	Verdict
CORS request gets 429	Rate-limited (the proxy itself)
CORS request gets any other answer	Proxy running; the target failed. Only that URL backs off, no banner
Only the no-cors request gets an answer	Responding but not working: likely capped, or the worker crashed
Neither gets an answer while online	Unreachable
Offline	No verdict

• The 429 is probed because the worker passes a target site's own 429 straight through. Before this PR, any 429 paused every proxied request.
• A bad verdict trips the existing breaker. A burst of failures trips it once rather than escalating the cooldown.
• Probes are shared between simultaneous failures and run at most once a minute.

UX: says only what was observed, with the issue's exact copy and no reset times.

• A non-blocking banner on the article list and the add screen. It links to Preferences → CORS Proxy and, on the shared default proxy, to "Set up your own proxy".

• On desktop, the banner also notes that saving with the browser extension needs no proxy.

• While the proxy is failing, a failed save or refetch says so ("Couldn't save: your CORS proxy isn't working. See the notice above.") instead of offering "Report this failed article?". The article isn't at fault, so a report would only be noise.

• A status line in Preferences and in Diagnostics.

• Diagnostics also shows the raw probe evidence and a per-device "proxy requests today" count. The proxy token stays masked.

• The banner clears as soon as any response comes back through the proxy or a probe succeeds. Changing the proxy setting resets it.

• All new copy is translated (English and Spanish) via i18next, under common.proxyHealth and diagnostics.*.

There is no automatic switching or fallback, as the issue's non-goal requires.

Tests

• Unit:

  • probe classifier, including a CORS 429 meaning rate-limited;
  • monitor: throttle, coalescing, offline, clears on success, reset, subscriptions;
  • governor diagnosis: proxy at fault or not, on network failures and on 429s; timeouts vs aborts; a burst trips once; 429 without diagnosis; resetBreaker.

• Worker: the empty-target probe gets a CORS 400 for every prefix shape, and behind the origin allowlist.

• Playwright (tests/e2e/proxy-health.spec.ts):

  • the proxy's own 429;
  • a target's 429 behind a working proxy: no banner, and the report dialog is still offered;
  • a capped edge: banner, "Couldn't save" notice, no report dialog, extension hint, Preferences status;
  • unreachable;
  • a network-failing target behind a working proxy: no banner.

  route.fulfill() adds Access-Control-Allow-Origin by itself, so the capped-edge case uses a real local server that answers 429 error code: 1027 with no CORS headers.

• Results (after rebasing onto main with i18n): Jest 472 passed, node --test for the worker/stats 63 passed, tsc clean. Full e2e: 100 passed and 2 failed. The two failures are multi-browser/natural sync specs that configure no proxy, so they never reach this code, and they passed when re-run alone (4/4). They've been flaky under full-suite load on this branch before.

Still open

• Step 1 of the issue (the real 1027 response) is split out to Verify what a capped Cloudflare worker (error 1027) actually returns #123 for separate discussion. The detection already handles the page arriving with or without CORS headers; Verify what a capped Cloudflare worker (error 1027) actually returns #123 confirms which one it is.

🤖 Generated with Claude Code

Screenshots

Capped proxy (stand-in 1027 answer, no CORS headers): banner on the article list, and the failed save names the proxy instead of offering a failure report

The same observation as a status line under Preferences → CORS Proxy

[netlify]

✅ Deploy Preview for savrlist ready!

Name	Link
🔨 Latest commit	6e8b1a9
🔍 Latest deploy log	https://app.netlify.com/projects/savrlist/deploys/6ad26830f04627f11adf5354
😎 Deploy Preview	https://deploy-preview-119--savrlist.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.