fullbleed 0.1.5 → 0.2.0

package/README.md

@@ -5,10 +5,10 @@ Fullbleed Rust engine compiled to WebAssembly and four font faces, so installing
 it does not require Python, Rust, a browser, or system fonts. MIT licensed.
 
 This is an optional integration around the published **Fullbleed 2.5.8** engine.
-The Node package has its own version, **0.1.5**. Normal text now selects a custom
-family's regular face even when its italic face is supplied first. Review saved
-PDF baselines when upgrading: affected documents can change appearance and line
-breaks. See the [font-family checks](https://github.com/fullbleed-engine/fullbleed-node/blob/main/docs/font-families.md) and
+The Node package has its own version, **0.2.0**. It adds optional process isolation
+for server applications. The engine and default worker mode are unchanged from
+0.1.5. See the [process isolation guide](docs/process-isolation.md),
+[font-family checks](https://github.com/fullbleed-engine/fullbleed-node/blob/main/docs/font-families.md), and
 [embedded-font checks](https://github.com/fullbleed-engine/fullbleed-node/blob/main/docs/font-subsets.md) for the retained fixtures.
 
 ## Install and render
@@ -19,9 +19,9 @@ Use Node.js 22 or newer. Install the [npm package](https://www.npmjs.com/package
 npm install fullbleed
 ```
 
-For a version-pinned installation, use `npm install --save-exact fullbleed@0.1.5`.
-Release verification compares the npm tarball with the checked
-[GitHub release](https://github.com/fullbleed-engine/fullbleed-node/releases/tag/v0.1.5).
+For a version-pinned installation, use `npm install --save-exact fullbleed@0.2.0`.
+Package archives and retained PDF/PNG evidence are attached to each
+[GitHub release](https://github.com/fullbleed-engine/fullbleed-node/releases).
 See the [installation verification records](https://github.com/fullbleed-engine/fullbleed-node/tree/main/verification).
 
 Save this as `invoice.mjs` and run `node invoice.mjs`:
@@ -121,6 +121,7 @@ native engine.
 | `maxPages` | Reject larger documents. Default: 1000. |
 | `timeoutMs` | Deadline including initial engine loading. Default: 30000 ms. |
 | `signal` | An `AbortSignal` to cancel rendering. |
+| `isolation` | `'worker'` (default) or `'process'` for a separate Node process per call. |
 | `allowMissingGlyphs` | Default `false`: reject engine-reported missing glyphs. |
 
 Rendering runs in a dedicated worker. Concurrent calls use separate workers and
@@ -129,6 +130,13 @@ render failure, timeout, or cancellation. Awaiting jobs in sequence therefore
 does not overlap their worker lifetimes. A timeout or abort starts termination;
 settlement includes the time needed to stop the worker.
 
+Use `isolation: 'process'` when a render-process failure should become a rejected
+request while the calling application stays running. This mode runs the engine
+and its worker in a fresh Node process, and waits for process exit and IPC
+disconnection before settling. It requires a host that permits child processes
+and adds startup and memory overhead. It does not pool processes or retry jobs.
+See the [guide and failure checks](docs/process-isolation.md).
+
 Bound concurrency in a server according to its available memory;
 each worker's WebAssembly memory has a 512 MiB ceiling. HTML and CSS together are
 limited to 4,000,000 UTF-8 bytes; supplied fonts and assets together to 64 MiB.
@@ -142,6 +150,7 @@ try {
     html: '<h1>Monthly statement</h1>',
     maxPages: 20,
     timeoutMs: 10_000,
+    isolation: 'process',
     signal: AbortSignal.timeout(8_000),
   });
   // Return result.pdf from your HTTP handler, or write it to your storage.
@@ -153,8 +162,9 @@ try {
 
 Error codes include `INVALID_INPUT`, `MISSING_GLYPHS`, `PAGE_LIMIT`, `TIMEOUT`,
 `ABORTED`, `ENGINE_LOAD_FAILED`, `ENGINE_LIMIT`, `RENDER_FAILED`,
-`PREVIEW_FAILED`, and `WORKER_FAILED`. Failed or cancelled calls do not return a
-partial PDF. Caller-owned asset buffers are copied when a call starts.
+`PREVIEW_FAILED`, `WORKER_FAILED`, and `PROCESS_FAILED`. Process failures may also
+include `exitCode` and `signal`. Failed or cancelled calls do not return a partial
+PDF. Caller-owned asset buffers are copied when a call starts.
 
 This API covers ordinary document generation and previews. It does not expose
 PDF/A, PDF/UA, PDF/X, template overlays, or compiled VDP. Use the
@@ -199,7 +209,8 @@ the previous public npm release.
 An intermittent process crash observed on Linux with Node 24.21.0 remains under
 investigation in [issue #7](https://github.com/fullbleed-engine/fullbleed-node/issues/7).
 Version 0.1.3 fixes worker shutdown timing, but does not establish that this crash
-is resolved. See the [runtime investigation and diagnostic](docs/runtime-diagnostics.md)
+is resolved. Version 0.2.0 adds optional process fault containment; it does not
+claim to fix the native crash. See the [runtime investigation and diagnostic](docs/runtime-diagnostics.md)
 for the observed scope, retained results, and a synthetic reproducer.
 
 ## License and support

package/dist/build.json

@@ -1,5 +1,5 @@
 {
-  "packageVersion": "0.1.5",
+  "packageVersion": "0.2.0",
   "engineVersion": "2.5.8",
   "engineSource": "https://crates.io/crates/fullbleed/2.5.8",
   "target": "wasm32-wasip1",
@@ -45,7 +45,7 @@
   "files": {
     "dist/engine.wasm": {
       "bytes": 5069661,
-      "sha256": "e95cc9132029b9c42ad684d898063b4efc043fa0b7b9fe2e7867f3eb3a17ef58"
+      "sha256": "2f41ac7c2d85f7724166ea0d466cc55b6d6f5ca0014014d667f54f7ac93577cb"
     },
     "dist/THIRD_PARTY_NOTICES.txt": {
       "bytes": 57660,

package/dist/index.d.cts

@@ -17,6 +17,8 @@ export interface RenderOptions {
   /** Default false: missing glyphs reject the job instead of silently emitting them. */
   allowMissingGlyphs?: boolean;
   signal?: AbortSignal;
+  /** Default: worker. Process starts a fresh Node child and waits for its exit. */
+  isolation?: 'worker' | 'process';
 }
 
 export interface RenderResult {
@@ -29,6 +31,9 @@ export interface RenderResult {
 
 export class FullbleedError extends Error {
   readonly code: string;
+  /** Present on PROCESS_FAILED errors after the child closes. */
+  readonly exitCode?: number | null;
+  readonly signal?: NodeJS.Signals | null;
   constructor(code: string, message: string, options?: ErrorOptions);
 }
 export function renderPdf(options: RenderOptions): Promise<RenderResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullbleed",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Generate PDFs from HTML and CSS in Node.js with the Fullbleed Rust engine, bundled fonts, and optional PNG previews.",
   "type": "module",
   "main": "./src/index.cjs",

package/src/index.cjs

@@ -4,6 +4,7 @@ const { readFile } = require('node:fs/promises');
 const { createHash } = require('node:crypto');
 const { join } = require('node:path');
 const { Worker } = require('node:worker_threads');
+const { fork } = require('node:child_process');
 const { pathToFileURL } = require('node:url');
 const pkg = require('../package.json');
 
@@ -45,9 +46,9 @@ function runtime() {
 
 function normalize(options) {
   if (!options || typeof options !== 'object' || Array.isArray(options)) invalid('Pass an options object with an html string.');
-  const supported = new Set(['html', 'css', 'fonts', 'assets', 'previewDpi', 'timeoutMs', 'maxPages', 'allowMissingGlyphs', 'signal']);
+  const supported = new Set(['html', 'css', 'fonts', 'assets', 'previewDpi', 'timeoutMs', 'maxPages', 'allowMissingGlyphs', 'signal', 'isolation']);
   for (const key of Object.keys(options)) if (!supported.has(key)) invalid(`Unknown option: ${key}`);
-  const { html, css = '', fonts = [], assets = {}, previewDpi = 0, timeoutMs = 30000, maxPages = 1000, allowMissingGlyphs = false, signal } = options;
+  const { html, css = '', fonts = [], assets = {}, previewDpi = 0, timeoutMs = 30000, maxPages = 1000, allowMissingGlyphs = false, signal, isolation = 'worker' } = options;
   if (typeof html !== 'string' || !html.trim()) invalid('html must be a nonempty string.');
   if (typeof css !== 'string') invalid('css must be a string.');
   if (Buffer.byteLength(html) + Buffer.byteLength(css) > sourceLimit) invalid('HTML and CSS together must not exceed 4,000,000 UTF-8 bytes.');
@@ -56,6 +57,7 @@ function normalize(options) {
   if (!Number.isSafeInteger(maxPages) || maxPages < 1) invalid('maxPages must be a positive integer.');
   if (typeof allowMissingGlyphs !== 'boolean') invalid('allowMissingGlyphs must be a boolean.');
   if (signal !== undefined && !(signal instanceof AbortSignal)) invalid('signal must be an AbortSignal.');
+  if (isolation !== 'worker' && isolation !== 'process') invalid('isolation must be worker or process.');
   if (!Array.isArray(fonts)) invalid('fonts must be an array of font byte arrays.');
   if (!assets || typeof assets !== 'object' || Array.isArray(assets)) invalid('assets must map relative names to byte arrays.');
   let assetBytes = 0;
@@ -74,7 +76,124 @@ function normalize(options) {
     for (let i = 1; i < segments.length; i++) if (fileNames.has(segments.slice(0, i).join('/'))) invalid(`Asset is both a file and a directory: ${name}`);
     return { name: 'assets/' + name, data: bytes(assets[name], `assets[${name}]`) };
   });
-  return { html, css: 'body { font-family: Inter; }\n' + css, customFonts, assetFiles, previewDpi, timeoutMs, maxPages, allowMissingGlyphs, signal };
+  return { html, css, customFonts, assetFiles, previewDpi, timeoutMs, maxPages, allowMissingGlyphs, signal, isolation };
+}
+
+function renderProcess(job, remaining) {
+  return new Promise((resolve, reject) => {
+    let child, timer, closed = false, failure, reply, exited, disconnected = false;
+    const timeout = () => new FullbleedError('TIMEOUT', `PDF rendering exceeded ${job.timeoutMs} ms.`);
+    const cleanup = () => {
+      clearTimeout(timer);
+      job.signal?.removeEventListener('abort', abort);
+    };
+    const stop = error => {
+      if (closed || failure) return;
+      failure = error;
+      // Cancellation can occur synchronously inside fork instrumentation. Wait
+      // until the returned process handle has been assigned before killing it.
+      queueMicrotask(() => {
+        if (!closed && child?.pid) child.kill('SIGKILL');
+      });
+    };
+    const abort = () => stop(new FullbleedError('ABORTED', 'PDF rendering was aborted.'));
+    timer = setTimeout(() => stop(timeout()), remaining);
+    job.signal?.addEventListener('abort', abort, { once: true });
+    if (job.signal?.aborted) {
+      cleanup();
+      reject(new FullbleedError('ABORTED', 'PDF rendering was aborted.'));
+      return;
+    }
+    try {
+      const env = { ...process.env };
+      // The bundled child needs no application preloads, inspector, eval script,
+      // or custom loader. Avoid replaying them in a fresh application process.
+      for (const key of Object.keys(env)) if (key.toUpperCase() === 'NODE_OPTIONS') delete env[key];
+      child = fork(join(__dirname, 'process-worker.cjs'), [], {
+        execPath: process.execPath, execArgv: [], env,
+        serialization: 'advanced', stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+        windowsHide: true,
+      });
+      child.on('error', cause => stop(new FullbleedError('PROCESS_FAILED', 'The rendering process failed.', { cause })));
+      child.on('message', message => {
+        if (reply || message?.type !== 'result' || typeof message.ok !== 'boolean') {
+          stop(new FullbleedError('PROCESS_FAILED', 'The rendering process returned an invalid response.'));
+          return;
+        }
+        const result = message.result;
+        if (message.ok
+          ? !(result?.pdf instanceof Uint8Array) || Buffer.from(result.pdf.subarray(0, 5)).toString() !== '%PDF-'
+            || !Number.isSafeInteger(result.pages) || result.pages < 1 || result.pages > job.maxPages
+            || !Array.isArray(result.previews) || result.previews.length !== (job.previewDpi ? result.pages : 0)
+            || !Array.from(result.previews).every(bytes => bytes instanceof Uint8Array
+              && Buffer.from(bytes.subarray(0, 8)).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+            || !Number.isSafeInteger(result.missingGlyphs) || result.missingGlyphs < 0
+            || result.engineVersion !== pkg.fullbleed.engineVersion
+          : typeof message.code !== 'string' || typeof message.message !== 'string') {
+          stop(new FullbleedError('PROCESS_FAILED', 'The rendering process returned an invalid result.'));
+          return;
+        }
+        reply = message;
+      });
+      const finish = (code, signal) => {
+        if (closed) return;
+        closed = true;
+        cleanup();
+        // Receiving PDF bytes is insufficient: a native crash during shutdown
+        // must reject the request, even if its result was sent before the crash.
+        if (!failure && (code !== 0 || signal || !reply)) {
+          failure = new FullbleedError('PROCESS_FAILED',
+            `Rendering process exited without completing successfully (code ${code}, signal ${signal ?? 'none'}).`);
+        }
+        if (failure) {
+          if (failure.code === 'PROCESS_FAILED') {
+            failure.exitCode = code;
+            failure.signal = signal;
+          }
+          reject(failure);
+        } else if (!reply.ok) {
+          reject(new FullbleedError(reply.code, reply.message));
+        } else {
+          const result = reply.result;
+          resolve({ pdf: Buffer.from(result.pdf), previews: result.previews.map(bytes => Buffer.from(bytes)),
+            pages: result.pages, missingGlyphs: result.missingGlyphs, engineVersion: result.engineVersion });
+        }
+      };
+      // All stdio is ignored except IPC. Waiting for both exit and disconnect
+      // drains messages and proves the process has stopped. On Windows, an
+      // interrupted IPC write can omit 'close' even after both these events.
+      child.once('exit', (code, signal) => {
+        exited = { code, signal };
+        if (disconnected) finish(code, signal);
+      });
+      child.once('disconnect', () => {
+        disconnected = true;
+        if (exited) finish(exited.code, exited.signal);
+      });
+      // A spawn error emits close without exit.
+      child.once('close', finish);
+      if (failure || job.signal?.aborted) {
+        if (!failure) abort();
+        return;
+      }
+      child.send({ type: 'render', options: {
+        html: job.html, css: job.css, fonts: job.customFonts.map(font => font.data),
+        assets: Object.fromEntries(job.assetFiles.map(file => [file.name.slice('assets/'.length), file.data])),
+        previewDpi: job.previewDpi, maxPages: job.maxPages, allowMissingGlyphs: job.allowMissingGlyphs,
+        timeoutMs: remaining,
+      } }, error => {
+        if (error) stop(new FullbleedError('PROCESS_FAILED', 'Could not send the rendering request.', { cause: error }));
+      });
+    } catch (cause) {
+      if (child) {
+        stop(new FullbleedError('PROCESS_FAILED', 'Could not start the rendering request.', { cause }));
+      } else {
+        closed = true;
+        cleanup();
+        reject(new FullbleedError('PROCESS_FAILED', 'Could not start the rendering process.', { cause }));
+      }
+    }
+  });
 }
 
 async function renderPdf(options) {
@@ -85,6 +204,7 @@ async function renderPdf(options) {
   if (job.signal?.aborted) throw aborted();
   const remaining = job.timeoutMs - (Date.now() - start);
   if (remaining <= 0) throw new FullbleedError('TIMEOUT', `PDF rendering exceeded ${job.timeoutMs} ms.`);
+  if (job.isolation === 'process') return renderProcess(job, remaining);
   return new Promise((resolve, reject) => {
     let worker, timer, settled = false;
     const finish = async (error, result) => {
@@ -116,7 +236,7 @@ async function renderPdf(options) {
         eval: true,
         workerData: {
           module: loaded.module, fonts: [...loaded.fonts, ...job.customFonts], assets: job.assetFiles,
-          html: job.html, css: job.css, previewDpi: job.previewDpi, maxPages: job.maxPages,
+          html: job.html, css: 'body { font-family: Inter; }\n' + job.css, previewDpi: job.previewDpi, maxPages: job.maxPages,
           allowMissingGlyphs: job.allowMissingGlyphs,
         },
       });

package/src/index.d.ts

@@ -17,6 +17,8 @@ export interface RenderOptions {
   /** Default false: missing glyphs reject the job instead of silently emitting them. */
   allowMissingGlyphs?: boolean;
   signal?: AbortSignal;
+  /** Default: worker. Process starts a fresh Node child and waits for its exit. */
+  isolation?: 'worker' | 'process';
 }
 
 export interface RenderResult {
@@ -29,6 +31,9 @@ export interface RenderResult {
 
 export class FullbleedError extends Error {
   readonly code: string;
+  /** Present on PROCESS_FAILED errors after the child closes. */
+  readonly exitCode?: number | null;
+  readonly signal?: NodeJS.Signals | null;
   constructor(code: string, message: string, options?: ErrorOptions);
 }
 export function renderPdf(options: RenderOptions): Promise<RenderResult>;

package/src/process-worker.cjs

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+'use strict';
+const { renderPdf } = require('./index.cjs');
+const controller = new AbortController();
+process.once('disconnect', () => controller.abort());
+process.once('message', async message => {
+  let reply;
+  try {
+    if (message?.type !== 'render') throw new Error('Invalid render request.');
+    const result = await renderPdf({ ...message.options, isolation: 'worker', signal: controller.signal });
+    reply = { type: 'result', ok: true, result };
+  } catch (error) {
+    reply = { type: 'result', ok: false, code: error.code ?? 'RENDER_FAILED', message: error.message };
+  }
+  if (!process.connected) return;
+  process.send(reply, error => {
+    if (error) process.exitCode = 1;
+    if (process.connected) process.disconnect();
+  });
+});