@jwilleke/ngdpbase-types 5.26.0 → 5.28.0

package/lib/src/export/pdfEngine.d.ts

@@ -0,0 +1,113 @@
+/** Page sizes Chromium knows by name. */
+export declare const PDF_PAGE_SIZES: readonly ["Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A4", "A5", "A6"];
+export type PdfPageSize = (typeof PDF_PAGE_SIZES)[number];
+export interface PdfMargin {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+}
+/**
+ * What a caller may set. An `@page` rule in the HTML (size, margin) wins over
+ * these, as it does when a browser prints.
+ */
+export interface PdfOptions {
+    /** Page size; default `ngdpbase.export.pdf.page-size`. */
+    format?: PdfPageSize;
+    /** Page margins, each a CSS length (`'20mm'`, `'0.5in'`); default none. */
+    margin?: PdfMargin;
+    /** Print background colours and images; default `true`. */
+    printBackground?: boolean;
+}
+/** Options after validation and defaults. */
+export interface ResolvedPdfOptions {
+    format: PdfPageSize;
+    margin: PdfMargin;
+    printBackground: boolean;
+}
+/** One local Chromium render, as the child receives it. */
+export interface PdfJob {
+    kind: 'render';
+    html: string;
+    executablePath: string;
+    options: ResolvedPdfOptions;
+    timeoutMs: number;
+}
+/** A PDF made elsewhere, to normalise in the child. */
+export interface PdfNormalizeJob {
+    kind: 'normalize';
+    pdf: Uint8Array;
+    timeoutMs: number;
+}
+/** Anything the child is asked to do. */
+export type PdfChildJob = PdfJob | PdfNormalizeJob;
+/** What the child sends back. `launch` means Chromium could not start: the engine is unavailable. */
+export type PdfJobResult = {
+    ok: true;
+    pdf: Uint8Array;
+} | {
+    ok: false;
+    stage: 'launch' | 'render';
+    error: string;
+};
+/**
+ * No PDF engine: `playwright-core` is not installed, no Chromium was found, or
+ * it could not start. An add-on catches it by `code` (it cannot import core
+ * values) and falls back to HTML.
+ */
+export declare class PdfUnavailableError extends Error {
+    readonly code = "PDF_UNAVAILABLE";
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Validate a caller's options and fill the defaults. Throws on anything
+ * Chromium would misread, so a typo is an error rather than a different page.
+ *
+ * @param options - The caller's options
+ * @param defaultFormat - `ngdpbase.export.pdf.page-size`
+ */
+export declare function resolvePdfOptions(options: PdfOptions | undefined, defaultFormat: string): ResolvedPdfOptions;
+/** Where Chromium or Chrome usually is, per platform. Checked after the configured path and Playwright's own. */
+export declare const SYSTEM_CHROMIUM_PATHS: Record<string, string[]>;
+export type ChromiumResolution = {
+    ok: true;
+    executablePath: string;
+    source: 'configured' | 'playwright' | 'system';
+} | {
+    ok: false;
+    reason: string;
+};
+/** Hooks for tests; a site passes nothing. */
+export interface ResolveDeps {
+    exists?: (p: string) => boolean;
+    platform?: string;
+    playwrightInstalled?: () => boolean;
+    /** Playwright's own Chromium, or null when it cannot say. */
+    playwrightChromium?: () => Promise<string | null>;
+}
+/** Whether `playwright-core` is installed (it is an optional dependency). */
+export declare function playwrightInstalled(): boolean;
+/**
+ * Find a Chromium to render with. Read on every call, so installing Chromium
+ * or setting the path takes effect without a restart.
+ *
+ * @param configuredPath - `ngdpbase.export.pdf.provider.local-chrome.chromium-path` ('' = find one)
+ */
+export declare function resolveChromium(configuredPath: string, deps?: ResolveDeps): Promise<ChromiumResolution>;
+export declare function childEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Render one job in a child process. Resolves with the child's answer; rejects
+ * only when the child timed out, crashed or never answered.
+ *
+ * @param job - The render
+ */
+export declare function renderPdfInChild(job: PdfJob): Promise<PdfJobResult>;
+/**
+ * Normalise a PDF in a child process (`normalizePdf`, the same pass a local
+ * render gets). Rejects when the bytes are not a PDF pdf-lib can read, or the
+ * child times out.
+ *
+ * @param pdf - A PDF a PDF service returned
+ * @param timeoutMs - The child is killed after this
+ */
+export declare function normalizePdfInChild(pdf: Uint8Array, timeoutMs: number): Promise<Uint8Array>;

package/lib/src/export/pdfEngine.js

@@ -0,0 +1,195 @@
+/**
+ * The HTML → PDF engine (#1974): the options and the error every provider
+ * shares, and the child process the `local-chrome` provider renders in
+ * (headless Chromium, driven by `playwright-core`, both optional at run time).
+ *
+ * - `resolveChromium` finds a Chromium to run: the configured path, then the
+ *   one Playwright installed (`npx playwright install chromium`), then the
+ *   usual system locations. Nothing is downloaded at `npm install`.
+ * - `renderPdfInChild` renders one document in a child process
+ *   (`pdfRenderWorker.ts`), killed at the timeout, so the site never waits on
+ *   Chromium or on PDF parsing.
+ * - `normalizePdfInChild` gives a PDF a PDF service made (the
+ *   `chrome-service` provider) the same metadata pass, in the same kind of
+ *   child, so parsing it never runs on the thread that answers requests.
+ *
+ * `ExportManager.htmlToPdf` is the door, through its providers
+ * (`PdfProvider.ts`); nothing else calls these.
+ */
+import { fork } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/** Page sizes Chromium knows by name. */
+export const PDF_PAGE_SIZES = ['Letter', 'Legal', 'Tabloid', 'Ledger', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6'];
+/** A CSS length Chromium's PDF margins accept: a number and px, in, cm or mm. */
+const MARGIN = /^\d+(\.\d+)?(px|in|cm|mm)$/;
+/**
+ * No PDF engine: `playwright-core` is not installed, no Chromium was found, or
+ * it could not start. An add-on catches it by `code` (it cannot import core
+ * values) and falls back to HTML.
+ */
+export class PdfUnavailableError extends Error {
+    code = 'PDF_UNAVAILABLE';
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'PdfUnavailableError';
+    }
+}
+/**
+ * Validate a caller's options and fill the defaults. Throws on anything
+ * Chromium would misread, so a typo is an error rather than a different page.
+ *
+ * @param options - The caller's options
+ * @param defaultFormat - `ngdpbase.export.pdf.page-size`
+ */
+export function resolvePdfOptions(options, defaultFormat) {
+    const opts = options ?? {};
+    if (typeof opts !== 'object')
+        throw new TypeError('htmlToPdf: options must be an object');
+    const format = opts.format ?? defaultFormat;
+    if (!PDF_PAGE_SIZES.includes(format)) {
+        throw new TypeError(`htmlToPdf: format must be one of ${PDF_PAGE_SIZES.join(', ')} (got ${JSON.stringify(format)})`);
+    }
+    const margin = {};
+    for (const side of ['top', 'right', 'bottom', 'left']) {
+        const value = opts.margin?.[side];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'string' || !MARGIN.test(value)) {
+            throw new TypeError(`htmlToPdf: margin.${side} must be a length such as '20mm' or '0.5in' (got ${JSON.stringify(value)})`);
+        }
+        margin[side] = value;
+    }
+    const printBackground = opts.printBackground ?? true;
+    if (typeof printBackground !== 'boolean')
+        throw new TypeError('htmlToPdf: printBackground must be a boolean');
+    return { format: format, margin, printBackground };
+}
+/** Where Chromium or Chrome usually is, per platform. Checked after the configured path and Playwright's own. */
+export const SYSTEM_CHROMIUM_PATHS = {
+    linux: ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/lib/chromium/chromium', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/snap/bin/chromium'],
+    darwin: ['/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'],
+    win32: ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe']
+};
+const requireHere = createRequire(import.meta.url);
+/** Whether `playwright-core` is installed (it is an optional dependency). */
+export function playwrightInstalled() {
+    try {
+        requireHere.resolve('playwright-core');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function playwrightChromiumPath() {
+    try {
+        const { chromium } = await import('playwright-core');
+        return chromium.executablePath() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find a Chromium to render with. Read on every call, so installing Chromium
+ * or setting the path takes effect without a restart.
+ *
+ * @param configuredPath - `ngdpbase.export.pdf.provider.local-chrome.chromium-path` ('' = find one)
+ */
+export async function resolveChromium(configuredPath, deps = {}) {
+    const exists = deps.exists ?? existsSync;
+    if (!(deps.playwrightInstalled ?? playwrightInstalled)()) {
+        return { ok: false, reason: 'playwright-core is not installed (it is an optional dependency; npm install without --omit=optional)' };
+    }
+    if (configuredPath) {
+        return exists(configuredPath)
+            ? { ok: true, executablePath: configuredPath, source: 'configured' }
+            : { ok: false, reason: `ngdpbase.export.pdf.provider.local-chrome.chromium-path is set, but nothing is there: ${configuredPath}` };
+    }
+    const bundled = await (deps.playwrightChromium ?? playwrightChromiumPath)();
+    if (bundled && exists(bundled))
+        return { ok: true, executablePath: bundled, source: 'playwright' };
+    for (const candidate of SYSTEM_CHROMIUM_PATHS[deps.platform ?? process.platform] ?? []) {
+        if (exists(candidate))
+            return { ok: true, executablePath: candidate, source: 'system' };
+    }
+    return { ok: false, reason: 'no Chromium found: install Chromium, or set ngdpbase.export.pdf.provider.local-chrome.chromium-path' };
+}
+/**
+ * The environment the child gets: enough to find a home, a temp folder and
+ * fonts, and none of the site's secrets (the session secret, keys and
+ * passwords the site holds in its environment).
+ */
+const CHILD_ENV_KEYS = [
+    'PATH', 'HOME', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL', 'PLAYWRIGHT_BROWSERS_PATH',
+    'FONTCONFIG_PATH', 'FONTCONFIG_FILE', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_RUNTIME_DIR',
+    'SystemRoot', 'LOCALAPPDATA', 'USERPROFILE', 'APPDATA', 'ProgramFiles', 'ProgramFiles(x86)'
+];
+export function childEnv(env = process.env) {
+    const out = {};
+    for (const key of CHILD_ENV_KEYS)
+        if (env[key] !== undefined)
+            out[key] = env[key];
+    return out;
+}
+/**
+ * Render one job in a child process. Resolves with the child's answer; rejects
+ * only when the child timed out, crashed or never answered.
+ *
+ * @param job - The render
+ */
+export function renderPdfInChild(job) {
+    return runPdfChild(job);
+}
+/**
+ * Normalise a PDF in a child process (`normalizePdf`, the same pass a local
+ * render gets). Rejects when the bytes are not a PDF pdf-lib can read, or the
+ * child times out.
+ *
+ * @param pdf - A PDF a PDF service returned
+ * @param timeoutMs - The child is killed after this
+ */
+export async function normalizePdfInChild(pdf, timeoutMs) {
+    const result = await runPdfChild({ kind: 'normalize', pdf, timeoutMs });
+    if (!result.ok)
+        throw new Error(`the PDF could not be read: ${result.error}`);
+    return result.pdf;
+}
+function runPdfChild(job) {
+    // Compiled, the worker is the .js beside this file. From source (vitest,
+    // tsx) it is the .ts, which needs tsx's loader.
+    const fromSource = import.meta.url.endsWith('.ts');
+    const entry = new URL(fromSource ? './pdfRenderWorker.ts' : './pdfRenderWorker.js', import.meta.url);
+    return new Promise((resolve, reject) => {
+        const child = fork(entry, [], {
+            execArgv: fromSource ? ['--import', 'tsx'] : [],
+            env: childEnv(),
+            serialization: 'advanced',
+            stdio: ['ignore', 'ignore', 'pipe', 'ipc']
+        });
+        let settled = false;
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { if (stderr.length < 2000)
+            stderr += chunk.toString(); });
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new Error(`PDF render timed out after ${job.timeoutMs} ms`)));
+            child.kill('SIGKILL');
+        }, job.timeoutMs);
+        child.once('message', (result) => {
+            settle(() => resolve(result.ok ? { ok: true, pdf: Buffer.from(result.pdf) } : result));
+        });
+        child.once('error', (err) => settle(() => reject(err)));
+        child.once('exit', (code, signal) => {
+            settle(() => reject(new Error(`PDF render process exited (${signal ?? code}) without an answer${stderr ? `: ${stderr.trim().split('\n')[0]}` : ''}`)));
+        });
+        child.send(job);
+    });
+}

package/lib/src/ice/converterShim.d.ts

@@ -0,0 +1,5 @@
+import type { IContentConverter } from '../converters/IContentConverter.js';
+import type { IceShim } from './types.js';
+/** The receiver today's converters hand to. */
+export declare const PAGES_RECEIVER = "core.pages";
+export declare function converterShim(converter: IContentConverter, tableClasses: () => string[]): IceShim;

package/lib/src/ice/fileHandling.d.ts

@@ -0,0 +1,30 @@
+import { type ZipReadLimits } from '../utils/zipArchive.js';
+import type { IceUpload } from './types.js';
+/** A file's fingerprint: SHA-256 of its bytes, hex. */
+export declare function fingerprint(bytes: Buffer): string;
+/**
+ * Is this path noise — something an operating system or archiver adds that is
+ * nobody's data? Patterns (configuration, `ngdpbase.import.engine.noise`):
+ *
+ * - `name/` — any path with a directory segment of that name (`__MACOSX/`);
+ * - `prefix*` / `*suffix` — a file name starting or ending so (`._*`);
+ * - anything else — a file name exactly (`.DS_Store`), case-insensitive.
+ */
+export declare function isNoise(filePath: string, patterns: readonly string[]): boolean;
+/** Is this upload a zip archive the engine unpacks? By its name, or its media type. */
+export declare function isZip(upload: IceUpload): boolean;
+/**
+ * Unpack the zips among the uploads into the files they hold, named
+ * `archive.zip/inner/path`. A nested zip is unpacked too. Everything else is
+ * passed through. Limits are per archive (`ZipReadLimits`), so a small
+ * archive that expands enormously stops at the budget. An archive that cannot
+ * be read is returned in `unreadable`, with why; the rest go on.
+ */
+export declare function expandUploads(uploads: readonly IceUpload[], limits: ZipReadLimits, maxDepth: number, depth?: number): {
+    files: IceUpload[];
+    unreadable: Array<{
+        name: string;
+        size: number;
+        message: string;
+    }>;
+};

package/lib/src/ice/ledger.d.ts

@@ -0,0 +1,37 @@
+import type { IceLedger, LedgerFileEntry } from './types.js';
+interface ScopeFile {
+    scope: string;
+    files: LedgerFileEntry[];
+    items: string[];
+}
+/** Keeps the newest entry per fingerprint, at most `maxEntries` files and item keys per scope. */
+declare abstract class ScopedLedger implements IceLedger {
+    private readonly maxEntries;
+    constructor(maxEntries: number);
+    protected abstract load(scope: string): Promise<ScopeFile>;
+    protected abstract save(data: ScopeFile): Promise<void>;
+    /** One writer per scope at a time, so two runs in one scope cannot lose each other's entries. */
+    private readonly chains;
+    private serial;
+    lastFile(scope: string, sha256: string): Promise<LedgerFileEntry | null>;
+    recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
+    hasItem(scope: string, itemKey: string): Promise<boolean>;
+    recordItem(scope: string, itemKey: string): Promise<void>;
+    files(scope: string): Promise<LedgerFileEntry[]>;
+}
+/** The ledger in memory: for tests, and for a site that keeps no import history. */
+export declare class MemoryIceLedger extends ScopedLedger {
+    private readonly scopes;
+    constructor(maxEntries?: number);
+    protected load(scope: string): Promise<ScopeFile>;
+    protected save(data: ScopeFile): Promise<void>;
+}
+/** One JSON file per scope, named by the scope's hash (a scope holds a username). */
+export declare class FileIceLedger extends ScopedLedger {
+    private readonly dir;
+    constructor(dir: string, maxEntries: number);
+    private fileFor;
+    protected load(scope: string): Promise<ScopeFile>;
+    protected save(data: ScopeFile): Promise<void>;
+}
+export {};

package/lib/src/ice/runImport.d.ts

@@ -0,0 +1,51 @@
+import type { ActorContext } from '../context/ActorContext.js';
+import type { ZipReadLimits } from '../utils/zipArchive.js';
+import type { IceItem, IceLedger, IceRunReport, IceRunRequest, OriginalChoice, RegisteredReceiver, RegisteredShim, ShimTools } from './types.js';
+/** Configuration the engine reads (each a key under `ngdpbase.import.engine.`). */
+export interface IceEngineSettings {
+    noise: string[];
+    zip: ZipReadLimits;
+    maxZipDepth: number;
+    maxFileBytes: number;
+    maxChainDepth: number;
+    defaultOriginal: OriginalChoice;
+}
+export interface IceRunDeps {
+    /** Enabled shims, in registration order. */
+    shims: RegisteredShim[];
+    receivers: ReadonlyMap<string, RegisteredReceiver>;
+    ledger: IceLedger;
+    settings: IceEngineSettings;
+    tools(shim: RegisteredShim): ShimTools;
+    now?: () => Date;
+}
+/** The id of the receiver that keeps an original when the chosen receiver does not keep its own (D11). */
+export declare const FILES_RECEIVER = "core.files";
+/** The scope a run's fingerprints are checked in, unless the caller names one. */
+export declare function defaultScope(receiverId: string, ctx: ActorContext): string;
+export interface ChainLeaf {
+    item: IceItem;
+    chain: string[];
+}
+/** What a chain needs: the shims it may continue through, and where it stops. */
+export interface ChainSpec {
+    shims: RegisteredShim[];
+    tools(shim: RegisteredShim): ShimTools;
+    maxChainDepth: number;
+    /** Does this item, from this shim, stop here? */
+    done(shim: RegisteredShim, item: IceItem): boolean;
+    /** Named in the error when nothing takes an item further. */
+    target: string;
+}
+/**
+ * Run a shim, then the shims after it (D9), until each item is done. What
+ * came before travels with each item: earlier metadata under later, earlier
+ * warnings first. Partial notes are collected into `partial`.
+ */
+export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[]): Promise<ChainLeaf[]>;
+/**
+ * Run one import. Fills and returns `report`, which the caller may be
+ * showing while it runs. Never throws for one file's failure; that file's
+ * status says why.
+ */
+export declare function runImport(deps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, report: IceRunReport): Promise<IceRunReport>;