Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):

Expand Down
2 changes: 1 addition & 1 deletion docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<head>`
- 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
Expand Down
37 changes: 30 additions & 7 deletions platforms/cloudflare/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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] =
Expand Down Expand Up @@ -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(
Expand Down
Loading