@heroiclands/package-build 25.5.3 → 25.5.5

package/engine/site-serve.mjs

@@ -25,21 +25,20 @@
  *
  * A page that changes because another note changed — a table that lists the
  * note, a link that carries its name — is written again by the next whole
- * build. A note in error is written as its page shows it, and the error is
- * reported; a build whose gates fire writes nothing and leaves the last good
- * site in place.
+ * build. A failed build is reported and leaves the last successful site in
+ * place, including its search index.
  *
  * The site is served from the deployed root, so a page is at the address it is
  * deployed at, its base path included. Every HTML page is sent with a script
  * that listens on {@link RELOAD_PATH} for the server's `reload` event; the
  * script is added as the page is sent and is never written to the site. The
- * search index is built once, after the first build.
+ * search index is built with each whole build before it replaces the last site.
  *
  * @module
  */
 
 import fs from "node:fs";
-import http from "node:http";
+import { Worker } from "node:worker_threads";
 import path from "node:path";
 
 import { siteBuildFailed } from "./site-build.mjs";
@@ -47,6 +46,7 @@ import { SITE_THEME_DIR } from "./site-theme.mjs";
 import { SITE_STATIC_DIR, buildPackageSite, writeSite, writeThemeFiles } from "./site-render.mjs";
 import { siteBase } from "../content-config.mjs";
 import { SEARCH_DIR, indexSite } from "./site-root.mjs";
+import { readCachedNavigation, siteSettings } from "./site-config.mjs";
 
 /** The address a served page listens on for the server's reloads. */
 export const RELOAD_PATH = "/__package-build/reload";
@@ -54,29 +54,6 @@ export const RELOAD_PATH = "/__package-build/reload";
 /** How long a burst of changes is gathered before it is written, in milliseconds. */
 const SETTLE_MS = 120;
 
-/** What a file is sent as, by its extension. */
-const CONTENT_TYPES = Object.freeze({
-    ".html": "text/html; charset=utf-8",
-    ".css": "text/css; charset=utf-8",
-    ".js": "text/javascript; charset=utf-8",
-    ".mjs": "text/javascript; charset=utf-8",
-    ".json": "application/json",
-    ".xml": "application/xml",
-    ".txt": "text/plain; charset=utf-8",
-    ".svg": "image/svg+xml",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".webp": "image/webp",
-    ".gif": "image/gif",
-    ".woff2": "font/woff2",
-    ".woff": "font/woff",
-    ".wasm": "application/wasm",
-});
-
-/** The script a served page is sent with. */
-const RELOAD_SCRIPT = `<script>new EventSource(${JSON.stringify(RELOAD_PATH)}).addEventListener("reload", () => location.reload());</script>`;
-
 /** Whether a note's text holds a query its build prepares ahead of the render. */
 const holdsQuery = (text) => /```\s*sql\b|\{\{[^}]*\bsql\b/.test(text);
 
@@ -91,16 +68,19 @@ const holdsQuery = (text) => /```\s*sql\b|\{\{[^}]*\bsql\b/.test(text);
  *   directory above `out` by default; `out` itself for a site served at `/`.
  * @param {string} [options.host] - The address to listen on.
  * @param {number} [options.port] - The port; `0` takes any free one.
- * @param {boolean} [options.search] - Build the search index after the first
+ * @param {boolean} [options.search] - Build the search index with each whole
  *   build, where the site has one.
  * @param {number} [options.year] - The year the footer states.
- * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown}) => void} [options.report] -
- *   Told of each build: `built` for a whole build, `page` for one note's page,
+ * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown, message?: string, fatal?: boolean}) => void} [options.report] -
+ *   Told of progress (`message`) and each build: `built` for a whole build, `page` for one note's page,
  *   `theme` for the theme, `failed` with what the build found, `error` with
  *   what it threw.
- * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>}>}
- *   The address of the site's home page, how to stop serving, and a promise
- *   for the moment every change seen so far has been written.
+ * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>, done: Promise<void>}>}
+ *   Resolves as soon as HTTP listens, before the first build. The address of
+ *   the site's home page, how to stop serving, and a promise for the initial
+ *   build and every change seen so far to finish. Failed builds are reported
+ *   through `report` and leave the last successful site in service. `done`
+ *   resolves on close and rejects if HTTP stops unexpectedly.
  */
 export async function serveSite({
     config,
@@ -112,27 +92,147 @@ export async function serveSite({
     year,
     report = () => {},
 }) {
-    /** @type {Set<http.ServerResponse>} */
-    const listeners = new Set();
+    // Refuse a site that cannot be described before starting its server.
+    siteSettings({ config });
+    readCachedNavigation(config);
+    root = path.resolve(root);
+    out = path.resolve(out);
+    let timer = null;
+    const watchers = [];
+    let closing = false;
+    let complete;
+    let abort;
+    const done = new Promise((resolve, reject) => {
+        complete = resolve;
+        abort = reject;
+    });
+    // The caller may attach its lifecycle handler after awaiting startup.
+    done.catch(() => {});
+    const stopWatching = () => {
+        if (timer) clearTimeout(timer);
+        timer = null;
+        for (const watcher of watchers) watcher.close();
+    };
+    const worker = new Worker(new URL("./site-serve-http.mjs", import.meta.url), {
+        workerData: { root, out, host, port, reloadPath: RELOAD_PATH },
+        // The HTTP helper uses only Node builtins. A caller's --input-type
+        // or loader flags describe its own entry point, not this file.
+        execArgv: [],
+    });
+    let workerFailure;
+    let started = false;
+    const requests = new Map();
+    worker.on("message", (event) => {
+        const waiting = requests.get(event.kind);
+        if (!waiting) return;
+        requests.delete(event.kind);
+        if (event.error) waiting.reject(event.error);
+        else waiting.resolve(event);
+    });
+    const failed = (error) => {
+        if (workerFailure) return;
+        workerFailure = error;
+        stopWatching();
+        abort(error);
+        for (const waiting of requests.values()) waiting.reject(error);
+        requests.clear();
+        if (started) report({ kind: "error", error, fatal: true });
+    };
+    worker.on("error", failed);
+    const exited = new Promise((resolve) => {
+        worker.once("exit", (code) => {
+            if ((started || requests.size) && !workerFailure)
+                failed(new Error(`the preview HTTP server stopped (exit ${code})`));
+            resolve();
+        });
+    });
+    const receive = (kind) =>
+        new Promise((resolve, reject) => {
+            if (workerFailure) reject(workerFailure);
+            else requests.set(kind, { resolve, reject });
+        });
+    const listening = await receive("listening");
+    started = true;
     let state = null;
+    const progress = (message) => report({ kind: "progress", message });
+    const reload = () => worker.postMessage({ kind: "reload" });
 
-    const reload = () => {
-        for (const res of listeners) res.write("event: reload\ndata: {}\n\n");
+    // Whole builds and incremental updates publish through the same boundary.
+    // HTTP owns the renames, between requests; writers only touch private trees.
+    const publish = async (write) => {
+        if (workerFailure || closing) return null;
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        const staging = fs.mkdtempSync(path.join(path.dirname(out), ".site-preview-"));
+        const staged = path.join(staging, "site");
+        const previous = path.join(staging, "previous");
+        let installed = false;
+        try {
+            const result = await write(staged);
+            if (!result || closing) return null;
+            if (workerFailure) throw workerFailure;
+            const ready = receive("installed");
+            worker.postMessage({ kind: "install", staged, previous });
+            await ready;
+            installed = true;
+            return result;
+        } finally {
+            // A failed rollback must retain the only remaining previous tree.
+            if (installed || !fs.existsSync(previous))
+                fs.rmSync(staging, { recursive: true, force: true });
+        }
     };
 
     const buildAll = async () => {
-        const result = await buildPackageSite({ config, out, year });
-        if (!result.written || siteBuildFailed(result.built))
-            report({ kind: "failed", built: result.built });
-        if (!result.written) return false;
+        const result = await publish(async (staged) => {
+            const built = await buildPackageSite({ config, out: staged, year, progress });
+            const findings = [...(built.written?.findings ?? []), ...(built.fonts?.findings ?? [])];
+            if (
+                !built.written ||
+                siteBuildFailed(built.built) ||
+                built.fonts?.findings.length ||
+                findings.some((finding) => finding.severity === "error")
+            ) {
+                report({ kind: "failed", built: built.built, findings });
+                return null;
+            }
+            if (search && config.site.search !== false) {
+                progress("building the search index");
+                const indexed = await indexSite({
+                    site: staged,
+                    output: path.join(staged, SEARCH_DIR),
+                    base: siteBase(config),
+                });
+                progress(`indexed ${indexed.pages} page(s) for search`);
+            }
+            return { ...built, findings };
+        });
+        if (!result) return false;
         state = result;
-        report({ kind: "built", built: result.built, findings: result.written.findings });
+        report({ kind: "built", built: result.built, findings: result.findings });
         return true;
     };
 
-    const redrawNotes = (files) => {
+    const redraw = async ({ pages, only, theme = false }) => {
+        return publish((staged) => {
+            // Keep unchanged pages, static files and the current search index.
+            fs.cpSync(out, staged, { recursive: true, mode: fs.constants.COPYFILE_FICLONE });
+            if (theme) writeThemeFiles(staged);
+            const written = writeSite({ site: state.site, pages, out: staged, only });
+            if (written.findings.some((finding) => finding.severity === "error")) {
+                report({ kind: "failed", findings: written.findings });
+                return null;
+            }
+            return {
+                ...written,
+                files: written.files.map((file) => path.join(out, path.relative(staged, file))),
+            };
+        });
+    };
+
+    const redrawNotes = async (files) => {
         if (!state) return false;
         const changed = new Set();
+        let pages = state.pages;
         for (const file of files) {
             const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
             if (!file.endsWith(".md") || !text || holdsQuery(text)) return false;
@@ -140,41 +240,33 @@ export async function serveSite({
             if (!entry) return false;
             if (entry.findings.length) {
                 report({ kind: "failed", findings: entry.findings });
-                return true;
+                return null;
             }
             const page = state.pageOf(entry);
-            state.pages = state.pages.map((old) => (old.url === page.url ? page : old));
+            pages = pages.map((old) => (old.url === page.url ? page : old));
             changed.add(page.url);
         }
-        const written = writeSite({ site: state.site, pages: state.pages, out, only: changed });
+        const written = await redraw({ pages, only: changed });
+        if (!written) return null;
+        state.pages = pages;
         report({ kind: "page", files: written.files, findings: written.findings });
         return true;
     };
 
-    const redrawTheme = () => {
+    const redrawTheme = async () => {
         if (!state) return false;
-        writeThemeFiles(out);
-        const written = writeSite({
-            site: state.site,
+        const written = await redraw({
             pages: state.pages,
-            out,
             only: new Set(state.pages.map((page) => page.url)),
+            theme: true,
         });
+        if (!written) return false;
         report({ kind: "theme", files: written.files, findings: written.findings });
         return true;
     };
 
-    const indexForSearch = async () => {
-        if (!search || config.site.search === false || !state) return;
-        await indexSite({ site: out, output: path.join(out, SEARCH_DIR), base: siteBase(config) });
-    };
-
-    await buildAll();
-    await indexForSearch();
-
     /** @type {{content: Set<string>, theme: boolean}} */
     let pending = { content: new Set(), theme: false };
-    let timer = null;
     let work = Promise.resolve();
     const flush = () => {
         timer = null;
@@ -182,93 +274,71 @@ export async function serveSite({
         pending = { content: new Set(), theme: false };
         work = work.then(async () => {
             try {
-                let done = true;
-                if (batch.content.size && !redrawNotes([...batch.content])) {
-                    done = await buildAll();
-                    if (done) await indexForSearch();
-                } else if (batch.theme) done = redrawTheme();
-                if (done) reload();
+                if (workerFailure || closing) return;
+                let changed = batch.content.size ? await redrawNotes([...batch.content]) : true;
+                if (changed === false) changed = await buildAll();
+                else if (changed && batch.theme) changed = await redrawTheme();
+                if (changed) reload();
             } catch (error) {
-                report({ kind: "error", error });
+                if (error !== workerFailure) report({ kind: "error", error });
             }
         });
     };
     const queue = (kind, file) => {
+        if (workerFailure || closing) return;
         if (kind === "theme") pending.theme = true;
         else pending.content.add(file);
         if (!timer) timer = setTimeout(flush, SETTLE_MS);
     };
 
-    const watchers = [
-        fs.watch(config.paths.content, { recursive: true }, (_event, name) => {
-            if (name) queue("content", path.join(config.paths.content, String(name)));
-        }),
-        ...[SITE_THEME_DIR, SITE_STATIC_DIR]
-            .filter((dir) => fs.existsSync(dir))
-            .map((dir) => fs.watch(dir, { recursive: true }, () => queue("theme"))),
-    ];
-
-    const server = http.createServer((req, res) => {
-        const address = decodeURIComponent(
-            new URL(req.url ?? "/", "http://serve.invalid").pathname,
+    try {
+        watchers.push(
+            fs.watch(config.paths.content, { recursive: true }, (_event, name) => {
+                if (name) queue("content", path.join(config.paths.content, String(name)));
+            }),
         );
-        if (address === RELOAD_PATH) {
-            res.writeHead(200, {
-                "content-type": "text/event-stream",
-                "cache-control": "no-cache",
-                connection: "keep-alive",
-            });
-            res.write(": connected\n\n");
-            listeners.add(res);
-            req.on("close", () => listeners.delete(res));
-            return;
+        for (const dir of [SITE_THEME_DIR, SITE_STATIC_DIR]) {
+            if (fs.existsSync(dir))
+                watchers.push(fs.watch(dir, { recursive: true }, () => queue("theme")));
         }
-        let file = path.join(root, address);
-        if (!file.startsWith(root)) {
-            res.writeHead(403).end();
-            return;
-        }
-        if (fs.statSync(file, { throwIfNoEntry: false })?.isDirectory())
-            file = path.join(file, "index.html");
-        let status = 200;
-        if (!fs.existsSync(file)) {
-            status = 404;
-            file = path.join(out, "404.html");
-            if (!fs.existsSync(file)) {
-                res.writeHead(404).end();
-                return;
-            }
-        }
-        const type = CONTENT_TYPES[path.extname(file).toLowerCase()] ?? "application/octet-stream";
-        let body = fs.readFileSync(file);
-        if (type.startsWith("text/html")) {
-            const html = body.toString("utf8");
-            const at = html.lastIndexOf("</body>");
-            body = Buffer.from(
-                at < 0 ? html + RELOAD_SCRIPT : html.slice(0, at) + RELOAD_SCRIPT + html.slice(at),
-            );
+    } catch (error) {
+        stopWatching();
+        started = false;
+        worker.postMessage({ kind: "close" });
+        await exited;
+        abort(error);
+        throw error;
+    }
+
+    // Return the listening address before beginning the first long build.
+    work = new Promise((resolve) => setImmediate(resolve)).then(async () => {
+        try {
+            if (await buildAll()) reload();
+        } catch (error) {
+            if (error !== workerFailure) report({ kind: "error", error });
         }
-        res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
-        res.end(body);
     });
-    await new Promise((resolve) => server.listen(port, host, resolve));
-    const listening = /** @type {import("node:net").AddressInfo} */ (server.address());
-    const base = new URL(config.homepage).pathname;
 
     return {
-        url: `http://${host}:${listening.port}${base}`,
+        url: `http://${host}:${listening.port}${new URL(config.homepage).pathname}`,
+        done,
         settled: async () => {
-            while (timer || pending.content.size || pending.theme) {
+            for (;;) {
+                const current = work;
+                await current;
+                if (workerFailure) throw workerFailure;
+                if (!timer && !pending.content.size && !pending.theme && current === work) return;
                 await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
             }
-            await work;
         },
         close: async () => {
-            if (timer) clearTimeout(timer);
-            for (const watcher of watchers) watcher.close();
-            for (const res of listeners) res.end();
+            closing = true;
+            stopWatching();
             await work;
-            await new Promise((resolve) => server.close(() => resolve()));
+            started = false;
+            worker.postMessage({ kind: "close" });
+            await exited;
+            complete();
         },
     };
 }