@beltype/cli 0.1.7 → 0.1.8

package/dist/src/print.js

@@ -14,8 +14,8 @@ import { fileURLToPath } from 'node:url';
 import { chromium } from 'playwright-core';
 import { ciceroFlags } from '@beltype/cicero/flags';
 import { cliFlags, tableOf } from './flags.js';
-import { checkPages } from './check.js';
-import { ARGS, VIEWPORT, documentAssets, servedHtml, routeCompanions, routeDocument, printOnPage, refusal } from './run.js';
+import { checkPages, requireMupdf } from './check.js';
+import { ARGS, VIEWPORT, documentAssets, servedHtml, routeCompanions, routeDocument, printOnPage, refusal, deferralLine } from './run.js';
 export { spliceHead } from './run.js';
 const round = (ms) => Math.round(ms * 10) / 10;
 /**
@@ -41,13 +41,15 @@ export async function print(input, output, options = {}) {
     let step = 'launch';
     let chromiumVersion = 'unknown';
     try {
+        if (flags.beltype.check)
+            await requireMupdf();
         const html = fs.readFileSync(input, 'utf8');
         const root = path.dirname(path.resolve(input));
         const docPath = `/${encodeURIComponent(path.basename(input))}`;
         const assets = documentAssets();
         const served = servedHtml(html);
         const missing = new Set();
-        const browser = await chromium.launch({ headless: true, args: ARGS });
+        const browser = await chromium.launch({ headless: true, args: ARGS, chromiumSandbox: options.sandbox ?? true });
         chromiumVersion = browser.version();
         lap('launch');
         try {
@@ -70,10 +72,12 @@ export async function print(input, output, options = {}) {
                 trace.caster = printed.caster;
                 for (const warning of printed.warnings)
                     console.warn(typeof warning === 'string' ? warning : JSON.stringify(warning));
+                for (const deferral of printed.deferred)
+                    console.warn(deferralLine(deferral));
             }
             else
                 lap('print');
-            const { bytes, pages, words, screens } = printed;
+            const { bytes, pages, words, screens, confessions } = printed;
             step = 'close';
             await browser.close();
             lap('close');
@@ -86,10 +90,10 @@ export async function print(input, output, options = {}) {
             let check;
             if (flags.beltype.check) {
                 step = 'check';
-                check = await checkPages(screens, bytes, path.resolve(output).replace(/\.pdf$/i, '') + '.check', flags.beltype.printer);
+                check = await checkPages(screens, bytes, path.resolve(output).replace(/\.pdf$/i, '') + '.check', flags.beltype.printer, confessions);
                 lap('check');
             }
-            return { output, pages, words, ms: performance.now() - started, ...(check ? { check } : {}) };
+            return { output, pages, words, deferred: printed.deferred.length, ms: performance.now() - started, ...(check ? { check } : {}) };
         }
         finally {
             await browser.close();

package/dist/src/run.js

@@ -24,7 +24,9 @@ export const ARGS = ['--font-render-hinting=none', '--force-device-scale-factor=
 export function documentAssets() {
     const distOf = (specifier, up) => path.resolve(path.dirname(fileURLToPath(import.meta.resolve(specifier))), ...Array(up).fill('..'));
     const cicero = ciceroEngine.vendorAssets();
-    return { files: cicero.files, dirs: { ...cicero.dirs, caster: distOf('@beltype/caster', 1), common: distOf('@beltype/common/errors', 0) } };
+    // Run from src/ or from dist/src/: the package root is the first folder up that holds `assets`.
+    const merge = [1, 2].map((up) => fileURLToPath(new URL(`${'../'.repeat(up)}assets/merge`, import.meta.url))).find((dir) => fs.existsSync(dir));
+    return { files: cicero.files, dirs: { ...cicero.dirs, caster: distOf('@beltype/caster', 1), common: distOf('@beltype/common/errors', 0), merge } };
 }
 /** The document as the page is served it: Caster's import map and Cicero's head ahead of the author's own. */
 export function servedHtml(html) {
@@ -32,6 +34,8 @@ export function servedHtml(html) {
     const imports = Object.fromEntries(['errors', 'data-beltype', 'flags', 'mime'].map((m) => [`@beltype/common/${m}`, `/_beltype/common/${m}.js`]));
     return spliceHead(html, `<script type="importmap">${JSON.stringify({ imports })}</script>\n  ${ciceroEngine.headHtml('/')}`);
 }
+/** One deferral as a line of its own after the run, so a print that approximated or dropped something says so (codeberg.org/BelType/cli issue 1). */
+export const deferralLine = (d) => `deferred: ${d.path}: ${d.feature}, painted as ${d.paintedAs}`;
 /** `fragment` at the top of the document's `<head>`, ahead of the author's own sheets and scripts. */
 export function spliceHead(html, fragment) {
     const head = /<head\b[^>]*>/i.exec(html);
@@ -101,8 +105,17 @@ export async function printOnPage(page, missing, flags, o) {
         await page.goto(ORIGIN + o.docPath, { waitUntil: 'load' });
     }
     progress?.lap('load');
+    return cutAndPrint(page, missing, flags, o);
+}
+/**
+ * The second half of {@link printOnPage}, on a document already in the page: a host that writes the document itself, as a mail merge does, comes in here.
+ *
+ * @throws {BuildError} where the cut or the print refused.
+ */
+export async function cutAndPrint(page, missing, flags, o) {
+    const { progress } = o;
     progress?.step('cut');
-    const cut = await page.evaluate(cutInPage, { cicero: flags.cicero, measures: o.measures === true });
+    const cut = await page.evaluate(cutInPage, { cicero: flags.cicero, measures: o.measures === true, ...(o.resumeAt ? { resumeAt: o.resumeAt } : {}) });
     progress?.lap('cut');
     const measures = 'refused' in cut ? [] : cut.measures;
     progress?.cicero?.(measures);
@@ -119,12 +132,12 @@ export async function printOnPage(page, missing, flags, o) {
         const sheet = chromiumSheet(await page.evaluate(pageSizesInPage));
         await page.evaluate(chromiumSheetInPage, sheet);
         const bytes = await page.pdf({ preferCSSPageSize: true, printBackground: true });
-        return { bytes, pages: await page.locator('beltype-page').count(), words: 0, warnings: [], caster: null, cicero: measures, screens };
+        return { bytes, pages: await page.locator('beltype-page').count(), words: 0, warnings: [], deferred: [], conformance: null, caster: null, cicero: measures, screens, confessions: [] };
     }
     const printed = await page.evaluate(printInPage, { options: flags.caster, ...(o.created !== undefined ? { created: o.created } : {}), ...(o.sharedWriter ? { sharedWriter: true } : {}) });
     if ('refused' in printed)
         throw refusal(missing, printed);
-    return { bytes: Buffer.from(printed.base64, 'base64'), pages: printed.pages, words: printed.words, warnings: printed.warnings, caster: printed.caster, cicero: measures, screens, printMs: printed.printMs };
+    return { bytes: Buffer.from(printed.base64, 'base64'), pages: printed.pages, words: printed.words, warnings: printed.warnings, deferred: printed.deferred, conformance: printed.conformance, caster: printed.caster, cicero: measures, screens, confessions: printed.confessions, printMs: printed.printMs };
 }
 /** The run's refusal: what it could not answer comes first, because a missing file's name says more than the step it broke. */
 export function refusal(missing, answer) {

package/dist/src/serve.js

@@ -4,12 +4,15 @@
  * @remarks
  * **One browser, one context, one holder page.** The context carries the companions' routes; the holder page opens the shared writer worker (Caster's `formeSharedWorkerUrl()`) and keeps it for as long as the page lives, so forme's WebAssembly stays warm across prints. A print is a new page in that context, routed to its own folder alone ({@link routeDocument}), run through {@link printOnPage} with `sharedWriter`, and closed.
  *
- * **One kept print page, for a document with no script of its own.** A print re-seats the kept page as Caster's kept frame does (`document.open()` keeps the `Window`, so the realm, Caster's registry and the companions' modules stay warm; *the printer runs in the realm it prints*, Caster's DESIGN.md S20, S87, S89): its routes are swapped for the print's folder, the served document is written in, and each module script the document names gets a query of its own. That page is shared only by a document whose text holds none of `<script`, `<iframe`, `<object`, `<embed`, `<frame`, `<portal`, `javascript:` or an `on…=` attribute ({@link keptRoad}); any other gets a new page, and the log line names the road. A print that fails or times out closes the kept page, and the next opens a new one.
+ * **One kept print page, for a document with no script of its own.** A print re-seats the kept page as Caster's kept frame does (`document.open()` keeps the `Window`, so the realm, Caster's registry and the companions' modules stay warm; *the printer runs in the realm it prints*, Caster's DESIGN.md S20, S87, S89): its routes are swapped for the print's folder, the served document is written in, and each module script the document names gets a query of its own. That page is shared only by a document whose text, its JSON-LD data blocks aside, holds none of `<script`, `<iframe`, `<object`, `<embed`, `<frame`, `<portal`, `javascript:` or an `on…=` attribute ({@link keptRoad}); any other gets a new page, and the log line names the road. A print that fails or times out closes the kept page, and the next opens a new one.
+ *
+ * **A mail merge, on the same page.** `POST /templates` takes a template's folder once, and `POST /templates/<id>/print` takes one customer's values and rows as JSON. The first customer seats the template and merges in the tab; each later one replaces only the top-level boxes that changed and resumes the cut (`merge-tab.ts`), which keeps the sheets, the faces and the rewrite, and leaves nothing of the customer before. Where the shape of the body changed, or Cicero will not promise the patch, the template is seated again and the log line says why. Measured 2026-11-07 on the bolletta: the PDF byte for byte the folder route's, and 30 to 50 ms less on a 61-day bill (codeberg.org/BelType/cli issue 2).
  *
  * **One at a time, and kept alive.** A promise chain runs the prints in turn. The browser is closed and started again (routes, holder page, warm-up) after `restartAfter` prints and after a print that failed with a 500, and a disconnected browser is started again before the next print. The warm-up prints a built-in document twice under forme, so the first request is warm too.
  *
  * @packageDocumentation
  */
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import http from 'node:http';
 import os from 'node:os';
@@ -19,7 +22,8 @@ import { chromium } from 'playwright-core';
 import { ciceroFlags } from '@beltype/cicero/flags';
 import { BuildError, ValidationError, FlagError } from '@beltype/common/errors';
 import { cliFlags, createdFromEnv, parseFlagArgs } from './flags.js';
-import { ARGS, ORIGIN, VIEWPORT, documentAssets, servedHtml, routeCompanions, routeDocument, printOnPage, refusal } from './run.js';
+import { ARGS, ORIGIN, VIEWPORT, documentAssets, servedHtml, routeCompanions, routeDocument, printOnPage, cutAndPrint, refusal, deferralLine } from './run.js';
+import { keepMergeInPage, reseatInPage, seatMergeInPage } from './in-page.js';
 const HOLDER_PATH = '/_beltype/holder.html';
 const HOLDER = `<!doctype html><html><head><meta charset="utf-8"><title>holder</title></head><body><script type="module">
 const c = await import('/_beltype/caster/src/index.js');
@@ -31,23 +35,41 @@ const WORDS = 'the quick brown fox jumps over a lazy dog while leaf litter decom
 const paragraph = (n) => Array.from({ length: 90 }, (_, i) => WORDS[(i * 7 + n * 3) % WORDS.length]).join(' ') + '.';
 /** Plain paragraphs and one heading, in the one face the CLI ships for it (`assets/warmup/`, SIL OFL): neither Cicero nor Caster supplies a default face, and Caster refuses a document with none. */
 export const WARMUP = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Warm-up</title><style>@font-face { font-family: Warm; src: url(warm.woff2) format("woff2"); font-weight: 200 900 } @page { size: A4; margin: 20mm } body { font: 11pt/1.4 Warm }</style></head><body><h1>Warm-up</h1>${Array.from({ length: 16 }, (_, n) => `<p>${paragraph(n)}</p>`).join('')}</body></html>`;
+/** ponytail: the oldest template is dropped past this, and its id answers 404; a named delete when a host needs to hold more. */
+const TEMPLATES_KEPT = 16;
 const DOC_PATH = '/index.html';
+/** The binds that listen on every address, under which a request's `Host` cannot be checked against one name. */
+const WILDCARD = new Set(['0.0.0.0', '::', '[::]']);
 const lapper = (steps) => {
     const began = {};
     return { start: (name) => { began[name] = performance.now(); }, end: (name) => { steps[name] = performance.now() - (began[name] ?? performance.now()); } };
 };
-const stepsLine = ({ road, ms: steps }, printed) => `road ${road}; ${['page', 'load', 'cut', 'print', 'close'].map((n) => `${n} ${Math.round(steps[n] ?? 0)}`).join(', ')}; caster ${Object.entries(printed.caster?.ms ?? {}).map(([k, v]) => `${k} ${Math.round(Number(v))}`).join(', ')}`;
-/** Whether a document may share the kept page: only one with no script of its own (the `Window` outlives `document.open()`, and so does a timer, a listener or a global a script left on it). The test is conservative; a false alarm costs only speed. */
-export const keptRoad = (html) => !/<script|<iframe|<object|<embed|<frame|<portal|javascript:|\son[a-z]+\s*=/i.test(html);
+const stepsLine = ({ road, ms: steps }, printed) => `road ${road}; ${['page', 'load', 'merge', 'cut', 'print', 'close'].map((n) => `${n} ${Math.round(steps[n] ?? 0)}`).join(', ')}; caster ${Object.entries(printed.caster?.ms ?? {}).map(([k, v]) => `${k} ${Math.round(Number(v))}`).join(', ')}`;
+/** A JSON-LD data block, which the browser never runs: an opening tag with that attribute and at most a plain `id`, as a store host saves it, to the first `</script` (the tokenizer ends the element there or later, never sooner, so what is cut is always inside the block). */
+const DATA_BLOCK = /<script\s+type\s*=\s*(["']?)application\/ld\+json\1(?:\s+id\s*=\s*(["']?)[\w-]+\2)?\s*>[\s\S]*?<\/script/gi;
+/** Whether a document may share the kept page: only one with no script of its own (the `Window` outlives `document.open()`, and so does a timer, a listener or a global a script left on it). A JSON-LD data block is data, not script, and does not count. The test is conservative; a false alarm costs only speed. */
+export const keptRoad = (html) => !/<script|<iframe|<object|<embed|<frame|<portal|javascript:|\bon[a-z]+\s*=/i.test(html.replace(DATA_BLOCK, ''));
 class HttpError extends Error {
     status;
     constructor(status, message) { super(message); this.status = status; }
 }
 export async function serve(options) {
     const log = options.log ?? ((line) => console.log(line));
+    const wildcard = WILDCARD.has(options.host);
+    const allowed = new Set((options.allowedHosts ?? []).map((h) => h.toLowerCase()));
+    if (wildcard && !allowed.size)
+        throw new ValidationError(`beltype serve: --host ${options.host} listens on every address, so the server cannot tell its own name from a rebound one; name the hosts it answers with --allowed-hosts <name[:port],…>.`);
     const assets = documentAssets();
-    const missing = new Set();
+    /** What the print running now could not answer; null between prints, so a page left over from one never writes into the next. */
+    let active = null;
+    /** The routes' one sink, context's and pages' alike: a kept page's routes outlive the print that set them. */
+    const missing = { add: (entry) => active?.add(entry) };
+    /** The page the print running now uses, which a timeout closes. */
+    let current = null;
     let kept = null;
+    /** The template whose merge the kept page shows, or null when it shows anything else. */
+    let seated = null;
+    const templates = new Map();
     let reseats = 0;
     let browser = null;
     let context = null;
@@ -60,7 +82,7 @@ export async function serve(options) {
     let tail = Promise.resolve();
     const stopBrowser = async () => {
         const old = browser;
-        browser = context = kept = null;
+        browser = context = kept = seated = null;
         await old?.close().catch(() => { });
     };
     /** The kept page, opened on a blank document at the document's own path so that relative references resolve as a print's would. */
@@ -69,17 +91,19 @@ export async function serve(options) {
         page.on('pageerror', (error) => console.warn(`page error: ${error.message}`));
         await routeDocument(page, missing, { root: path.join(os.tmpdir(), 'beltype-serve-none'), docPath: DOC_PATH, served: servedHtml('<!doctype html><html><head></head><body></body></html>') });
         await page.goto(ORIGIN + DOC_PATH, { waitUntil: 'load' });
+        seated = null;
         return kept = page;
     };
     /** Closes `page`, and forgets it if it is the kept one: a page a failed or timed-out print used is never reused. */
     const closePage = async (page) => {
         if (kept === page)
-            kept = null;
+            kept = seated = null;
         await page.close().catch(() => { });
     };
     /** Run `html` and `files` through the print's road: re-seated on the kept page where the document carries no script of its own, else on a new page. The folder is gone after. */
     const render = async (files, given, created, trace = { road: 'fresh', ms: {} }) => {
         const root = fs.mkdtempSync(path.join(os.tmpdir(), 'beltype-serve-'));
+        const mine = new Set();
         try {
             for (const [name, bytes] of files) {
                 const file = path.join(root, ...name.split('/'));
@@ -91,20 +115,22 @@ export async function serve(options) {
             const served = servedHtml(author);
             const keep = keptRoad(author);
             trace.road = keep ? 'kept' : 'fresh';
-            missing.clear();
             const lapped = lapper(trace.ms);
             lapped.start('page');
-            const page = keep ? (kept ?? await openKept()) : await context.newPage();
+            const page = current = keep ? (kept ?? await openKept()) : await context.newPage();
+            active = mine;
             try {
-                if (keep)
+                if (keep) {
+                    seated = null;
                     await page.unrouteAll({ behavior: 'wait' });
+                }
                 await routeDocument(page, missing, { root, docPath: DOC_PATH, served });
                 lapped.end('page');
                 const reseat = keep ? served.replace(/(<script type="module" src="[^"?]+)"/g, `$1?kept=${++reseats}"`) : undefined;
-                const printed = await printOnPage(page, missing, flags, { docPath: DOC_PATH, sharedWriter: true, progress: { step: lapped.start, lap: lapped.end }, ...(reseat !== undefined ? { reseat } : {}), ...(created !== undefined ? { created } : {}) });
+                const printed = await printOnPage(page, mine, flags, { docPath: DOC_PATH, sharedWriter: true, progress: { step: lapped.start, lap: lapped.end }, ...(reseat !== undefined ? { reseat } : {}), ...(created !== undefined ? { created } : {}) });
                 lapped.end('print');
-                if (missing.size)
-                    throw refusal(missing, null);
+                if (mine.size)
+                    throw refusal(mine, null);
                 if (!keep) {
                     lapped.start('close');
                     await closePage(page);
@@ -118,11 +144,69 @@ export async function serve(options) {
             }
         }
         finally {
+            if (active === mine)
+                active = null;
             fs.rmSync(root, { recursive: true, force: true });
         }
     };
+    /** One customer of `template` on the kept page: the changed boxes replaced where the template is seated, else the template seated and merged. */
+    const renderMerge = async (template, data, created, trace) => {
+        const flags = { caster: template.given.caster, cicero: ciceroFlags.resolve(template.given.cicero), beltype: cliFlags.resolve(template.given.beltype) };
+        const mine = new Set();
+        const lapped = lapper(trace.ms);
+        lapped.start('page');
+        const page = current = kept ?? await openKept();
+        active = mine;
+        lapped.end('page');
+        const merged = (answer) => {
+            if ('refused' in answer)
+                throw refusal(mine, answer);
+            return answer;
+        };
+        try {
+            let resumeAt = null;
+            lapped.start('merge');
+            if (seated === template.id) {
+                const answer = merged(await page.evaluate(keepMergeInPage, data));
+                if ('again' in answer) {
+                    log(`beltype serve: the template is seated again: ${answer.again}`);
+                    seated = null;
+                }
+                else {
+                    resumeAt = answer.resumeAt;
+                    trace.road = 'merge kept';
+                }
+            }
+            if (seated !== template.id) {
+                lapped.start('load');
+                await page.unrouteAll({ behavior: 'wait' });
+                const served = servedHtml(template.author);
+                await routeDocument(page, missing, { root: template.root, docPath: DOC_PATH, served });
+                await page.evaluate(reseatInPage, served.replace(/(<script type="module" src="[^"?]+)"/g, `$1?kept=${++reseats}"`));
+                lapped.end('load');
+                lapped.start('merge');
+                merged(await page.evaluate(seatMergeInPage, { template: template.author, data }));
+                seated = template.id;
+                trace.road = 'merge seated';
+            }
+            lapped.end('merge');
+            const printed = await cutAndPrint(page, mine, flags, { sharedWriter: true, resumeAt, progress: { step: lapped.start, lap: lapped.end }, ...(created !== undefined ? { created } : {}) });
+            lapped.end('print');
+            if (mine.size)
+                throw refusal(mine, null);
+            return printed;
+        }
+        catch (error) {
+            await closePage(page);
+            throw error;
+        }
+        finally {
+            if (active === mine)
+                active = null;
+        }
+    };
     const start = async () => {
-        browser = await chromium.launch({ headless: true, args: ARGS });
+        browser = await chromium.launch({ headless: true, args: ARGS, chromiumSandbox: options.sandbox ?? true });
         const mine = browser;
         version = mine.version();
         mine.on('disconnected', () => { if (browser === mine)
@@ -173,7 +257,8 @@ export async function serve(options) {
         return result;
     };
     await start();
-    const print = async (req) => {
+    /** A request's form: the document's files, the flags, and the instant the file says it was made. */
+    const readDocument = async (req) => {
         const form = await readForm(req, options.maxUpload);
         const files = new Map();
         const args = [];
@@ -195,37 +280,103 @@ export async function serve(options) {
             throw new ValidationError('beltype serve: the form has no index.html file.');
         const given = await parseFlagArgs(args);
         created ??= createdFromEnv();
-        const writer = String(given.caster['writer'] ?? 'pdf-lib');
-        return enqueue(async () => {
-            const id = prints + 1;
-            log(`beltype serve: print ${id} started`);
-            const t0 = performance.now();
-            const trace = { road: 'fresh', ms: {} };
-            const run = render(files, given, created, trace);
-            let timer;
-            const limit = new Promise((_, reject) => { timer = setTimeout(() => reject(new HttpError(504, `beltype serve: the print took over ${options.timeout / 1000} s.`)), options.timeout); });
-            try {
-                const printed = await Promise.race([run, limit]);
-                prints++;
-                sinceStart++;
-                log(`beltype serve: print ${id}: 200, ${printed.pages} pages, ${writer}, ${Math.round(performance.now() - t0)} ms (write ${printed.caster?.ms['emit'] ?? '?'} ms)`);
-                log(`beltype serve: print ${id}: ${stepsLine(trace, printed)}`);
-                return { bytes: printed.bytes, printed, writer };
-            }
-            catch (error) {
-                prints++;
-                sinceStart++;
-                run.catch(() => { });
-                if (error instanceof HttpError && kept)
+        return { files, args, given, created, writer: String(given.caster['writer'] ?? 'pdf-lib') };
+    };
+    /** A print's turn: logged, held to the timeout, and counted towards a restart. */
+    const inTurn = (writer, run) => enqueue(async () => {
+        const id = prints + 1;
+        log(`beltype serve: print ${id} started`);
+        const t0 = performance.now();
+        const trace = { road: 'fresh', ms: {} };
+        const running = run(trace);
+        let timer;
+        const limit = new Promise((_, reject) => { timer = setTimeout(() => reject(new HttpError(504, `beltype serve: the print took over ${options.timeout / 1000} s.`)), options.timeout); });
+        try {
+            const printed = await Promise.race([running, limit]);
+            prints++;
+            sinceStart++;
+            log(`beltype serve: print ${id}: 200, ${printed.pages} pages, ${writer}, ${Math.round(performance.now() - t0)} ms (write ${printed.caster?.ms['emit'] ?? '?'} ms)`);
+            log(`beltype serve: print ${id}: ${stepsLine(trace, printed)}`);
+            return { bytes: printed.bytes, printed, writer };
+        }
+        catch (error) {
+            prints++;
+            sinceStart++;
+            running.catch(() => { });
+            if (error instanceof HttpError) {
+                // The page the print still runs on is closed, so it asks for nothing more, and the print is let end, so its folder goes before the answer.
+                if (current)
+                    await closePage(current);
+                if (kept)
                     await closePage(kept);
-                if (!(error instanceof BuildError) && !(error instanceof HttpError))
-                    needsRestart = true;
-                throw error;
+                await running.catch(() => { });
             }
-            finally {
-                clearTimeout(timer);
-            }
-        });
+            if (!(error instanceof BuildError) && !(error instanceof HttpError))
+                needsRestart = true;
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    });
+    const print = async (req) => {
+        const { files, given, created, writer } = await readDocument(req);
+        return inTurn(writer, (trace) => render(files, given, created, trace));
+    };
+    /** A template's folder, kept on disk under the hash of what it holds, so uploading it again is the same template. */
+    const uploadTemplate = async (req) => {
+        const { files, args, given } = await readDocument(req);
+        const author = Buffer.from(files.get('index.html')).toString('utf8');
+        if (!keptRoad(author))
+            throw new ValidationError('beltype serve: a template holds no script of its own, nor an <iframe>, <object>, <embed>, <frame>, <portal>, javascript: or on…= attribute: the merge runs in one kept page, which they would outlive.');
+        if (author.search(DATA_BLOCK) < 0)
+            throw new ValidationError('beltype serve: a template has a data block, a <script type="application/ld+json">; this one has none.');
+        const hash = crypto.createHash('sha256');
+        for (const name of [...files.keys()].sort())
+            hash.update(name).update('\0').update(files.get(name)).update('\0');
+        const id = hash.update(args.sort().join('\0')).digest('hex').slice(0, 32);
+        if (templates.has(id))
+            return id;
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'beltype-template-'));
+        for (const [name, bytes] of files) {
+            const file = path.join(root, ...name.split('/'));
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, bytes);
+        }
+        templates.set(id, { id, root, author, given });
+        for (const old of templates.values()) {
+            if (templates.size <= TEMPLATES_KEPT)
+                break;
+            if (old.id === seated)
+                continue;
+            templates.delete(old.id);
+            fs.rmSync(old.root, { recursive: true, force: true });
+        }
+        return id;
+    };
+    /** One customer of a template: the body is JSON, `{ values, rows, created }`. */
+    const printMerge = async (id, req) => {
+        const template = templates.get(id);
+        if (!template)
+            throw new HttpError(404, `beltype serve: no template ${id}; POST its folder to /templates (the oldest are dropped past ${TEMPLATES_KEPT}, and a restart of the server forgets them all).`);
+        const { data, created } = mergeBody(await readBody(req, options.maxUpload));
+        return inTurn(String(template.given.caster['writer'] ?? 'pdf-lib'), (trace) => renderMerge(template, data, created ?? createdFromEnv(), trace));
+    };
+    /** The `Host` a request must name; set once the server listens. */
+    let authority = '';
+    /**
+     * Whether a request does not name this server, or comes from a page of another origin: a page in the user's browser can POST a form here with no preflight, and a rebound name reaches it under its own `Host`.
+     *
+     * @remarks
+     * Under a wildcard bind (`0.0.0.0`, `::`) the server cannot know which name it is reached by, so the `Host` must be on `allowedHosts`, which `serve` demands there. An entry with no port names the host on any port.
+     */
+    const foreign = (req) => {
+        const host = (req.headers.host ?? '').toLowerCase();
+        const named = (!wildcard && host === authority) || allowed.has(host) || allowed.has(host.replace(/:\d+$/, ''));
+        if (!named)
+            return true;
+        const origin = req.headers.origin;
+        return origin !== undefined && origin !== '' && origin.toLowerCase() !== `http://${host}`;
     };
     const server = http.createServer(async (req, res) => {
         const send = (status, type, body, headers = {}) => {
@@ -234,28 +385,38 @@ export async function serve(options) {
         };
         const text = (status, message) => send(status, 'text/plain; charset=utf-8', message + '\n');
         try {
+            if (foreign(req))
+                throw new HttpError(403, `beltype serve: refused a request for ${req.headers.host ?? 'no host'} from ${req.headers.origin ?? 'no origin'}; it answers ${[...(wildcard ? [] : [authority]), ...allowed].join(', ')} and no page of another origin.`);
             const pathname = new URL(req.url ?? '/', 'http://x').pathname;
             if (pathname === '/health') {
                 if (req.method !== 'GET')
                     return text(405, 'beltype serve: /health takes GET.');
                 return send(restarting ? 503 : 200, 'application/json', JSON.stringify({ status: restarting ? 'restarting' : 'up', chromium: version, prints, queued }));
             }
-            if (pathname !== '/print')
-                return text(404, `beltype serve: no ${pathname}; there is POST /print and GET /health.`);
+            if (pathname === '/templates') {
+                if (req.method !== 'POST')
+                    return text(405, 'beltype serve: /templates takes POST.');
+                return send(201, 'application/json', JSON.stringify({ template: await uploadTemplate(req) }));
+            }
+            const merge = /^\/templates\/([0-9a-f]+)\/print$/.exec(pathname);
+            if (pathname !== '/print' && !merge)
+                return text(404, `beltype serve: no ${pathname}; there is POST /print, POST /templates, POST /templates/<id>/print and GET /health.`);
             if (req.method !== 'POST')
-                return text(405, 'beltype serve: /print takes POST.');
-            const { bytes, printed, writer } = await print(req);
+                return text(405, `beltype serve: ${pathname} takes POST.`);
+            const { bytes, printed, writer } = await (merge ? printMerge(merge[1], req) : print(req));
             for (const warning of printed.warnings)
                 log(`beltype serve: warning: ${typeof warning === 'string' ? warning : JSON.stringify(warning)}`);
-            send(200, 'application/pdf', bytes, { 'x-beltype-pages': printed.pages, 'x-beltype-words': printed.words, 'x-beltype-warnings': printed.warnings.length });
+            for (const deferral of printed.deferred)
+                log(`beltype serve: ${deferralLine(deferral)}`);
+            send(200, 'application/pdf', bytes, { 'x-beltype-pages': printed.pages, 'x-beltype-words': printed.words, 'x-beltype-warnings': printed.warnings.length, 'x-beltype-deferred': printed.deferred.length, ...standardHeader(printed.conformance) });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             const status = error instanceof HttpError ? error.status : error instanceof BuildError ? 422 : error instanceof ValidationError || error instanceof FlagError ? 400 : 500;
             log(`beltype serve: ${req.method} ${req.url}: ${status}`);
-            if (status === 413) {
-                // Keep nothing more: answer, discard what still arrives (a client cut off mid-write sees EPIPE, not the 413), and drop the connection after a second if the client is still sending.
-                res.writeHead(413, { 'content-type': 'text/plain; charset=utf-8' });
+            if (status === 413 || status === 403) {
+                // Keep nothing more: answer, discard what still arrives (a client cut off mid-write sees EPIPE, not the answer), and drop the connection after a second if the client is still sending.
+                res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
                 res.end(message + '\n', () => {
                     req.resume();
                     setTimeout(() => req.destroy(), 1000).unref();
@@ -267,7 +428,8 @@ export async function serve(options) {
     });
     await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port, options.host, resolve); });
     const address = server.address();
-    const url = `http://${options.host}:${address.port}`;
+    authority = `${options.host.includes(':') ? `[${options.host}]` : options.host}:${address.port}`.toLowerCase();
+    const url = `http://${authority}`;
     log(`beltype serve: listening on ${url}`);
     return {
         url,
@@ -276,11 +438,13 @@ export async function serve(options) {
             await new Promise((resolve) => server.close(() => resolve()));
             await tail;
             await stopBrowser();
+            for (const { root } of templates.values())
+                fs.rmSync(root, { recursive: true, force: true });
         }
     };
 }
-/** The request's multipart form, read up to `limit` bytes. @throws {HttpError} 413 as soon as the count passes the limit; {ValidationError} where the body is not a form. */
-async function readForm(req, limit) {
+/** The request's body, read up to `limit` bytes. @throws {HttpError} 413 as soon as the count passes the limit. */
+async function readBody(req, limit) {
     const declared = Number(req.headers['content-length'] ?? 0);
     if (declared > limit)
         throw new HttpError(413, `beltype serve: the upload is ${declared} bytes, over the limit of ${limit}.`);
@@ -292,11 +456,37 @@ async function readForm(req, limit) {
             throw new HttpError(413, `beltype serve: the upload is over the limit of ${limit} bytes.`);
         chunks.push(chunk);
     }
+    return Buffer.concat(chunks);
+}
+/** One customer's JSON: `values` a flat object of strings, numbers and booleans, `rows` a table of arrays of flat objects, `created` an instant. @throws {ValidationError} */
+function mergeBody(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        throw new ValidationError('beltype serve: the customer is JSON: { "values": { … }, "rows": { "<table>": [ { … } ] } }; the body does not parse.');
+    }
+    const isObject = (x) => typeof x === 'object' && x !== null && !Array.isArray(x);
+    if (!isObject(parsed))
+        throw new ValidationError('beltype serve: the customer is a JSON object with "values" and "rows".');
+    const { values = {}, rows = {}, created } = parsed;
+    if (!isObject(values) || Object.values(values).some((v) => !['string', 'number', 'boolean'].includes(typeof v)))
+        throw new ValidationError('beltype serve: "values" is an object of strings, numbers and booleans.');
+    if (!isObject(rows) || Object.values(rows).some((table) => !Array.isArray(table) || table.some((row) => !isObject(row))))
+        throw new ValidationError('beltype serve: "rows" is an object of tables, each an array of objects.');
+    if (created !== undefined && typeof created !== 'string')
+        throw new ValidationError('beltype serve: "created" is an ISO 8601 instant.');
+    return { data: { values, rows }, created: created === undefined ? undefined : instant(created) };
+}
+/** The request's multipart form, read up to `limit` bytes. @throws {HttpError} 413 as soon as the count passes the limit; {ValidationError} where the body is not a form. */
+async function readForm(req, limit) {
+    const body = await readBody(req, limit);
     const type = req.headers['content-type'] ?? '';
     if (!/^multipart\/form-data/i.test(type))
         throw new ValidationError('beltype serve: POST /print takes multipart/form-data.');
     try {
-        return await new Response(Buffer.concat(chunks), { headers: { 'content-type': type } }).formData();
+        return await new Response(body, { headers: { 'content-type': type } }).formData();
     }
     catch {
         throw new ValidationError('beltype serve: the body is not a well-formed multipart/form-data.');
@@ -316,3 +506,5 @@ function instant(value) {
         throw new ValidationError(`beltype serve: created is an ISO 8601 instant; got "${value}".`);
     return date.toISOString();
 }
+/** What the file claims, as Caster's report says it: `x-beltype-standard: pdf-2.0; pdf-ua-2`, or `pdf-2.0` alone where the claim was not asked for or was withdrawn. A print under `beltype.printer=chromium` is Chromium's own file, which Caster never saw, and carries no header. */
+export const standardHeader = (conformance) => conformance === null ? {} : { 'x-beltype-standard': conformance === 'pdfua2' ? 'pdf-2.0; pdf-ua-2' : 'pdf-2.0' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beltype/cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "beltype, the command line: a finished HTML document printed to PDF by Cicero and Caster in Chromium's headless shell.",
   "type": "module",
   "license": "MIT",
@@ -27,21 +27,33 @@
   },
   "pnpm": {
     "onlyBuiltDependencies": [
-      "@beltype/cicero",
       "@beltype/caster",
-      "@beltype/common"
+      "@beltype/cicero",
+      "@beltype/common",
+      "esbuild"
     ]
   },
   "dependencies": {
-    "@beltype/caster": "0.1.7",
-    "@beltype/cicero": "0.1.6",
+    "@beltype/caster": "0.2.5",
+    "@beltype/cicero": "0.1.10",
     "@beltype/common": "0.1.2",
-    "mupdf": "1.28.1",
     "playwright-core": "1.63.0"
   },
+  "peerDependencies": {
+    "mupdf": "1.28.1"
+  },
+  "peerDependenciesMeta": {
+    "mupdf": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@beltype/specimens": "0.1.0",
+    "@beltype/specimens": "0.1.1",
     "@types/node": "^22.20.5",
+    "esbuild": "0.28.2",
+    "linkedom": "0.18.14",
+    "mupdf": "1.28.1",
+    "prosemirror-stores": "git+https://codeberg.org/egildo/prosemirror-stores.git#3b281922616bf674c9338de73626b98b8f0a1d8d",
     "typescript": "7.0.2"
   },
   "bugs": {