@beltype/cli 0.1.4 → 0.1.5

package/README.md

@@ -6,6 +6,7 @@ The BelType command line. It prints a finished HTML document to PDF: Cicero cuts
 beltype print paper/index.html            # writes paper/index.pdf
 beltype print paper/index.html -o paper.pdf
 beltype print paper/index.html --printer chromium --check --trace trace.json
+beltype serve                             # the same, behind HTTP: see below
 ```
 
 ## Flags
@@ -19,9 +20,25 @@ beltype print paper/index.html --flag caster.shaper=fontkit --flag cicero.compos
 - `--printer caster|chromium`: who prints the pages Cicero presented. Chromium prints them one sheet to a page; it refuses, naming `--printer caster`, when the pages are not all one size.
 - `--trace <file.json>`: where the run's time went. `process` is node's clock around each step (launch, context, load, cut, print, transfer, close, write), `cicero` is Cicero's own `performance.measure` entries, `caster` is Caster's report (`ms` per stage and `timing`; `null` under Chromium), with the versions and the resolved flags. It is written even when the run refuses, with the step that refused.
 - `--check`: the proof that the PDF is the screen. Each presented page is screenshotted at 96 dpi, the PDF is rasterised at 96 dpi and the pairs are diffed into `<name>.check/` (`screen-N.png`, `print-N.png`, `diff-N.png`, `check.json`). It reports a share of differing pixels per page and a mean, and never fails the run. It tolerates one pixel of slip, because the screen's pages sit at fractional heights (A4 is 1122.52 px) and Skia and mupdf shade letter edges differently.
+- `SOURCE_DATE_EPOCH=<seconds>` (an environment variable, not a flag): the moment the file says it was made, whole seconds since 1970 as the reproducible-builds convention has it. Set, the file's `/CreationDate` and `/ModDate` are that instant and the same document printed twice gives the same bytes; unset, they are the wall clock.
 
 The document is plain HTML, CSS and the files beside it. The run answers every request from the document's folder, on a made-up `.invalid` address, and refuses anything else by name: a document that asks for a file it does not have, or for anything on a network, prints nothing. Fonts must be declared with `@font-face` and their files, because Caster embeds every face it draws.
 
+## beltype serve
+
+`beltype serve` is `beltype print` behind an HTTP door, in Gotenberg's shape: one Chromium kept warm, and forme kept warm in a shared worker that every document's page hands its display list to, so a print skips the browser's launch and forme's cold first write. A print is still `beltype print`'s: Cicero cuts and Caster prints in the document's own page, answered from the files it was posted with.
+
+```bash
+beltype serve --port 3000
+curl -F index.html=@index.html -F paper.css=@paper.css -F fonts/a.woff2=@fonts/a.woff2 -F caster.writer=forme http://127.0.0.1:3000/print -o out.pdf
+```
+
+- `POST /print`, `multipart/form-data`. `index.html` is required; every other file keeps its form field name as its path relative to the document (`fonts/a.woff2`), plain segments with `/` separators, never absolute and never `..`. A field that is not a file is a flag, `<owner>.<name>` = value (`caster.writer=forme`, `cicero.…`); `beltype.check` is refused. A field `created` (an ISO 8601 instant) fixes the file's dates, else `SOURCE_DATE_EPOCH`, else the clock. The answer is `200 application/pdf` with `X-Beltype-Pages`, `X-Beltype-Words` and `X-Beltype-Warnings` (the count); `422` with `beltype print`'s sentence where the document is refused (a file it asked for and was not given, among them); `400` for a bad request; `413` over the upload limit; `504` over the time limit; `500` otherwise, after which the browser is restarted.
+- `GET /health`: `{ "status": "up", "chromium": …, "prints": …, "queued": … }`, or `503` with `"status": "restarting"` while the browser starts again.
+- `--host 127.0.0.1`, `--port 3000`, `--max-upload 50` (MB), `--timeout 60` (seconds per print), `--restart-after 100` (prints before the browser is restarted).
+- One print runs at a time; the others wait their turn. After every start the server prints a built-in document twice under forme (the log shows both writes), so the first request is warm.
+- It binds `127.0.0.1` unless `--host` says otherwise, and fetches nothing from a network: a document that asks for anything it was not posted is refused by name, as in `beltype print`. The built-in warm-up document ships one font, Source Sans 3 (SIL OFL), in `assets/warmup/`.
+
 ## The sample
 
 `paper`, from [`@beltype/specimens`](https://codeberg.org/BelType/specimens), is a short scientific article on A4 (its data are invented). It exercises what a paged document needs:

package/assets/warmup/OFL-SourceSans3.txt

@@ -0,0 +1,93 @@
+Copyright 2010-2020 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe in the United States and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/src/flags.js

@@ -52,3 +52,12 @@ export async function flagsHelp() {
     const valuesWidth = Math.max(...rows.map((r) => r[1].length));
     return `${rows.map(([flag, values, def]) => `  ${flag.padEnd(width)}  ${values.padEnd(valuesWidth)}  default ${def}`).join('\n')}`;
 }
+/** The instant `SOURCE_DATE_EPOCH` names (whole seconds since 1970, the reproducible-builds convention), as an ISO 8601 string; undefined where the variable is not set. @throws {ValidationError} where it is not whole seconds. */
+export function createdFromEnv(env = process.env) {
+    const epoch = env['SOURCE_DATE_EPOCH'];
+    if (epoch === undefined || epoch === '')
+        return undefined;
+    if (!/^\d{1,15}$/.test(epoch))
+        throw new ValidationError(`beltype: SOURCE_DATE_EPOCH is whole seconds since 1970; got "${epoch}".`);
+    return new Date(Number(epoch) * 1000).toISOString();
+}

package/dist/src/in-page.js

@@ -33,14 +33,15 @@ export async function cutInPage(run) {
 /**
  * Caster prints the presented pages; the bytes cross back as base64, the one form `evaluate` carries intact.
  *
- * @param options - the resolved Caster flags. `printMs` in the answer is Caster's own time in the page, before the bytes are encoded.
+ * @param run - `options` is the resolved Caster flags; `created` is the instant the file says it was made, absent for the wall clock; `sharedWriter` has forme write through a `SharedWorker` the page opens (Caster's `formeSharedWorkerUrl()`), so a host that keeps the page's browser alive keeps the writer warm. `printMs` in the answer is Caster's own time in the page, before the bytes are encoded.
  */
-export async function printInPage(options) {
+export async function printInPage(run) {
     try {
         const t0 = performance.now();
         // @ts-expect-error a URL the page resolves, not a module the checker can find. A literal on purpose: a computed `import()` is wrapped by `rewriteRelativeImportExtensions` in a helper the page does not have.
         const caster = await import('/_beltype/caster/src/index.js');
-        const printed = await caster.print({ document }, options);
+        const formePort = run.sharedWriter ? new SharedWorker(caster.formeSharedWorkerUrl(), { type: 'module', name: 'forme' }).port : undefined;
+        const printed = await caster.print({ document, ...(run.created !== undefined ? { created: run.created } : {}), ...(formePort ? { formePort } : {}) }, run.options);
         const printMs = performance.now() - t0;
         const bytes = printed.bytes;
         let binary = '';

package/dist/src/main.js

@@ -2,19 +2,48 @@
  * The `beltype` command.
  *
  * @remarks
- * One verb so far: `beltype print <file.html> [-o <file.pdf>]`. The output defaults to the input's name with `.pdf`, beside it. A flag the parser does not know is refused, never ignored.
+ * Two verbs: `beltype print <file.html> [-o <file.pdf>]` and `beltype serve` (see `serve.ts`). The output defaults to the input's name with `.pdf`, beside it. A flag the parser does not know is refused, never ignored.
  *
  * Flags have one shape across BelType: `--flag <owner>.<name>=<value>`, repeatable, names a row of a package's table (`beltype print --help` lists them all). `--printer` and `--check` are the command line's own rows spelled plainly; `--trace <file>` takes a free string, so it is a plain option beside the table.
  *
  * @packageDocumentation
  */
 import { parseArgs } from 'node:util';
-import { BelTypeError } from '@beltype/common/errors';
+import { BelTypeError, ValidationError } from '@beltype/common/errors';
 import { checkLines } from './check.js';
-import { cliFlags, flagsHelp, parseFlagArgs } from './flags.js';
+import { cliFlags, createdFromEnv, flagsHelp, parseFlagArgs } from './flags.js';
 import { print } from './print.js';
-const USAGE = 'usage: beltype print <file.html> [-o <file.pdf>] [--printer caster|chromium] [--check] [--trace <file.json>] [--flag <owner>.<name>=<value>]...';
+import { serve } from './serve.js';
+const USAGE = 'usage: beltype serve [--host 127.0.0.1] [--port 3000] [--max-upload 50] [--timeout 60] [--restart-after 100]\n       beltype print <file.html> [-o <file.pdf>] [--printer caster|chromium] [--check] [--trace <file.json>] [--flag <owner>.<name>=<value>]...';
+async function serveVerb(argv) {
+    const { values } = parseArgs({ args: argv, options: {
+            host: { type: 'string', default: '127.0.0.1' },
+            port: { type: 'string', default: '3000' },
+            'max-upload': { type: 'string', default: '50' },
+            timeout: { type: 'string', default: '60' },
+            'restart-after': { type: 'string', default: '100' }
+        } });
+    const number = (name, raw, min) => {
+        if (!/^\d+$/.test(raw) || Number(raw) < min)
+            throw new ValidationError(`beltype serve: --${name} is a whole number of at least ${min}; got "${raw}".`);
+        return Number(raw);
+    };
+    const server = await serve({
+        host: values.host,
+        port: number('port', values.port, 0),
+        maxUpload: number('max-upload', values['max-upload'], 1) * 1024 * 1024,
+        timeout: number('timeout', values.timeout, 1) * 1000,
+        restartAfter: number('restart-after', values['restart-after'], 1)
+    });
+    const stop = () => { void server.close().then(() => process.exit(0)); };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+}
 async function main(argv) {
+    if (argv[0] === 'serve') {
+        await serveVerb(argv.slice(1));
+        return -1;
+    }
     const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
             output: { type: 'string', short: 'o' },
             help: { type: 'boolean', short: 'h' },
@@ -38,14 +67,16 @@ async function main(argv) {
     if (values.check)
         given.beltype['check'] = true;
     const output = values.output ?? input.replace(/\.html?$/i, '') + '.pdf';
-    const result = await print(input, output, { given, ...(values.trace !== undefined ? { trace: values.trace } : {}) });
+    const created = createdFromEnv();
+    const result = await print(input, output, { given, ...(values.trace !== undefined ? { trace: values.trace } : {}), ...(created ? { created } : {}) });
     console.log(`${result.output}: ${result.pages} pages, ${result.words} words, ${(result.ms / 1000).toFixed(1)} s`);
     if (result.check)
         for (const line of checkLines(result.check))
             console.log(line);
     return 0;
 }
-main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+main(process.argv.slice(2)).then((code) => { if (code >= 0)
+    process.exit(code); }, (error) => {
     console.error(error instanceof BelTypeError ? error.message : error);
     process.exit(1);
 });

package/dist/src/print.js

@@ -12,19 +12,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { chromium } from 'playwright-core';
-import { ciceroEngine } from '@beltype/cicero/engine';
 import { ciceroFlags } from '@beltype/cicero/flags';
-import { BuildError } from '@beltype/common/errors';
-import { contentType } from '@beltype/common/mime';
-import { cutInPage, printInPage, pageSizesInPage, chromiumSheetInPage } from './in-page.js';
 import { cliFlags, tableOf } from './flags.js';
-import { chromiumSheet } from './chromium.js';
-import { screenshotPages, checkPages } from './check.js';
-/** `.invalid` is reserved (RFC 2606), so nothing on a network can ever answer it instead. */
-const ORIGIN = 'https://print.invalid';
-const VIEWPORT = { width: 1200, height: 1600 };
-/** Deterministic text and timers that run while nobody watches the page. */
-const ARGS = ['--font-render-hinting=none', '--force-device-scale-factor=1', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows'];
+import { checkPages } from './check.js';
+import { ARGS, VIEWPORT, documentAssets, servedHtml, routeCompanions, routeDocument, printOnPage, refusal } from './run.js';
+export { spliceHead } from './run.js';
 const round = (ms) => Math.round(ms * 10) / 10;
 /**
  * Print `input`, an HTML file, to `output`.
@@ -52,16 +44,8 @@ export async function print(input, output, options = {}) {
         const html = fs.readFileSync(input, 'utf8');
         const root = path.dirname(path.resolve(input));
         const docPath = `/${encodeURIComponent(path.basename(input))}`;
-        // Each companion's built folder, found from a module it exports: common exports no `package.json`.
-        const distOf = (specifier, up) => path.resolve(path.dirname(fileURLToPath(import.meta.resolve(specifier))), ...Array(up).fill('..'));
-        const cicero = ciceroEngine.vendorAssets();
-        const assets = {
-            files: cicero.files,
-            dirs: { ...cicero.dirs, caster: distOf('@beltype/caster', 1), common: distOf('@beltype/common/errors', 0) },
-        };
-        // Caster's modules import common by its package names, which a page resolves only through an import map.
-        const imports = Object.fromEntries(['errors', 'data-beltype', 'flags', 'mime'].map((m) => [`@beltype/common/${m}`, `/_beltype/common/${m}.js`]));
-        const served = spliceHead(html, `<script type="importmap">${JSON.stringify({ imports })}</script>\n  ${ciceroEngine.headHtml('/')}`);
+        const assets = documentAssets();
+        const served = servedHtml(html);
         const missing = new Set();
         const browser = await chromium.launch({ headless: true, args: ARGS });
         chromiumVersion = browser.version();
@@ -69,52 +53,27 @@ export async function print(input, output, options = {}) {
         try {
             step = 'context';
             const context = await browser.newContext({ viewport: VIEWPORT, serviceWorkers: 'block' });
-            await answerFromDisk(context, missing, { root, docPath, served, assets });
+            await routeCompanions(context, missing, assets);
             const page = await context.newPage();
-            page.on('pageerror', (error) => console.warn(`page error: ${error.message}`));
+            await routeDocument(page, missing, { root, docPath, served });
             lap('context');
-            step = 'load';
-            await page.goto(ORIGIN + docPath, { waitUntil: 'load' });
-            lap('load');
-            step = 'cut';
-            const cut = await page.evaluate(cutInPage, { cicero: flags.cicero, measures: options.trace !== undefined });
-            lap('cut');
-            if (!('refused' in cut))
-                trace.cicero = cut.measures;
-            if ('refused' in cut || missing.size)
-                throw refusal(missing, 'refused' in cut ? cut : null);
-            let screens = [];
-            if (flags.beltype.check) {
-                step = 'check';
-                screens = await screenshotPages(page);
-                lap('check');
-            }
-            step = 'print';
-            let bytes;
-            let pages;
-            let words;
-            if (flags.beltype.printer === 'chromium') {
-                const sheet = chromiumSheet(await page.evaluate(pageSizesInPage));
-                await page.evaluate(chromiumSheetInPage, sheet);
-                bytes = await page.pdf({ preferCSSPageSize: true, printBackground: true });
-                pages = await page.locator('beltype-page').count();
-                words = 0;
-                lap('print');
-            }
-            else {
-                const printed = await page.evaluate(printInPage, flags.caster);
-                if ('refused' in printed)
-                    throw refusal(missing, printed);
+            const printed = await printOnPage(page, missing, flags, {
+                docPath,
+                measures: options.trace !== undefined,
+                ...(options.created !== undefined ? { created: options.created } : {}),
+                progress: { step: (name) => { step = name; }, lap, cicero: (measures) => { trace.cicero = measures; } }
+            });
+            if (printed.printMs !== undefined) {
                 trace.process['print'] = round(printed.printMs);
                 trace.process['transfer'] = round(performance.now() - mark - printed.printMs);
                 mark = performance.now();
                 trace.caster = printed.caster;
                 for (const warning of printed.warnings)
                     console.warn(typeof warning === 'string' ? warning : JSON.stringify(warning));
-                bytes = Buffer.from(printed.base64, 'base64');
-                pages = printed.pages;
-                words = printed.words;
             }
+            else
+                lap('print');
+            const { bytes, pages, words, screens } = printed;
             step = 'close';
             await browser.close();
             lap('close');
@@ -177,64 +136,3 @@ function versions(chromiumVersion) {
         chromium: chromiumVersion
     };
 }
-/** The run's refusal: what it could not answer comes first, because a missing file's name says more than the step it broke. */
-function refusal(missing, answer) {
-    if (missing.size)
-        return new BuildError(`beltype print: the document asked for what the run cannot give it, so the print would not be the document:\n${[...missing].map((m) => `  ${m}`).join('\n')}`);
-    return new BuildError(`beltype print: the ${answer?.at ?? 'run'} step refused:\n${answer?.refused || '(the refusal carried no message)'}`);
-}
-/** `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);
-    if (head)
-        return html.slice(0, head.index + head[0].length) + `\n  ${fragment}` + html.slice(head.index + head[0].length);
-    const before = /^\s*(<!doctype[^>]*>\s*)?(<html\b[^>]*>)?/i.exec(html)?.[0] ?? '';
-    return `${before}<head>\n  ${fragment}\n</head>${html.slice(before.length)}`;
-}
-// ponytail: routes only. A dedicated or shared worker's WebSocket and fetches pass no route, so a document that opens one is not refused; the monorepo's `cast` closes that with a proxy the run owns (packages/cli/src/cast.js), to be brought over when a document needs it.
-async function answerFromDisk(context, missing, o) {
-    await context.routeWebSocket(/.*/, (ws) => {
-        missing.add(`${ws.url()} (a WebSocket; print opens none)`);
-        return ws.close({ code: 1008, reason: 'beltype print reaches no network' });
-    });
-    await context.route('**/*', async (route) => {
-        const url = new URL(route.request().url());
-        if (url.origin !== ORIGIN) {
-            missing.add(`${url.href} (another origin; print fetches nothing from a network)`);
-            return route.abort('blockedbyclient');
-        }
-        let pathname;
-        try {
-            pathname = decodeURIComponent(url.pathname);
-        }
-        catch {
-            missing.add(`${url.pathname} (a malformed percent escape, which names no file)`);
-            return route.fulfill({ status: 400, body: '' });
-        }
-        if (url.pathname === o.docPath)
-            return route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body: o.served });
-        const file = pathname.startsWith('/_beltype/') ? fromAssets(o.assets, pathname.slice('/_beltype/'.length)) : within(o.root, `.${pathname}`);
-        if (file)
-            return route.fulfill({ status: 200, path: file, contentType: contentType(file) });
-        if (pathname !== '/favicon.ico')
-            missing.add(pathname.startsWith('/_beltype/') ? `${pathname} (no companion holds it)` : `${pathname} (not in ${o.root})`);
-        return route.fulfill({ status: 404, body: '' });
-    });
-}
-function fromAssets(assets, assetPath) {
-    const file = assets.files[assetPath];
-    if (file)
-        return isFile(file) ? file : null;
-    for (const [prefix, dir] of Object.entries(assets.dirs)) {
-        if (assetPath.startsWith(prefix + '/'))
-            return within(dir, assetPath.slice(prefix.length + 1));
-    }
-    return null;
-}
-/** `rel` under `dir`, if it is a file there and does not climb out. */
-function within(dir, rel) {
-    const file = path.resolve(dir, rel);
-    const inside = path.relative(dir, file);
-    return !inside.startsWith('..') && !path.isAbsolute(inside) && isFile(file) ? file : null;
-}
-const isFile = (file) => fs.existsSync(file) && fs.statSync(file).isFile();

package/dist/src/run.js

@@ -0,0 +1,157 @@
+/**
+ * The steps of a print as functions of a page, so `beltype print` and a server that keeps a browser alive print the same way.
+ *
+ * @remarks
+ * **Every request is answered from disk, on one made-up origin.** {@link routeCompanions} answers on the browser context what no document owns: a WebSocket and another origin are refused and named, `/_beltype/` is answered from the companions' built files. {@link routeDocument} answers on a page the document at its own name and its folder at the root, and lets everything else fall back to the context's routes (Playwright runs a page's routes before its context's). {@link printOnPage} then loads, cuts, screenshots when asked and prints, and throws the refusals `print` has always thrown.
+ *
+ * @packageDocumentation
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ciceroEngine } from '@beltype/cicero/engine';
+import { BuildError } from '@beltype/common/errors';
+import { contentType } from '@beltype/common/mime';
+import { cutInPage, printInPage, pageSizesInPage, chromiumSheetInPage } from './in-page.js';
+import { chromiumSheet } from './chromium.js';
+import { screenshotPages } from './check.js';
+/** `.invalid` is reserved (RFC 2606), so nothing on a network can ever answer it instead. */
+export const ORIGIN = 'https://print.invalid';
+export const VIEWPORT = { width: 1200, height: 1600 };
+/** Deterministic text and timers that run while nobody watches the page. */
+export const ARGS = ['--font-render-hinting=none', '--force-device-scale-factor=1', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows'];
+/** The companions' built folders and files, each folder found from a module it exports: common exports no `package.json`. */
+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) } };
+}
+/** 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) {
+    // Caster's modules import common by its package names, which a page resolves only through an import map.
+    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('/')}`);
+}
+/** `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);
+    if (head)
+        return html.slice(0, head.index + head[0].length) + `\n  ${fragment}` + html.slice(head.index + head[0].length);
+    const before = /^\s*(<!doctype[^>]*>\s*)?(<html\b[^>]*>)?/i.exec(html)?.[0] ?? '';
+    return `${before}<head>\n  ${fragment}\n</head>${html.slice(before.length)}`;
+}
+// ponytail: routes only. A dedicated or shared worker's WebSocket and fetches pass no route, so a document that opens one is not refused; the monorepo's `cast` closes that with a proxy the run owns (packages/cli/src/cast.js), to be brought over when a document needs it.
+/** What no document owns, on the context: refuse a WebSocket or another origin by name, and answer `/_beltype/` from the companions. */
+export async function routeCompanions(context, missing, assets = documentAssets()) {
+    await context.routeWebSocket(/.*/, (ws) => {
+        missing.add(`${ws.url()} (a WebSocket; print opens none)`);
+        return ws.close({ code: 1008, reason: 'beltype print reaches no network' });
+    });
+    await context.route('**/*', async (route) => {
+        const url = new URL(route.request().url());
+        if (url.origin !== ORIGIN) {
+            missing.add(`${url.href} (another origin; print fetches nothing from a network)`);
+            return route.abort('blockedbyclient');
+        }
+        const pathname = decoded(url, missing);
+        if (pathname === null)
+            return route.fulfill({ status: 400, body: '' });
+        const file = pathname.startsWith('/_beltype/') ? fromAssets(assets, pathname.slice('/_beltype/'.length)) : null;
+        if (file)
+            return route.fulfill({ status: 200, path: file, contentType: contentType(file) });
+        missing.add(`${pathname} (${pathname.startsWith('/_beltype/') ? 'no companion holds it' : 'no document answered it'})`);
+        return route.fulfill({ status: 404, body: '' });
+    });
+}
+/** The document's own files on a page: the document at `docPath`, its folder `root` at the root. Another origin and `/_beltype/` fall back to the context's routes. */
+export async function routeDocument(page, missing, o) {
+    await page.route('**/*', async (route) => {
+        const url = new URL(route.request().url());
+        if (url.origin !== ORIGIN)
+            return route.fallback();
+        const pathname = decoded(url, missing);
+        if (pathname === null)
+            return route.fulfill({ status: 400, body: '' });
+        if (pathname.startsWith('/_beltype/'))
+            return route.fallback();
+        if (url.pathname === o.docPath)
+            return route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body: o.served });
+        const file = within(o.root, `.${pathname}`);
+        if (file)
+            return route.fulfill({ status: 200, path: file, contentType: contentType(file) });
+        if (pathname !== '/favicon.ico')
+            missing.add(`${pathname} (not in ${o.root})`);
+        return route.fulfill({ status: 404, body: '' });
+    });
+}
+/**
+ * Load the document on `page`, cut it, screenshot its pages when `--check` asks, and print it under the flags' printer.
+ *
+ * @remarks
+ * What the run could not answer after the print (`missing`) is the caller's to test with {@link refusal}: `print` tests it after closing the browser, as it always has.
+ * @throws {BuildError} where the cut or the print refused, or the document asked for what the run could not give it.
+ */
+export async function printOnPage(page, missing, flags, o) {
+    const { progress } = o;
+    page.on('pageerror', (error) => console.warn(`page error: ${error.message}`));
+    progress?.step('load');
+    await page.goto(ORIGIN + o.docPath, { waitUntil: 'load' });
+    progress?.lap('load');
+    progress?.step('cut');
+    const cut = await page.evaluate(cutInPage, { cicero: flags.cicero, measures: o.measures === true });
+    progress?.lap('cut');
+    const measures = 'refused' in cut ? [] : cut.measures;
+    progress?.cicero?.(measures);
+    if ('refused' in cut || missing.size)
+        throw refusal(missing, 'refused' in cut ? cut : null);
+    let screens = [];
+    if (flags.beltype.check) {
+        progress?.step('check');
+        screens = await screenshotPages(page);
+        progress?.lap('check');
+    }
+    progress?.step('print');
+    if (flags.beltype.printer === 'chromium') {
+        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 };
+    }
+    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 };
+}
+/** 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) {
+    if (missing.size)
+        return new BuildError(`beltype print: the document asked for what the run cannot give it, so the print would not be the document:\n${[...missing].map((m) => `  ${m}`).join('\n')}`);
+    return new BuildError(`beltype print: the ${answer?.at ?? 'run'} step refused:\n${answer?.refused || '(the refusal carried no message)'}`);
+}
+/** The percent-decoded path of `url`, or null (and the name of what it asked) where the escape is malformed. */
+function decoded(url, missing) {
+    try {
+        return decodeURIComponent(url.pathname);
+    }
+    catch {
+        missing.add(`${url.pathname} (a malformed percent escape, which names no file)`);
+        return null;
+    }
+}
+function fromAssets(assets, assetPath) {
+    const file = assets.files[assetPath];
+    if (file)
+        return isFile(file) ? file : null;
+    for (const [prefix, dir] of Object.entries(assets.dirs)) {
+        if (assetPath.startsWith(prefix + '/'))
+            return within(dir, assetPath.slice(prefix.length + 1));
+    }
+    return null;
+}
+/** `rel` under `dir`, if it is a file there and does not climb out. */
+function within(dir, rel) {
+    const file = path.resolve(dir, rel);
+    const inside = path.relative(dir, file);
+    return !inside.startsWith('..') && !path.isAbsolute(inside) && isFile(file) ? file : null;
+}
+const isFile = (file) => fs.existsSync(file) && fs.statSync(file).isFile();

package/dist/src/serve.js

@@ -0,0 +1,272 @@
+/**
+ * `beltype serve`: `beltype print` behind an HTTP door, with one Chromium kept warm, as Gotenberg does.
+ *
+ * @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 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 fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+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';
+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');
+window.sw = new SharedWorker(c.formeSharedWorkerUrl(), { type: 'module', name: 'forme' });
+</script></body></html>`;
+// Run from src/ or from dist/src/: the package root is the first folder up that holds `assets`.
+const WARMUP_FONT = [1, 2].map((up) => fileURLToPath(new URL(`${'../'.repeat(up)}assets/warmup/SourceSans3-Variable.woff2`, import.meta.url))).find((f) => fs.existsSync(f));
+const WORDS = 'the quick brown fox jumps over a lazy dog while leaf litter decomposes along an altitudinal gradient and soil carbon settles slowly beneath the canopy of old beech and spruce'.split(' ');
+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. */
+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>`;
+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 assets = documentAssets();
+    const missing = new Set();
+    let browser = null;
+    let context = null;
+    let version = 'unknown';
+    let restarting = false;
+    let needsRestart = false;
+    let prints = 0;
+    let sinceStart = 0;
+    let queued = 0;
+    let tail = Promise.resolve();
+    const stopBrowser = async () => {
+        const old = browser;
+        browser = context = null;
+        await old?.close().catch(() => { });
+    };
+    /** Run `html` and `files` through the print's road on a new page; the folder and the page are gone after. */
+    const render = async (files, given, created) => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'beltype-serve-'));
+        try {
+            for (const [name, bytes] of files) {
+                const file = path.join(root, ...name.split('/'));
+                fs.mkdirSync(path.dirname(file), { recursive: true });
+                fs.writeFileSync(file, bytes);
+            }
+            const flags = { caster: given.caster, cicero: ciceroFlags.resolve(given.cicero), beltype: cliFlags.resolve(given.beltype) };
+            const docPath = '/index.html';
+            const served = servedHtml(Buffer.from(files.get('index.html')).toString('utf8'));
+            missing.clear();
+            const page = await context.newPage();
+            try {
+                await routeDocument(page, missing, { root, docPath, served });
+                const printed = await printOnPage(page, missing, flags, { docPath, sharedWriter: true, ...(created !== undefined ? { created } : {}) });
+                if (missing.size)
+                    throw refusal(missing, null);
+                return printed;
+            }
+            finally {
+                await page.close().catch(() => { });
+            }
+        }
+        finally {
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+    };
+    const start = async () => {
+        browser = await chromium.launch({ headless: true, args: ARGS });
+        const mine = browser;
+        version = mine.version();
+        mine.on('disconnected', () => { if (browser === mine)
+            needsRestart = true; });
+        options.onBrowser?.(mine);
+        context = await mine.newContext({ viewport: VIEWPORT, serviceWorkers: 'block' });
+        await routeCompanions(context, missing, assets);
+        // Registered after the companions' routes, so it runs first.
+        await context.route(ORIGIN + HOLDER_PATH, (route) => route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body: servedHtml(HOLDER) }));
+        const holder = await context.newPage();
+        await holder.goto(ORIGIN + HOLDER_PATH, { waitUntil: 'load' });
+        await holder.waitForFunction(() => window.sw !== undefined);
+        const given = await parseFlagArgs(['caster.writer=forme']);
+        for (const n of [1, 2]) {
+            const printed = await render(new Map([['index.html', Buffer.from(WARMUP)], ['warm.woff2', fs.readFileSync(WARMUP_FONT)]]), given, undefined);
+            log(`beltype serve: warm-up ${n}: ${printed.pages} pages, forme write ${printed.caster?.ms['emit'] ?? '?'} ms`);
+        }
+        needsRestart = false;
+        sinceStart = 0;
+    };
+    const restart = async () => {
+        restarting = true;
+        try {
+            await stopBrowser();
+            log('beltype serve: restarting the browser');
+            await start();
+        }
+        catch (error) {
+            needsRestart = true;
+            throw error;
+        }
+        finally {
+            restarting = false;
+        }
+    };
+    /** Runs `job` after every earlier job and after any restart it needs; the restart a job asks for happens before the next one. */
+    const enqueue = (job) => {
+        queued++;
+        const result = tail.then(async () => {
+            queued--;
+            if (needsRestart || sinceStart >= options.restartAfter)
+                await restart();
+            return job();
+        });
+        tail = result.then(async () => { if (needsRestart || sinceStart >= options.restartAfter)
+            await restart(); }).catch(() => { });
+        return result;
+    };
+    await start();
+    const print = async (req) => {
+        const form = await readForm(req, options.maxUpload);
+        const files = new Map();
+        const args = [];
+        let created;
+        for (const [name, value] of form.entries()) {
+            if (typeof value !== 'string') {
+                files.set(plainName(name), new Uint8Array(await value.arrayBuffer()));
+            }
+            else if (name === 'created') {
+                created = instant(value);
+            }
+            else {
+                if (name === 'beltype.check')
+                    throw new ValidationError('beltype serve: beltype.check is refused; the server writes no files of its own.');
+                args.push(`${name}=${value}`);
+            }
+        }
+        if (!files.has('index.html'))
+            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 run = render(files, given, created);
+            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)`);
+                return { bytes: printed.bytes, printed, writer };
+            }
+            catch (error) {
+                prints++;
+                sinceStart++;
+                run.catch(() => { });
+                if (!(error instanceof BuildError) && !(error instanceof HttpError))
+                    needsRestart = true;
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        });
+    };
+    const server = http.createServer(async (req, res) => {
+        const send = (status, type, body, headers = {}) => {
+            res.writeHead(status, { 'content-type': type, ...headers });
+            res.end(body);
+        };
+        const text = (status, message) => send(status, 'text/plain; charset=utf-8', message + '\n');
+        try {
+            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 (req.method !== 'POST')
+                return text(405, 'beltype serve: /print takes POST.');
+            const { bytes, printed, writer } = await 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 });
+        }
+        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' });
+                res.end(message + '\n', () => {
+                    req.resume();
+                    setTimeout(() => req.destroy(), 1000).unref();
+                });
+            }
+            else if (!res.headersSent)
+                text(status, message);
+        }
+    });
+    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}`;
+    log(`beltype serve: listening on ${url}`);
+    return {
+        url,
+        async close() {
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+            await tail;
+            await stopBrowser();
+        }
+    };
+}
+/** 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 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}.`);
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > limit)
+            throw new HttpError(413, `beltype serve: the upload is over the limit of ${limit} bytes.`);
+        chunks.push(chunk);
+    }
+    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();
+    }
+    catch {
+        throw new ValidationError('beltype serve: the body is not a well-formed multipart/form-data.');
+    }
+}
+/** A file's name as a path relative to the document: plain segments joined by `/`. @throws {ValidationError} where it is absolute, climbs out or is not a plain name. */
+function plainName(name) {
+    const segments = name.split('/');
+    if (!name || segments.some((s) => s === '' || s === '.' || s === '..' || /[\\\0:]/.test(s)))
+        throw new ValidationError(`beltype serve: the file name "${name}" is not a plain relative path with / separators (no absolute path, no "..").`);
+    return name;
+}
+/** An ISO 8601 instant, normalised. @throws {ValidationError} */
+function instant(value) {
+    const date = new Date(value);
+    if (!/^\d{4}-\d\d-\d\dT/.test(value) || Number.isNaN(date.getTime()))
+        throw new ValidationError(`beltype serve: created is an ISO 8601 instant; got "${value}".`);
+    return date.toISOString();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beltype/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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",
@@ -13,10 +13,11 @@
     "node": ">=22"
   },
   "bin": {
-    "beltype": "./dist/src/cli.js"
+    "beltype": "dist/src/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "assets"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -32,7 +33,7 @@
     ]
   },
   "dependencies": {
-    "@beltype/caster": "0.1.5",
+    "@beltype/caster": "0.1.6",
     "@beltype/cicero": "0.1.5",
     "@beltype/common": "0.1.2",
     "mupdf": "1.28.1",