@beltype/cli 0.1.5 → 0.1.6

package/README.md

@@ -36,6 +36,7 @@ curl -F index.html=@index.html -F paper.css=@paper.css -F fonts/a.woff2=@fonts/a
 - `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).
+- A document whose text holds no `<script`, `<iframe`, `<object`, `<embed`, `<frame`, `<portal`, `javascript:` or `on…=` attribute is printed on one kept page, re-seated for each print as Caster's kept frame is (`document.open()` keeps the realm, so Caster's registry and the companions' modules stay warm); any other document gets a page of its own, because a script's timers, listeners and globals would outlive it on a kept `Window`. The log line of each print names the road (`road kept` or `road fresh`) and the time of every step. A print that fails or times out closes the kept page.
 - 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/`.
 

package/dist/src/in-page.js

@@ -70,3 +70,18 @@ export function chromiumSheetInPage(sheet) {
     shadow.textContent = sheet.shadow;
     document.querySelector('beltype-root')?.shadowRoot?.appendChild(shadow);
 }
+/**
+ * Seat `html` as the page's document without a navigation: `document.open()` keeps the `Window`, so the realm Caster measures from, its modules and its capability registry stay (Caster's DESIGN.md S87, S89). The `adoptedStyleSheets` the last document left on the Document are emptied; `load` is awaited as a navigation's would be.
+ *
+ * @remarks
+ * The previous Cicero client is released first (`release()`, Cicero 0.1.6, SPEC XII.7): the `Window` and its one `FontFaceSet` outlive `document.open()`, and an unreleased client heard a face of the next document's family arrive as a late fact and ran beside the host's run, which was let go after one page (measured: the paper after a document of another family cut 1 page, not 4). A released client deletes its handle, so the next document's module scripts must load under a URL of their own, which `serve.ts` keys per re-seat.
+ */
+export async function reseatInPage(html) {
+    await window.__beltypeCicero?.release?.();
+    document.open();
+    document.adoptedStyleSheets = [];
+    const loaded = new Promise((resolve) => window.addEventListener('load', () => resolve(), { once: true }));
+    document.write(html);
+    document.close();
+    await loaded;
+}

package/dist/src/run.js

@@ -12,7 +12,7 @@ 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 { cutInPage, printInPage, reseatInPage, 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. */
@@ -93,9 +93,13 @@ export async function routeDocument(page, missing, o) {
  */
 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' });
+    if (o.reseat !== undefined)
+        await page.evaluate(reseatInPage, o.reseat);
+    else {
+        page.on('pageerror', (error) => console.warn(`page error: ${error.message}`));
+        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 });

package/dist/src/serve.js

@@ -4,6 +4,8 @@
  * @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 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
@@ -24,11 +26,19 @@ 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));
+export 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>`;
+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>`;
+const DOC_PATH = '/index.html';
+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);
 class HttpError extends Error {
     status;
     constructor(status, message) { super(message); this.status = status; }
@@ -37,6 +47,8 @@ export async function serve(options) {
     const log = options.log ?? ((line) => console.log(line));
     const assets = documentAssets();
     const missing = new Set();
+    let kept = null;
+    let reseats = 0;
     let browser = null;
     let context = null;
     let version = 'unknown';
@@ -48,11 +60,25 @@ export async function serve(options) {
     let tail = Promise.resolve();
     const stopBrowser = async () => {
         const old = browser;
-        browser = context = null;
+        browser = context = kept = 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) => {
+    /** The kept page, opened on a blank document at the document's own path so that relative references resolve as a print's would. */
+    const openKept = async () => {
+        const page = await context.newPage();
+        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' });
+        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;
+        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-'));
         try {
             for (const [name, bytes] of files) {
@@ -61,19 +87,34 @@ export async function serve(options) {
                 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'));
+            const author = Buffer.from(files.get('index.html')).toString('utf8');
+            const served = servedHtml(author);
+            const keep = keptRoad(author);
+            trace.road = keep ? 'kept' : 'fresh';
             missing.clear();
-            const page = await context.newPage();
+            const lapped = lapper(trace.ms);
+            lapped.start('page');
+            const page = keep ? (kept ?? await openKept()) : 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 (keep)
+                    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 } : {}) });
+                lapped.end('print');
                 if (missing.size)
                     throw refusal(missing, null);
+                if (!keep) {
+                    lapped.start('close');
+                    await closePage(page);
+                    lapped.end('close');
+                }
                 return printed;
             }
-            finally {
-                await page.close().catch(() => { });
+            catch (error) {
+                await closePage(page);
+                throw error;
             }
         }
         finally {
@@ -94,6 +135,7 @@ export async function serve(options) {
         const holder = await context.newPage();
         await holder.goto(ORIGIN + HOLDER_PATH, { waitUntil: 'load' });
         await holder.waitForFunction(() => window.sw !== undefined);
+        await openKept();
         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);
@@ -158,7 +200,8 @@ export async function serve(options) {
             const id = prints + 1;
             log(`beltype serve: print ${id} started`);
             const t0 = performance.now();
-            const run = render(files, given, created);
+            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 {
@@ -166,12 +209,15 @@ export async function serve(options) {
                 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)
+                    await closePage(kept);
                 if (!(error instanceof BuildError) && !(error instanceof HttpError))
                     needsRestart = true;
                 throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beltype/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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",
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@beltype/caster": "0.1.6",
-    "@beltype/cicero": "0.1.5",
+    "@beltype/cicero": "0.1.6",
     "@beltype/common": "0.1.2",
     "mupdf": "1.28.1",
     "playwright-core": "1.63.0"