Skip to content

fix(preview): add failure reasons, retries, and cache TTL split - #19

Merged
phatpham9 merged 1 commit into
mainfrom
fix/preview-reliability-and-cache
Nov 13, 2026
Merged

phatpham9 merged 1 commit into
mainfrom
fix/preview-reliability-and-cache

Conversation

@phatpham9

Copy link
Copy Markdown
Member

Summary

Step 1 of the preview-reliability plan, plus the preview cache-TTL fix. The cron/refresh design is unchanged.

Structured preview failures

  • PreviewUnavailableError now carries a reason and optional upstreamStatus:
    blocked, rate_limited, upstream_error, timeout, unsupported_content_type, too_large, empty_body, redirect, invalid_url.
  • 401/403 map to blocked, 429 to rate_limited, and 5xx to upstream_error.
  • Transient upstream 429/5xx responses are retried once with jitter. The shared timeout signal bounds the total fetch time.
  • handlePreview logs preview_unavailable / preview_empty events with the URL, reason, and upstream status, and returns the reason to the client.
  • The preview panel now shows specific messages for blocked sources, temporary upstream failures/timeouts, unsupported formats, and oversized articles instead of one generic error.
  • Truncated HTML now falls back to <html> as the content root, so a capped page can still extract a readable prefix. If truncation leaves no readable blocks, it is reported as too_large.

Cache TTL split for preview and items

  • /api/preview and /api/items now use the same split as the home page:
    • the Cache API stores the edge copy (public, max-age=1800 / 21600),
    • clients always receive private, no-store.
  • This prevents Cloudflare's Browser Cache TTL setting from rewriting the preview's 30-minute TTL to 4 hours (observed in production: cf-cache-status: HIT, max-age=14400).
  • Explicit expirationTtl keeps the internal 30-minute / 6-hour Cache API lifetimes.
  • The service worker still stores preview/item responses in Cache Storage for offline reuse; Cache Storage ignores Cache-Control.

Versions

  • app.js → v109
  • reader-shell → v143

Verification

  • 92 tests passing (vitest run --exclude '.claude/**'; a local stale worktree under .claude/ otherwise doubles discovery)
  • Typecheck, npm audit (0), wrangler deploy --dry-run
  • Local end-to-end:
    • Reuters → 502 reason=blocked, upstream_status=401, log preview_unavailable; panel shows “This source blocks reader previews.”
    • arXiv PDF → 502 reason=unsupported_content_type; panel shows “This article format can't be previewed.”
    • Preview and items responses return private, no-store on both a miss and a Cache API hit.
    • Warm cache still omits a newly inserted D1 probe row; a fresh cache key includes it.
    • Service worker still caches the shell for offline reuse.
  • Unit tests cover blocked, retry-then-success, persistent 5xx, timeout, and truncation/too_large.

Post-deploy check

After deploy, /api/preview responses should carry cache-control: private, no-store, and a blocked source should return reason: "blocked" plus upstream_status in the 502 body. Worker Logs should show preview_unavailable events.

🤖 Generated with Claude Code

- PreviewUnavailableError now carries a structured reason and optional
  upstream status: blocked, rate_limited, upstream_error, timeout,
  unsupported_content_type, too_large, empty_body, redirect, invalid_url
- Retry transient upstream 429/5xx responses once with jitter; map timeouts
  and 401/403/429/5xx separately
- handlePreview logs preview_unavailable/preview_empty and returns the reason
  to the client, which shows specific blocked/temporary/format/size messages
- Split preview and /api/items cache responses: the Cache API keeps the
  public 30-minute / 6-hour edge copy, while clients always receive
  private, no-store so the CDN Browser Cache TTL cannot extend them
- Fall back to <html> for truncated documents so capped pages still extract
  readable prefixes; label truncation with too_large when nothing is readable
- Bump app.js to v109 and the shell cache to v143
- Add retry/reason/timeout/too_large tests and update the docs

Verified locally: Reuters -> 502 reason=blocked upstream_status=401 and the
client shows the blocked-source message; arXiv PDF -> reason=unsupported_content_type
with the format message; preview and items both return private, no-store on
miss and Cache API hit; 92 tests, typecheck, audit, and dry-run pass.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

🔎 Cloudflare preview: https://055d62a1-feedreader.phatpham9.workers.dev

Uploaded from 8e53f07d68503592f9153bced308d2519174c5f7. This is a Worker version preview — it shares the production D1 database, so it reads/writes real data; it does not receive cron-triggered refreshes.

@phatpham9
phatpham9 merged commit 2e0281d into main Nov 13, 2026
3 checks passed
@phatpham9
phatpham9 deleted the fix/preview-reliability-and-cache branch November 13, 2026 04:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant