domma-cms 1.8.26 → 1.8.28

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/server.js

@@ -14,6 +14,7 @@ import multipart from '@fastify/multipart';
 import rateLimit from '@fastify/rate-limit';
 import helmet from '@fastify/helmet';
 import compress from '@fastify/compress';
+import {registerAssetCache} from './services/assetCache.js';
 import path from 'path';
 import fs from 'fs/promises';
 import {fileURLToPath} from 'url';
@@ -159,6 +160,12 @@ if (publicCorsPrefixes.length) {
 await app.register(multipart, { limits: { fileSize: serverConfig.uploads.maxFileSize } });
 await app.register(rateLimit, rateLimitOptions());
 
+// Text assets (scripts, stylesheets, SVG, JSON) from memory, compressed once
+// per encoding - services/assetCache.js. Its onSend hook must be added BEFORE
+// compress registers its own, so compress finds content-encoding set and
+// steps aside.
+registerAssetCache(app);
+
 // Negotiates brotli/gzip/deflate per Accept-Encoding. Skips already-compressed
 // content types (images, fonts, video) and responses under threshold.
 await app.register(compress, {

package/server/services/assetCache.js

@@ -0,0 +1,141 @@
+/**
+ * Static assets from memory, compressed once.
+ *
+ * @fastify/static streams every stylesheet and script from disk on every
+ * request - stat, open, read, close - and @fastify/compress then brotli's the
+ * stream for every visitor. On a busy site that was a whole core for about a
+ * thousand assets a second, all of it repeated work: the files do not change
+ * between requests. This hook, placed BEFORE @fastify/compress's, keeps the
+ * served form of a text asset in memory - the bytes as sent, per encoding
+ * (br, gzip, or identity for a client that accepts none) - and answers the
+ * next request with the buffer. The file is still stat'ed each time, so an
+ * edit (a new mtime or size) is seen at once, and @fastify/static still does
+ * everything else: it resolved the path, set the type, the cache-control the
+ * mount asked for, the ETag and Last-Modified, and answered the 304s, the
+ * HEADs and the 404s before this runs. The hook only swaps the stream for a
+ * buffer, so a file @fastify/static would not have served is never served
+ * here either.
+ *
+ * Only what is worth it: GET, a 200, a compressible type (the same rule
+ * @fastify/compress uses), no Range, a file between 1 KB and `maxFileBytes`.
+ * Images, fonts and media stream as before. On while the response cache is
+ * on, like the page memo - the admin's cache switch means all of it - and
+ * emptied when the cache is cleared or re-initialised. Bounded by bytes, not
+ * entries, with the least recently served evicted first.
+ */
+import fs from 'node:fs/promises';
+import * as cache from './cache/index.js';
+import {encode, pickEncoding} from './htmlResponse.js';
+
+/** @fastify/compress's own rule for what is text enough to compress. */
+const COMPRESSIBLE = /^text\/(?!event-stream)|(?:\+|\/)json(?:;|$)|(?:\+|\/)text(?:;|$)|(?:\+|\/)xml(?:;|$)|javascript(?:;|$)/u;
+
+const DEFAULTS = {maxBytes: 64 * 1024 * 1024, maxFileBytes: 2 * 1024 * 1024, minBytes: 1024};
+
+/** @type {Map<string, {mtimeMs: number, size: number, body: Buffer}>} key = encoding + NUL + path */
+const _entries = new Map();
+/** @type {Map<string, Promise<Buffer>>} */
+const _inflight = new Map();
+let _bytes = 0;
+let _limits = {...DEFAULTS};
+const _stats = {hits: 0, misses: 0, evictions: 0};
+
+cache.onInvalidate((reason) => {
+    // Tags name pages, collections and blocks, never files; a file's own
+    // change is seen through its mtime. A clear, a re-init or the cache going
+    // off empties this too.
+    if (reason !== 'tags') clearAssetCache();
+});
+
+export function clearAssetCache() {
+    _entries.clear();
+    _inflight.clear();
+    _bytes = 0;
+}
+
+export function assetCacheStats() {
+    return {entries: _entries.size, bytes: _bytes, maxBytes: _limits.maxBytes, hits: _stats.hits, misses: _stats.misses, evictions: _stats.evictions};
+}
+
+export function _resetAssetCacheForTests() {
+    clearAssetCache();
+    _stats.hits = 0;
+    _stats.misses = 0;
+    _stats.evictions = 0;
+}
+
+/**
+ * Is this a stream @fastify/static made for a file? @fastify/send opens the
+ * file with fs.createReadStream, which carries the path it opened.
+ */
+function fileOf(payload) {
+    return payload && typeof payload.pipe === 'function' && typeof payload.path === 'string' ? payload.path : null;
+}
+
+async function bodyFor(file, st, encoding) {
+    const key = `${encoding}\0${file}`;
+    const kept = _entries.get(key);
+    if (kept && kept.mtimeMs === st.mtimeMs && kept.size === st.size) {
+        _entries.delete(key);
+        _entries.set(key, kept); // most recently served last
+        _stats.hits++;
+        return kept.body;
+    }
+    if (_inflight.has(key)) return _inflight.get(key);
+    _stats.misses++;
+    const making = (async () => {
+        try {
+            const raw = await fs.readFile(file);
+            const body = encoding === 'identity' ? raw : await encode(raw, encoding);
+            if (kept) { _bytes -= kept.body.length; _entries.delete(key); }
+            _entries.set(key, {mtimeMs: st.mtimeMs, size: st.size, body});
+            _bytes += body.length;
+            while (_bytes > _limits.maxBytes && _entries.size > 1) {
+                const [oldestKey, oldest] = _entries.entries().next().value;
+                _entries.delete(oldestKey);
+                _bytes -= oldest.body.length;
+                _stats.evictions++;
+            }
+            return body;
+        } finally {
+            _inflight.delete(key);
+        }
+    })();
+    _inflight.set(key, making);
+    return making;
+}
+
+/**
+ * Add the onSend hook. Call BEFORE registering @fastify/compress, so this
+ * runs first and compress sees `content-encoding` already set and steps aside.
+ *
+ * @param {import('fastify').FastifyInstance} app
+ * @param {{maxBytes?: number, maxFileBytes?: number, minBytes?: number}} [limits]
+ */
+export function registerAssetCache(app, limits = {}) {
+    _limits = {...DEFAULTS, ...limits};
+    app.addHook('onSend', async (request, reply, payload) => {
+        if (request.method !== 'GET' || reply.statusCode !== 200 || !cache.isEnabled()) return payload;
+        const file = fileOf(payload);
+        if (!file || request.headers.range) return payload;
+        if (!COMPRESSIBLE.test(String(reply.getHeader('content-type') || ''))) return payload;
+        if (reply.getHeader('content-encoding')) return payload; // a precompressed file @fastify/static served itself
+
+        let st;
+        try { st = await fs.stat(file); } catch { return payload; }
+        if (!st.isFile() || st.size < _limits.minBytes || st.size > _limits.maxFileBytes) return payload;
+
+        const encoding = pickEncoding(request.headers['accept-encoding']) || 'identity';
+        let body;
+        try { body = await bodyFor(file, st, encoding); } catch { return payload; }
+
+        payload.destroy(); // the stream @fastify/static opened: release its file descriptor
+        reply.removeHeader('accept-ranges');
+        reply.header('content-length', body.length);
+        if (encoding !== 'identity') {
+            reply.header('content-encoding', encoding);
+            reply.header('vary', 'accept-encoding');
+        }
+        return body;
+    });
+}

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,141 @@
+/**
+ * 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|Buffer} input
+ * @param {string} encoding - 'br' | 'gzip'
+ * @returns {Promise<Buffer>}
+ */
+export function encode(input, encoding) {
+    if (!Buffer.isBuffer(input)) input = Buffer.from(String(input), '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}`);
+}
+
+/** encode() for a page's HTML. */
+export const encodeHtml = encode;
+
+/** 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);
+}

package/server/services/renderer.js

@@ -687,6 +687,10 @@ function buildSeoMeta({page, site, baseUrl, title, description, image}) {
         });
     }
 
+    // The page's own structured data (frontmatter `seo.schema` - the editor's
+    // SEO tab): one object or a list, each emitted as its own block.
+    jsonLd.push(...schemaBlocks(page.seo?.schema));
+
     return {
         title,
         description,
@@ -703,6 +707,32 @@ function buildSeoMeta({page, site, baseUrl, title, description, image}) {
     };
 }
 
+/**
+ * The JSON-LD blocks a page declares in `seo.schema`: an object, a list of
+ * them, or a JSON string of either (a hand-written frontmatter may hold it as
+ * text). Anything that is not a plain object with a string `@type` is dropped
+ * rather than emitted broken, and `@context` defaults to schema.org, which is
+ * what every example and validator expects. Pure.
+ *
+ * @param {unknown} value
+ * @returns {object[]}
+ */
+export function schemaBlocks(value) {
+    let v = value;
+    if (typeof v === 'string') {
+        if (!v.trim()) return [];
+        try { v = JSON.parse(v); } catch { return []; }
+    }
+    const list = Array.isArray(v) ? v : [v];
+    const out = [];
+    for (const item of list) {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+        if (typeof item['@type'] !== 'string' || !item['@type'].trim()) continue;
+        out.push(item['@context'] ? item : {'@context': 'https://schema.org', ...item});
+    }
+    return out;
+}
+
 /** An absolute URL for og:image and JSON-LD: crawlers ignore relative ones. */
 function absoluteUrl(url, origin) {
     const u = String(url || '').trim();