domma-cms 1.8.25 → 1.8.27

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [1.8.27] - 2026-10-19
+
+- **Pages come out of the cache about twice as fast.** Every public request decided whether you may see the page before it looked in the response cache, and that decision parsed the whole page - shortcodes, collections and all - so a cached page still cost a full parse on every visit. The parsed page is now kept per file (keyed on the file's time and size, emptied whenever anything leaves the response cache, and only while the cache is on), so a cached page costs a file stat and a lookup. On a 40 KB home page: 230 to 540 pages a second, the typical response from 41 ms to 18 ms under load.
+- **A cached page is compressed once, not on every visit.** The response cache held the page as HTML and brotli ran on it for every visitor; the compressed body is now kept as well, per encoding, addressed by the page's own content hash (so it can never be stale and needs no invalidation). After the change above this was most of what a cached page still cost. The ETag now names the encoding (`"<hash>-br"`); a browser holding the other one's validator still gets its 304.
+- **`x-dm-cache` on every page response** says which way it went: `hit`, `miss`, `off` (the cache is disabled) or `bypass` (a draft, an expiring page or a per-viewer page, never cached). `GET /api/cache/status` gains `pageMemo` (size, hits, misses).
+
+## [1.8.26] - 2026-10-18
+
+- **Updates clear out their old backups.** Every `npx domma-cms update` copies the engine and plugins into `.domma-backups/` first, and nothing ever removed those copies - some sites held 250+ of up to 490 MB each. After a successful update it now keeps the newest 7, plus one about a week, a month, three, six and twelve months old (at most 16), and nothing older than a year. Backups you put in that folder yourself, under any other name, are never touched.
+
 ## [1.8.25] - 2026-10-18
 
 - **Tutorial: The Editor.** A walk through a working session in the editor - the list, the tabs, coloured text, the live preview, saving and drafts, and the settings (font, wrapping, smooth typing, the admin menu folding away). Under Documentation › Tutorials, first in the list on every site.

package/bin/lib/backup-retention.js

@@ -0,0 +1,66 @@
+/**
+ * Update backups, for the engine updater.
+ *
+ * Every update copies the engine's code, structural configs and plugins into
+ * .domma-backups/<timestamp>/ (about 500 MB on a site with plugins) and nothing
+ * ever removed them: a site that rolled a few times a day had 250+ of them. The
+ * updater now keeps the newest few plus one backup per age band - about a week,
+ * a month, three months, six months and a year old - and nothing older than a
+ * year. Only the names the updater writes are counted: anything else in the
+ * folder was put there by hand and is left alone.
+ *
+ * Each band keeps its OLDEST backup - that is what lets one move up: it ages out
+ * of its band into the next. Past the first week a band also keeps its NEWEST,
+ * the next in line, so when the oldest moves on the band is never left empty
+ * (with only the oldest kept, the year band stood empty 44% of the time at three
+ * updates a day). So at most 7 + 1 + 2 x 4 = 16 are kept.
+ *
+ * @module bin/lib/backup-retention
+ */
+
+import {existsSync, readdirSync, rmSync} from 'node:fs';
+import path from 'node:path';
+
+/** How many of the newest update backups a site keeps outright. */
+export const KEEP_UPDATE_BACKUPS = 7;
+
+const DAY = 24 * 60 * 60 * 1000;
+
+/** Age bands, in days: [from, to). The first starts at 0 so a backup can survive long enough to reach a week. */
+export const BACKUP_BANDS = [[0, 7], [7, 30], [30, 90], [90, 180], [180, 365]];
+
+/** `new Date().toISOString()` with `:` and `.` made `-` - the updater's own names. */
+const UPDATE_BACKUP_NAME = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/;
+
+/** When an update backup was taken, from its name; null for a name the updater did not write. */
+export function backupTime(name) {
+    const m = UPDATE_BACKUP_NAME.exec(name);
+    if (!m) return null;
+    const t = Date.parse(`${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`);
+    return Number.isNaN(t) ? null : t;
+}
+
+/** The update backups to remove from a listing, oldest first. Pure: `now` is a timestamp in ms. */
+export function backupsToPrune(names, now = Date.now(), keep = KEEP_UPDATE_BACKUPS) {
+    const ours = names
+        .map(name => ({name, at: backupTime(name)}))
+        .filter(b => b.at !== null)
+        .sort((a, b) => a.at - b.at);
+    const kept = new Set(ours.slice(-keep).map(b => b.name));
+    BACKUP_BANDS.forEach(([from, to], i) => {
+        const inBand = ours.filter(b => now - b.at >= from * DAY && now - b.at < to * DAY);
+        if (!inBand.length) return;
+        kept.add(inBand[0].name);
+        if (i > 0) kept.add(inBand.at(-1).name);
+    });
+    return ours.filter(b => !kept.has(b.name)).map(b => b.name);
+}
+
+/** Apply the retention rule to `dir`. Returns the names removed. */
+export function pruneUpdateBackups(dir, now = Date.now()) {
+    if (!existsSync(dir)) return [];
+    const names = readdirSync(dir, {withFileTypes: true}).filter(e => e.isDirectory()).map(e => e.name);
+    const doomed = backupsToPrune(names, now);
+    for (const name of doomed) rmSync(path.join(dir, name), {recursive: true, force: true});
+    return doomed;
+}

package/bin/update.js

@@ -15,6 +15,7 @@ import {createInterface} from 'node:readline';
 import {fileURLToPath} from 'node:url';
 import {deepMergeNewKeys} from './lib/config-merge.js';
 import {shouldReplacePlugin} from './lib/plugin-version.js';
+import {KEEP_UPDATE_BACKUPS, pruneUpdateBackups} from './lib/backup-retention.js';
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -567,6 +568,13 @@ export default async function update(_positional, flags) {
         console.log('');
     }
 
+    // -------------------------------------------------------------------------
+    // 13b. Thin the update backups (bin/lib/backup-retention.js) - done last, so a failed update
+    //      never costs a backup, and only when this run took one.
+    // -------------------------------------------------------------------------
+
+    const prunedBackups = backupPath ? pruneUpdateBackups(path.join(cwd, '.domma-backups')) : [];
+
     // -------------------------------------------------------------------------
     // 14. Summary
     // -------------------------------------------------------------------------
@@ -581,6 +589,9 @@ export default async function update(_positional, flags) {
 
     if (backupPath) {
         info(`Backup saved to: .domma-backups/${path.basename(backupPath)}/`);
+        if (prunedBackups.length) {
+            info(`Removed ${prunedBackups.length} older update backup(s): the newest ${KEEP_UPDATE_BACKUPS} are kept, plus one about a week, a month, 3, 6 and 12 months old.`);
+        }
     }
 
     if (newPlugins.length > 0) {

package/docs/DommaFeatures.md

@@ -1280,9 +1280,10 @@ The four Tools below were plugins until 0.67.0 and are now part of the CMS. They
   - Registers new plugins, disabled except the protective ones such as Security.
   - Adds only new keys to `server.json`, `auth.json`, `content.json` and `presets.json`.
   - Swaps the CMS dependencies but keeps dependencies you added, self-heals `.gitignore`, updates the marker and runs `npm install`.
+  - Thins `.domma-backups/` after a successful update: the newest 7 update backups, plus the oldest and newest backup aged 7-30 days, 30-90 days, 90-180 days and 180-365 days (and the oldest under a week), so one about a week, a month, three, six and twelve months old is always there - at most 16. Nothing older than a year is kept, and backups not named by the updater are never touched (unreleased).
   
   Options: `--yes`, `--no-backup`, `--no-install`, `--dry-run` (preview only), `--force` (reinstall the same version).
-  Where: `bin/update.js`, `bin/lib/config-merge.js`, `bin/lib/plugin-version.js` - Since: 0.6.5.
+  Where: `bin/update.js`, `bin/lib/config-merge.js`, `bin/lib/plugin-version.js`, `bin/lib/backup-retention.js` - Since: 0.6.5.
 - **`npm run setup`** - The terminal setup wizard:
   1. Generates `JWT_SECRET` and `INSTANCE_SECRET`.
   2. Creates the first admin if there are no users (password of at least 8 characters).

package/docs/cache.md

@@ -73,6 +73,27 @@ All endpoints require an admin Bearer token. The dashboard has a cache widget sh
 
 When you toggle the cache **off**, the in-memory data is preserved - toggle back on and your warm entries are still there. When you turn it **off in `config/cache.json`** and restart, the next boot starts with a `NoneDriver` and no data.
 
+## Seeing whether a page was cached
+
+Every page response carries `x-dm-cache`:
+
+| Value | Meaning |
+|---|---|
+| `hit` | served from the response cache |
+| `miss` | rendered on this request and stored |
+| `off` | the cache is disabled; rendered |
+| `bypass` | never cached: a draft preview, a page with expiring shortcodes, or a per-viewer page for a signed-in visitor |
+
+Open the browser's network panel, or `curl -sI https://example.com/ | grep x-dm-cache`.
+
+## The parsed-page memo
+
+Before the response cache is asked, the route decides whether the viewer may see the page at all (`resolvePublishedPage()`), and that decision reads the page with `getPage()`, which parses the body to learn whether it expires, renders per viewer, and which collections and blocks it uses. Without help a cache hit still paid for that parse. `content.js` keeps the anonymous parse per file, keyed on the file's mtime and size, emptied through `cache.onInvalidate()` whenever anything leaves the response cache, and only while the cache is enabled. A viewer's read (`{user}`) or an expiry read is never memoised. `GET /api/cache/status` reports it as `pageMemo`.
+
+## The compressed body
+
+`services/htmlResponse.js` `sendHtml()`: a page that came from the response cache (`{cached: true}` - the page route and the docs route) is also kept compressed, one entry per encoding under `enc:<br|gzip>:<sha1 of the HTML>`. Content-addressed, so never stale and never invalidated; bounded by the cache's LRU and TTL. The negotiation and parameters match @fastify/compress (brotli quality 4), which steps aside when `content-encoding` is already set. A 404, a draft or a per-viewer page is not kept and goes out through @fastify/compress as before.
+
 ## Thundering-herd safety
 
 If three concurrent requests hit a cold key, the producer runs exactly once - the other two await the first's result via an in-flight promise map. This matters for popular pages on cache cold-start: without coalescing, N parallel requests trigger N parallel renders, each writing the same value back to the cache.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "1.8.25",
+  "version": "1.8.27",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/server/routes/api/cache.js

@@ -11,6 +11,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import {fileURLToPath} from 'url';
 import * as cache from '../../services/cache/index.js';
+import {pageMemoStats} from '../../services/content.js';
 import {authenticate, requireAdmin} from '../../middleware/auth.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -37,7 +38,7 @@ async function writeCacheConfig(cfg) {
 export async function cacheRoutes(fastify) {
     const adminOnly = {preHandler: [authenticate, requireAdmin]};
 
-    fastify.get('/cache/status', adminOnly, async () => cache.getStats());
+    fastify.get('/cache/status', adminOnly, async () => ({...cache.getStats(), pageMemo: pageMemoStats()}));
 
     fastify.get('/cache/keys', adminOnly, async () => ({entries: cache.listEntries()}));
 

package/server/routes/docs-public.js

@@ -41,7 +41,7 @@ export async function docsPublicRoutes(fastify) {
             return reply.type('text/html; charset=utf-8').send(await render404(`/domma-docs${docPath ? '/' + docPath : ''}`));
         }
         // private + ETag: the response is role-dependent, so no shared proxy may reuse it.
-        return sendHtml(request, reply, html);
+        return sendHtml(request, reply, html, {cached: true}); // renderDocPage() caches per role
     };
 
     fastify.get('/domma-docs', handle);    // exact - params['*'] === '' (home landing)

package/server/routes/public.js

@@ -18,7 +18,6 @@ import {viewerRoleKey} from '../services/userRoles.js';
 import {hooks} from '../services/hooks.js';
 import {getConfig} from '../config.js';
 import * as cache from '../services/cache/index.js';
-import {createHash} from 'crypto';
 
 /**
  * Derive the absolute origin for the current request.
@@ -40,55 +39,10 @@ export function getBaseUrl(request) {
     return `${request.protocol}://${host}`;
 }
 
-/**
- * Escape user-controlled strings before interpolating into HTML.
- * Prevents reflected XSS in error pages.
- *
- * @param {string} str
- * @returns {string}
- */
-function escapeHtml(str) {
-    return String(str)
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
-
-/*
- * Send an HTML page with headers that make a browser CHECK before reusing it.
- *
- * Public pages went out with no Cache-Control, no ETag and no Last-Modified at
- * all. With nothing to go on a browser applies heuristic caching, so an edited
- * page could keep showing the old content on a normal refresh - the server was
- * serving the new one the whole time. That is indistinguishable from a CMS bug
- * and was reported as one.
- *
- * `no-cache` does not mean "do not store": it means store it, then revalidate
- * before every reuse. Paired with an ETag that makes the common case a 304 with
- * no body rather than a full re-download.
- *
- * `private` because these responses are role-dependent - the response cache
- * keys on role for exactly that reason - and a shared proxy must never hand one
- * visitor a page rendered for another's permissions.
- */
-export function sendHtml(request, reply, html) {
-    const etag = `"${createHash('sha1').update(html).digest('base64')}"`;
-    reply.header('cache-control', 'private, no-cache');
-    reply.header('etag', etag);
-
-    // If-None-Match may carry a list, and a weak validator's W/ prefix.
-    const seen = String(request.headers['if-none-match'] || '')
-        .split(',')
-        .map((t) => t.trim().replace(/^W\//, ''));
-    if (seen.includes(etag)) return reply.code(304).send();
-
-    // Deliberately no reply.code() here: the 404 handlers have already called
-    // reply.status(404), and forcing 200 would turn every not-found into a
-    // soft 404 that search engines index as a real page.
-    return reply.type('text/html; charset=utf-8').send(html);
-}
+// Validators, the 304 and the compressed body kept per encoding live in
+// services/htmlResponse.js; re-exported because docs-public.js imports it from here.
+import {sendHtml} from '../services/htmlResponse.js';
+export {sendHtml};
 
 export async function publicRoutes(fastify) {
     // Admin panel: serve index.html for all /admin/* paths (SPA fallback)
@@ -249,6 +203,7 @@ export async function publicRoutes(fastify) {
         if (isDraft) {
             reply.header('cache-control', 'no-store, private');
             reply.header('x-robots-tag', 'noindex, nofollow');
+            reply.header('x-dm-cache', 'bypass');
             return reply.type('text/html; charset=utf-8').send(await render());
         }
 
@@ -256,6 +211,7 @@ export async function publicRoutes(fastify) {
         // so these pages must render against the expiry ledger on every request.
         if (page.hasExpiry) {
             reply.header('cache-control', 'no-store, private');
+            reply.header('x-dm-cache', 'bypass');
             hooks.emit('content:pageViewed', {urlPath, title: page.title || ''});
             return reply.type('text/html; charset=utf-8').send(await render());
         }
@@ -265,6 +221,7 @@ export async function publicRoutes(fastify) {
         // must not share an entry. Anonymous viewers of such a view get no rows
         // at all (views.js), which is one output, so they still share the cache.
         if (page.perViewer && userObj) {
+            reply.header('x-dm-cache', 'bypass');
             hooks.emit('content:pageViewed', {urlPath, title: page.title || ''});
             return sendHtml(request, reply, await render());
         }
@@ -276,9 +233,14 @@ export async function publicRoutes(fastify) {
         const cacheKey = `page:${urlPath}:m${pageMtime}:role${viewerRoleKey(userObj)}:o${baseUrl}`;
         // The footer's blocks (site.json footer.blocks) are on every page: editing one must reach the cached pages.
         const cacheTags = [`page:${urlPath}`, ...(page.cacheTags || []), 'nav', 'site', ...footerBlockCacheTags(getConfig('site'))];
-        const html = await cache.wrap(cacheKey, render, {tags: cacheTags});
+        // x-dm-cache says which way this response went - hit, miss, off (the
+        // cache is disabled) or bypass (a draft, an expiring or a per-viewer
+        // page, never cached) - so a slow page can be read from the browser.
+        const {value: html, status} = await cache.wrapStatus(cacheKey, render, {tags: cacheTags});
+        reply.header('x-dm-cache', status);
         hooks.emit('content:pageViewed', {urlPath, title: page.title || ''});
-        return sendHtml(request, reply, html);
+        // cached: this HTML is shared, so its compressed body is kept too (htmlResponse.js).
+        return sendHtml(request, reply, html, {cached: true});
     });
 }
 

package/server/services/cache/index.js

@@ -9,6 +9,9 @@ let _lastConfig = null;
 /** @type {Map<string, Promise<*>>} */
 const _inflight = new Map();
 
+/** Called with a reason whenever anything leaves the cache - see onInvalidate(). */
+const _invalidateListeners = new Set();
+
 const _stats = {
     hits: 0,
     misses: 0,
@@ -28,6 +31,7 @@ const _stats = {
  */
 export async function initCache(config = {}) {
     _lastConfig = {...config};
+    _notifyInvalidate('init');
     _stats.initialisedAt = new Date().toISOString();
     if (config.enabled === false) {
         _driver = new NoneDriver();
@@ -72,6 +76,7 @@ export async function setEnabled(enabled) {
     } else {
         _enabled = false;
         _inflight.clear();
+        _notifyInvalidate('disabled');
     }
 }
 
@@ -79,6 +84,28 @@ export function isEnabled() {
     return _enabled;
 }
 
+/**
+ * Hear about every invalidation: a tag flush, a clear, a re-init or the cache
+ * being switched off. Anything that keeps its own derived copy of what the
+ * response cache holds (content.js's parsed-page memo) drops it here, so it
+ * can never be fresher or staler than the cache itself. The listener gets
+ * `(reason, tags)` and its errors are swallowed - an invalidation must never
+ * fail because an onlooker threw.
+ *
+ * @param {(reason: 'tags'|'clear'|'init'|'disabled', tags?: string[]) => void} fn
+ * @returns {() => void} unsubscribe
+ */
+export function onInvalidate(fn) {
+    _invalidateListeners.add(fn);
+    return () => _invalidateListeners.delete(fn);
+}
+
+function _notifyInvalidate(reason, tags) {
+    for (const fn of _invalidateListeners) {
+        try { fn(reason, tags); } catch { /* an onlooker's problem, not the cache's */ }
+    }
+}
+
 export async function get(key) {
     return _driver.get(_vk(key));
 }
@@ -91,13 +118,17 @@ export async function invalidateTags(tags) {
     if (!Array.isArray(tags) || tags.length === 0) return;
     _stats.invalidations++;
     _stats.lastInvalidationAt = new Date().toISOString();
-    return _driver.invalidateTags(tags);
+    const out = await _driver.invalidateTags(tags);
+    _notifyInvalidate('tags', tags);
+    return out;
 }
 
 export async function clear() {
     _inflight.clear();
     _stats.lastClearedAt = new Date().toISOString();
-    return _driver.clear();
+    const out = await _driver.clear();
+    _notifyInvalidate('clear');
+    return out;
 }
 
 /**
@@ -151,19 +182,35 @@ export function getStats() {
  * @param {{ttlSeconds?: number, tags?: string[]}} [opts]
  */
 export async function wrap(key, producer, opts = {}) {
+    return (await wrapStatus(key, producer, opts)).value;
+}
+
+/**
+ * wrap(), and which way it went: `{value, status}` with status `hit`, `miss`
+ * (this call produced it, or waited on the in-flight production) or `off`
+ * (the cache is disabled and the producer simply ran). The public route puts
+ * the status on the response as `x-dm-cache`, so a slow page can be told
+ * apart from a page that is never cached without reading the server's logs.
+ *
+ * @param {string} key
+ * @param {() => Promise<*>} producer
+ * @param {{ttlSeconds?: number, tags?: string[]}} [opts]
+ * @returns {Promise<{value: *, status: 'hit'|'miss'|'off'}>}
+ */
+export async function wrapStatus(key, producer, opts = {}) {
     if (!_enabled) {
         const raw = await producer();
-        return _stripCacheTags(raw);
+        return {value: _stripCacheTags(raw), status: 'off'};
     }
 
     const vkey = _vk(key);
     const hit = await _driver.get(vkey);
     if (hit !== undefined) {
         _stats.hits++;
-        return hit;
+        return {value: hit, status: 'hit'};
     }
 
-    if (_inflight.has(vkey)) return _inflight.get(vkey);
+    if (_inflight.has(vkey)) return {value: await _inflight.get(vkey), status: 'miss'};
 
     _stats.misses++;
     const promise = (async () => {
@@ -183,7 +230,7 @@ export async function wrap(key, producer, opts = {}) {
     })();
 
     _inflight.set(vkey, promise);
-    return promise;
+    return {value: await promise, status: 'miss'};
 }
 
 function _vk(key) {
@@ -207,6 +254,7 @@ function _stripCacheTags(raw) {
 }
 
 export function _resetForTests() {
+    _notifyInvalidate('init');
     _driver = new NoneDriver();
     _enabled = false;
     _lastConfig = null;

package/server/services/content.js

@@ -16,6 +16,63 @@ const CONTENT_DIR = config.content.contentDir;
 const PAGES_DIR = path.join(CONTENT_DIR, 'pages');
 const MEDIA_DIR = config.content.mediaDir;
 
+// ---------------------------------------------------------------------------
+// Parsed-page memo
+// ---------------------------------------------------------------------------
+//
+// Every public request decides whether the viewer may see the page BEFORE the
+// response cache is consulted, and that decision (resolvePublishedPage) reads
+// the page with getPage(), which parses the whole body - shortcodes,
+// collections, sanitising - to learn `hasExpiry`, `perViewer` and the cache
+// tags. So a response-cache "hit" still cost a full anonymous parse, 3-4 ms on
+// an ordinary page and the whole of the per-request CPU; the cache only ever
+// saved the second parse. This memo keeps the anonymous parse (no user, no
+// expiry ledger) per file, keyed on the file's mtime and size, and is emptied
+// whenever ANYTHING leaves the response cache (cache.onInvalidate), so it is
+// exactly as fresh as the cache: an edit changes the mtime, a collection or
+// block save flushes both. It is on only while the response cache is on - in
+// development every read parses, as before - and a short TTL bounds anything
+// the hooks do not know about. Entries are cloned in and out, so a caller
+// that edits the object it was handed edits its own copy.
+const PAGE_MEMO_MAX = 500;
+const PAGE_MEMO_TTL_MS = 5 * 60 * 1000;
+/** @type {Map<string, {mtimeMs: number, size: number, at: number, page: object}>} */
+const _pageMemo = new Map();
+const _pageMemoStats = {hits: 0, misses: 0};
+cache.onInvalidate(() => _pageMemo.clear());
+
+/** For the cache status route and tests: how the memo is doing. */
+export function pageMemoStats() {
+    return {size: _pageMemo.size, max: PAGE_MEMO_MAX, hits: _pageMemoStats.hits, misses: _pageMemoStats.misses};
+}
+
+export function _resetPageMemoForTests() {
+    _pageMemo.clear();
+    _pageMemoStats.hits = 0;
+    _pageMemoStats.misses = 0;
+}
+
+async function readPageMemo(filePath) {
+    const st = await fs.stat(filePath);
+    const now = Date.now();
+    const kept = _pageMemo.get(filePath);
+    if (kept && kept.mtimeMs === st.mtimeMs && kept.size === st.size && now - kept.at < PAGE_MEMO_TTL_MS) {
+        _pageMemo.delete(filePath);
+        _pageMemo.set(filePath, kept); // most recently used last
+        _pageMemoStats.hits++;
+        return structuredClone(kept.page);
+    }
+    _pageMemoStats.misses++;
+    const page = await readPageFile(filePath);
+    try {
+        _pageMemo.set(filePath, {mtimeMs: st.mtimeMs, size: st.size, at: now, page: structuredClone(page)});
+    } catch {
+        return page; // something in it cannot be cloned: hand it over unmemoised
+    }
+    while (_pageMemo.size > PAGE_MEMO_MAX) _pageMemo.delete(_pageMemo.keys().next().value);
+    return page;
+}
+
 // ---------------------------------------------------------------------------
 // Pages
 // ---------------------------------------------------------------------------
@@ -71,6 +128,10 @@ export async function getPageMtime(urlPath) {
 export async function getPage(urlPath, opts = {}) {
     const filePath = await resolveExistingFilePath(urlPath);
     try {
+        // Only the anonymous, ledger-free read is memoised: a viewer's read
+        // differs per role ([menu], row-scoped [view]) and an expiry read
+        // writes to the ledger.
+        if (!opts.user && !opts.expiry && cache.isEnabled()) return await readPageMemo(filePath);
         return await readPageFile(filePath, {user: opts.user || null, expiry:opts.expiry});
     } catch {
         return null;

package/server/services/htmlResponse.js

@@ -0,0 +1,138 @@
+/**
+ * Sending a rendered page: validators, and the compressed body kept per
+ * encoding.
+ *
+ * @fastify/compress compresses every response as it leaves, so a page that
+ * came out of the response cache was still brotli'd on every request - after
+ * the parsed-page memo that was most of what a cache hit cost (a 40 KB page
+ * is ~2 ms of brotli at quality 4, in the thread pool but paid for all the
+ * same). Here the compressed body is cached too, addressed by the content:
+ * the key is the encoding plus the sha1 of the HTML, the same hash the ETag
+ * is made from. Content-addressed means it can never be stale - a different
+ * page is a different hash - so it needs no tags and no invalidation, and two
+ * cache keys that render the same HTML (two base URLs, say) share one body.
+ * Its memory is bounded by the cache's own LRU and TTL.
+ *
+ * Only a response that came from the response cache asks for it (`cached`):
+ * a 404 carries the requested path, a per-viewer page is one visitor's, and
+ * caching those would fill the cache with bodies nobody asks for twice.
+ * Everything else goes out as HTML and @fastify/compress does what it did.
+ *
+ * The negotiation and the parameters match @fastify/compress (br before
+ * gzip, brotli quality 4, zlib's default gzip level, the 1 KB threshold), so
+ * a visitor gets the same bytes either way; compress sees `content-encoding`
+ * already set and steps aside.
+ */
+import {createHash} from 'node:crypto';
+import zlib from 'node:zlib';
+import {promisify} from 'node:util';
+import * as cache from './cache/index.js';
+
+const brotli = promisify(zlib.brotliCompress);
+const gzip = promisify(zlib.gzip);
+
+/** Responses under this many bytes are not worth compressing - @fastify/compress's threshold. */
+export const COMPRESS_THRESHOLD = 1024;
+/** Offered in order of preference: the tie-break when the client rates them equally. */
+export const ENCODINGS = ['br', 'gzip'];
+
+/**
+ * Which of our encodings the client prefers, or null for none (no header, or
+ * nothing acceptable). `*` and `x-gzip` count as gzip, as @fastify/compress
+ * reads them; a `q=0` rules an encoding out.
+ *
+ * @param {string|undefined} header - the Accept-Encoding value
+ * @param {string[]} [offered]
+ * @returns {string|null}
+ */
+export function pickEncoding(header, offered = ENCODINGS) {
+    if (!header) return null;
+    const q = new Map();
+    for (const part of String(header).toLowerCase().split(',')) {
+        const [rawName, ...params] = part.trim().split(';');
+        let name = rawName.trim();
+        if (!name) continue;
+        if (name === '*' || name === 'x-gzip') name = 'gzip';
+        let weight = 1;
+        for (const p of params) {
+            const m = p.trim().match(/^q=([0-9.]+)$/);
+            if (m) weight = Number(m[1]);
+        }
+        if (!q.has(name) || q.get(name) < weight) q.set(name, weight);
+    }
+    let best = null;
+    let bestQ = 0;
+    for (const enc of offered) {
+        const weight = q.get(enc) ?? 0;
+        if (weight > bestQ) { best = enc; bestQ = weight; }
+    }
+    return best;
+}
+
+/**
+ * The compressed body, the way @fastify/compress would have made it.
+ *
+ * @param {string} html
+ * @param {string} encoding - 'br' | 'gzip'
+ * @returns {Promise<Buffer>}
+ */
+export function encodeHtml(html, encoding) {
+    const input = Buffer.from(html, 'utf8');
+    if (encoding === 'br') {
+        return brotli(input, {params: {
+            [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
+            [zlib.constants.BROTLI_PARAM_SIZE_HINT]: input.length,
+        }});
+    }
+    if (encoding === 'gzip') return gzip(input);
+    throw new Error(`Unknown encoding: ${encoding}`);
+}
+
+/** The validator's content part: the same hash whatever the encoding. */
+export function htmlHash(html) {
+    return createHash('sha1').update(html).digest('base64');
+}
+
+/**
+ * Send a rendered page: cache-control, an ETag, a 304 when the browser
+ * already has it, and - for a response that came from the response cache -
+ * the compressed body from the cache, made once.
+ *
+ * The ETag is the content hash, suffixed with the encoding when the body is
+ * compressed (`"<hash>-br"`): a strong validator names a representation, and
+ * the bytes differ per encoding. A browser's If-None-Match is matched on the
+ * hash whatever suffix it carries, so a visitor who first got gzip and now
+ * accepts brotli still gets their 304.
+ *
+ * Deliberately no reply.code() on the success path: the 404 handlers call
+ * reply.status(404) before sending, and forcing 200 would turn every
+ * not-found into a soft 404 that search engines index as a real page.
+ *
+ * @param {import('fastify').FastifyRequest} request
+ * @param {import('fastify').FastifyReply} reply
+ * @param {string} html
+ * @param {{cached?: boolean}} [opts] - cached: the HTML came from the response cache, so its
+ *   compressed form may be kept too
+ */
+export async function sendHtml(request, reply, html, {cached = false} = {}) {
+    const hash = htmlHash(html);
+    const encoding = cached && Buffer.byteLength(html) >= COMPRESS_THRESHOLD
+        ? pickEncoding(request.headers['accept-encoding'])
+        : null;
+    const etag = `"${hash}${encoding ? `-${encoding}` : ''}"`;
+    reply.header('cache-control', 'private, no-cache');
+    reply.header('etag', etag);
+    reply.header('vary', 'accept-encoding');
+
+    // If-None-Match may carry a list, and a weak validator's W/ prefix.
+    const seen = String(request.headers['if-none-match'] || '')
+        .split(',')
+        .map((t) => t.trim().replace(/^W\//, ''));
+    if (seen.some((t) => t === `"${hash}"` || t.startsWith(`"${hash}-`))) return reply.code(304).send();
+
+    if (!encoding) return reply.type('text/html; charset=utf-8').send(html);
+
+    const body = await cache.wrap(`enc:${encoding}:${hash}`, () => encodeHtml(html, encoding), {tags: ['encoded']});
+    reply.header('content-encoding', encoding);
+    return reply.type('text/html; charset=utf-8').send(body);
+}