diff --git a/README.md b/README.md index 1a903c1..8d86384 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ `feedreader` is server-rendered HTML with vanilla JS/CSS — no framework runtime, no client hydration, no bundler payload. That keeps it genuinely tiny and fast, not just "fast for a SPA." -The home page has no render-blocking asset requests: the stylesheet and pre-paint theme bootstrap are inlined into the HTML, and the response is edge-cached per URL for five minutes. Versioned static assets are served with immutable browser caching; see [`web-static/_headers`](web-static/_headers). +The home page has no render-blocking asset requests: the stylesheet and pre-paint theme bootstrap are inlined into the HTML, and the response is edge-cached per URL for five minutes. The browser-facing copy is `private, no-store`; the five-minute cache lives in the Worker Cache API. Versioned static assets are served with immutable browser caching; see [`web-static/_headers`](web-static/_headers). Lighthouse against the production deployment (mobile, simulated throttling): diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0ed9ad7..58666a4 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -73,7 +73,7 @@ This keeps refresh logic, rendering, and feed shaping independent of D1-specific ## Caching -- `GET /` is cached per URL (including the raw query string) for five minutes through the Cache API. `APP_VERSION` is part of the key and changes on every deploy, so a release invalidates old HTML; local `wrangler dev` keeps `APP_VERSION` at `dev` and skips the home cache so template/CSS edits are never hidden. +- `GET /` is cached per URL (including the raw query string) for five minutes through the Cache API. `APP_VERSION` is part of the key and changes on every deploy, so a release invalidates old HTML; local `wrangler dev` keeps `APP_VERSION` at `dev` and skips the home cache so template/CSS edits are never hidden. The browser-facing response is `private, no-store`: the five-minute copy is internal to the Cache API, which keeps Cloudflare's Browser Cache TTL setting from rewriting the client TTL. - `GET /api/items` is edge-cached until the underlying sources next refresh (the key includes `sync_state.last_success_at`). Successful article previews are cached for 30 minutes. - `style.css` and `theme-init.js` are read from the `ASSETS` binding once per isolate and inlined into the server-rendered HTML, so first paint has no render-blocking network requests. The files remain the single source of truth and are still served directly for cached shells. - [`web-static/_headers`](../web-static/_headers) marks versioned static assets as immutable for a year; `service-worker.js` keeps `must-revalidate` so updates land. diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index fc9a8d9..e472560 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -62,7 +62,7 @@ The checked-in `wrangler.toml` config does not hardcode a route. Domain attachme - D1: 5GB storage, 5M row reads/day, 100k row writes/day. - Workers: 100k requests/day, 10ms CPU time per invocation, 50 subrequests per request. -- The five-minute home-page cache absorbs most `GET /` traffic, so only cache misses run the feed query and render the HTML. Each cold-isolate cache miss also reads `style.css` and `theme-init.js` through the `ASSETS` binding (two local subrequests), then reuses them in memory. +- The five-minute home-page cache absorbs most `GET /` traffic, so only cache misses run the feed query and render the HTML. The browser response is `private, no-store`; edge caching is the Worker Cache API, not the CDN, so the zone's Browser Cache TTL setting cannot rewrite the client TTL. Each cold-isolate cache miss also reads `style.css` and `theme-init.js` through the `ASSETS` binding (two local subrequests), then reuses them in memory. - The standalone launch veil and skeleton styles are inlined with the existing HTML/CSS, so they add no extra requests. Bump the shell cache version when the HTML shell or `app.js` changes; see [RUNBOOK.md](RUNBOOK.md#pwa-shell-updates). - Article previews add one outbound fetch (and one `node-html-parser` parse) per uncached `/api/preview` request. The 400 KB body cap and 30-minute edge cache in `core/preview.ts` bound that cost; watch the CPU-time panel if preview usage is heavy. Richer preview blocks (inline links, captions, tables) increase the cached response payload but not the upstream fetch count; the same byte cap and cache TTL apply. diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md index d3734ae..1073186 100644 --- a/docs/RUNBOOK.md +++ b/docs/RUNBOOK.md @@ -99,7 +99,7 @@ Before considering any `core/render.ts` change done: 3. Load `http://127.0.0.1:8788` and verify: - the document has no external `style.css` or `theme-init.js` request; both are inlined in `` - - the response carries `Cache-Control: public, max-age=0, s-maxage=300` + - the response carries `Cache-Control: private, no-store` (the five-minute edge copy lives in the Cache API and is rewritten to this header on the way out) - in a regular browser tab the launch veil stays hidden (`display: none`) and is removed from the DOM; in an installed/standalone window it is visible and fades out within about a second - throttle the network, then change a source filter or run a search: skeleton cards appear after ~150 ms and are replaced by the new cards; `View more` appends three skeleton rows - enable article preview, throttle the network, and open a card: the card title stays visible while a preview skeleton appears in the panel, then the fetched title/content fade in; a failed preview clears the skeleton and shows the error status diff --git a/platforms/cloudflare/src/index.ts b/platforms/cloudflare/src/index.ts index e487450..f7500f2 100644 --- a/platforms/cloudflare/src/index.ts +++ b/platforms/cloudflare/src/index.ts @@ -75,6 +75,12 @@ const ITEMS_CACHE_TTL_SECONDS = 21600; // fresh items are only as current as the last source refresh, and a deploy // changes the content through APP_VERSION in the cache key. const HOME_CACHE_TTL_SECONDS = 300; +// The browser copy must always revalidate. `no-store` also keeps Cloudflare's +// CDN from caching the Worker response, because the zone's Browser Cache TTL +// setting rewrites `max-age` on CDN-cached HTML (observed as a 4-hour TTL). +// Edge caching is handled explicitly by the Cache API instead. +const HOME_CLIENT_CACHE_CONTROL = "private, no-store"; +const HOME_EDGE_CACHE_CONTROL = `public, max-age=${HOME_CACHE_TTL_SECONDS}`; // Reader previews are fetched on demand when the user opens the side panel. // A short edge cache keeps repeated clicks from re-fetching the same article @@ -156,7 +162,7 @@ async function handleHome( const cacheRequest = homeCacheRequest(url, appVersion); if (homeCacheEnabled) { const cached = await readEdgeCache(cacheRequest); - if (cached) return cached; + if (cached) return clientHomeResponse(cached); } const [{ items, hasNext }, states, inlineCss, themeInitScript] = @@ -191,16 +197,33 @@ async function handleHome( inlineCss, themeInitScript, }); - const response = new Response(html, { + const clientHeaders = { + "Content-Type": "text/html; charset=utf-8", + "Cache-Control": HOME_CLIENT_CACHE_CONTROL, + }; + if (!homeCacheEnabled) { + return new Response(html, { headers: clientHeaders }); + } + const cacheResponse = new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8", - "Cache-Control": `public, max-age=0, s-maxage=${HOME_CACHE_TTL_SECONDS}`, + "Cache-Control": HOME_EDGE_CACHE_CONTROL, }, }); - if (homeCacheEnabled) { - await writeEdgeCache(cacheRequest, response.clone(), HOME_CACHE_TTL_SECONDS); - } - return response; + await writeEdgeCache(cacheRequest, cacheResponse, HOME_CACHE_TTL_SECONDS); + return new Response(html, { headers: clientHeaders }); +} + +/** Rewrites the cached edge copy into the browser-facing copy. The Cache API + * keeps the `public` response; clients only ever see `private, no-store`. */ +function clientHomeResponse(cached: Response): Response { + const headers = new Headers(cached.headers); + headers.set("Cache-Control", HOME_CLIENT_CACHE_CONTROL); + return new Response(cached.body, { + status: cached.status, + statusText: cached.statusText, + headers, + }); } async function handleHealthz(