@jwilleke/ngdpbase-types 5.26.0 → 5.27.0

package/lib/src/managers/EmailManager.d.ts

@@ -20,17 +20,34 @@
  * running count, not one per email. `send()` still rejects, so a caller with
  * a person waiting can tell them.
  *
+ * `sendTo(ctx, …, { attachments })` attaches files, a PDF from
+ * `ExportManager.htmlToPdf` for one (#1974), up to
+ * `ngdpbase.mail.attachments.max-bytes` in total. A log line names how many
+ * files and bytes, never their names or content.
+ *
  * @see docs/admin/email-setup.md for operator setup instructions
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/456}
  */
 import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import type { MailMessage, MailProvider } from '../mail/MailProvider.js';
+import type { MailAttachment, MailMessage, MailProvider } from '../mail/MailProvider.js';
+import type { ActorContext } from '../context/ActorContext.js';
+export type { MailAttachment } from '../mail/MailProvider.js';
 /** The degraded reason while sends fail; cleared by the next success. */
 export declare const SEND_FAILING_REASON = "outbound email is failing \u2014 see the server log and the administrator notification";
 /** Title of the administrator notice. */
 export declare const SEND_FAILING_TITLE = "Email could not be sent";
+/** An attachment the message cannot carry (#1974): refused before sending, so it is not a delivery failure. */
+export declare class AttachmentRefusedError extends Error {
+    readonly code = "ATTACHMENT_REFUSED";
+    constructor(message: string);
+}
+/** What a caller may add after the body (#1974). */
+export interface SendOptions {
+    /** Files to attach, e.g. a PDF from `ExportManager.htmlToPdf`. */
+    attachments?: MailAttachment[];
+}
 declare class EmailManager extends BaseManager implements MailProvider {
     private provider;
     private providerName;
@@ -39,6 +56,7 @@ declare class EmailManager extends BaseManager implements MailProvider {
     private noticeWindowMs;
     private notice;
     private failuresSinceSuccess;
+    private attachmentMaxBytes;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /**
@@ -49,16 +67,25 @@ declare class EmailManager extends BaseManager implements MailProvider {
      */
     send(message: MailMessage): Promise<void>;
     /**
-     * Convenience wrapper — build and send a message in one call.
+     * Build and send a message in one call.
+     *
+     * @param ctx - Who is sending (security-posture P1); named in the log line when the message carries attachments
+     * @param to - Recipient address
+     * @param subject - Subject line
+     * @param text - Plain-text body
+     * @param html - Optional HTML body
+     * @param options - Attachments (#1974); their total is capped by `ngdpbase.mail.attachments.max-bytes`
      */
-    sendTo(to: string, subject: string, text: string, html?: string): Promise<void>;
+    sendTo(ctx: ActorContext, to: string, subject: string, text: string, html?: string, options?: SendOptions): Promise<void>;
     /**
      * Send without waiting, for a sender nobody is waiting on (a form's copy, a
      * reservation notice). Never rejects: a failure is already logged and
      * reported to administrators by `send()` (#1916), so there is nothing left
-     * for the caller to do with it.
+     * for the caller to do with it. An attachment over the limit is logged here.
      */
-    sendInBackground(to: string, subject: string, text: string, html?: string): void;
+    sendInBackground(ctx: ActorContext, to: string, subject: string, text: string, html?: string, options?: SendOptions): void;
+    /** Refuse attachments a mail relay would choke on, or that are not what they say. */
+    private checkAttachments;
     /** Whether sends are failing right now: degraded by a failed send, not yet cleared by a success. */
     isDeliveryFailing(): boolean;
     private reportFailure;

package/lib/src/managers/ExportManager.d.ts

@@ -1,6 +1,16 @@
 import type { ActorContext } from '../context/ActorContext.js';
 import BaseManager from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
+import { PdfUnavailableError, type PdfJob, type PdfJobResult, type PdfOptions, type ChromiumResolution } from '../export/pdfEngine.js';
+import type { Transport } from '../http/guardedFetch.js';
+export { PdfUnavailableError };
+export type { PdfOptions, PdfMargin, PdfPageSize } from '../export/pdfEngine.js';
+/**
+ * The needs-attention reason while PDF export has no engine (#1974). Set only
+ * when something asked for a PDF and could not have one; cleared by the next
+ * render that works.
+ */
+export declare const PDF_UNAVAILABLE_REASON = "PDF export unavailable: choose a PDF provider (local-chrome or chrome-service) in ngdpbase.export.pdf.provider, or fix the one chosen (the server log says why)";
 /**
  * Export file metadata interface
  */
@@ -41,6 +51,14 @@ export interface PageForExport {
 }
 declare class ExportManager extends BaseManager {
     private exportDirectory;
+    /** What the providers call out to; replaced in tests. A site never sets these. */
+    protected pdfRenderer: (job: PdfJob) => Promise<PdfJobResult>;
+    protected chromiumResolver: (configuredPath: string) => Promise<ChromiumResolution>;
+    protected pdfServiceTransport: Transport | undefined;
+    protected pdfNormalizer: (pdf: Uint8Array, timeoutMs: number) => Promise<Uint8Array>;
+    /** Renders running now, and renders waiting for a slot (`ngdpbase.export.pdf.max-concurrent`). */
+    private pdfActive;
+    private pdfWaiting;
     /**
      * Creates a new ExportManager instance
      *
@@ -70,6 +88,50 @@ declare class ExportManager extends BaseManager {
      * @returns The CSV document
      */
     toCsv(headers: readonly string[], rows: readonly (readonly unknown[])[]): string;
+    /**
+     * A rendered HTML document (print CSS and all) as PDF bytes (#1974).
+     *
+     * - __A provider renders it:__ `ngdpbase.export.pdf.provider` — `none`
+     *   (default), `local-chrome` (a Chromium on this machine) or
+     *   `chrome-service` (a Chromium service by URL, e.g. Gotenberg); see
+     *   `src/export/PdfProvider.ts`. Read on every render, so a change applies
+     *   without a restart.
+     * - __Sandboxed:__ `local-chrome` runs Chromium with JavaScript off and every
+     *   request refused except `data:` URIs, so images, stylesheets and fonts
+     *   must be inlined. A `chrome-service` is reached through the egress policy,
+     *   and what its Chromium may load is the service's own setting.
+     * - __Deterministic:__ the same HTML on the same core version, provider and
+     *   engine version gives the same bytes (no dates, no random ID), so an
+     *   add-on can store the document's SHA-256.
+     * - __Off the request path:__ a local render, and the metadata pass on a
+     *   service's PDF, each run in a child process; everything is bounded by
+     *   `ngdpbase.export.pdf.timeout-ms`, and at most
+     *   `ngdpbase.export.pdf.max-concurrent` run at once while the rest wait.
+     * - __Optional:__ with no engine (provider `none`, or the chosen one cannot
+     *   be used) it throws `PdfUnavailableError` (`code: 'PDF_UNAVAILABLE'`),
+     *   logs why, and this manager shows "needs attention" on the admin
+     *   dashboard until a render works. A site that never asks for a PDF is
+     *   never flagged.
+     *
+     * Records no audit event: it reads nothing and changes nothing. The caller
+     * that issues the document records that, with its own event.
+     *
+     * @param ctx - Who is asking; named in the log line
+     * @param html - A complete HTML document
+     * @param options - Page size, margins, printBackground; an `@page` rule in the HTML wins
+     * @returns The PDF
+     */
+    htmlToPdf(ctx: ActorContext, html: string, options?: PdfOptions): Promise<Buffer>;
+    /**
+     * The provider `ngdpbase.export.pdf.provider` names, built for this render
+     * from the current settings. A name that is not a provider is unavailable,
+     * with the reason, as `none` is.
+     */
+    private pdfProvider;
+    /** Log why, flag the manager (unless something worse is already shown), and refuse. */
+    private pdfUnavailable;
+    private acquirePdfSlot;
+    private releasePdfSlot;
     /**
      * Initialize the ExportManager
      *

package/lib/src/managers/ExportManager.js

@@ -3,11 +3,27 @@ import fs from 'fs/promises';
 import path from 'path';
 import LocaleUtils from '../utils/LocaleUtils.js';
 import logger from '../utils/logger.js';
+import { actorOf } from '../context/ActorContext.js';
+import { PdfUnavailableError, normalizePdfInChild, renderPdfInChild, resolveChromium, resolvePdfOptions } from '../export/pdfEngine.js';
+import { NonePdfProvider, PDF_PROVIDERS } from '../export/PdfProvider.js';
+import { LocalChromePdfProvider } from '../export/LocalChromePdfProvider.js';
+import { ChromeServicePdfProvider } from '../export/ChromeServicePdfProvider.js';
+import { resolveEgressPolicy } from '../http/egressPolicy.js';
+export { PdfUnavailableError };
+/**
+ * The needs-attention reason while PDF export has no engine (#1974). Set only
+ * when something asked for a PDF and could not have one; cleared by the next
+ * render that works.
+ */
+export const PDF_UNAVAILABLE_REASON = 'PDF export unavailable: choose a PDF provider (local-chrome or chrome-service) in ngdpbase.export.pdf.provider, or fix the one chosen (the server log says why)';
+/** Shipped defaults of the `ngdpbase.export.pdf.*` keys. */
+const PDF_DEFAULTS = { provider: 'none', pageSize: 'Letter', timeoutMs: 30_000, maxConcurrent: 2, serviceMaxBytes: 52_428_800 };
 /**
  * ExportManager - Handles page exports to multiple formats
  *
  * Similar to JSPWiki's export functionality, provides page export capabilities
- * to HTML, PDF, markdown, and other formats.
+ * to HTML and markdown, the one CSV writer, and HTML → PDF (`htmlToPdf`, #1974)
+ * through an optional headless Chromium.
  *
  * @class ExportManager
  * @extends BaseManager
@@ -24,6 +40,14 @@ import logger from '../utils/logger.js';
 const CSV_FORMULA_START = /^[=+\-@\t\r]/;
 class ExportManager extends BaseManager {
     exportDirectory;
+    /** What the providers call out to; replaced in tests. A site never sets these. */
+    pdfRenderer = renderPdfInChild;
+    chromiumResolver = (p) => resolveChromium(p);
+    pdfServiceTransport = undefined;
+    pdfNormalizer = normalizePdfInChild;
+    /** Renders running now, and renders waiting for a slot (`ngdpbase.export.pdf.max-concurrent`). */
+    pdfActive = 0;
+    pdfWaiting = [];
     /**
      * Creates a new ExportManager instance
      *
@@ -67,6 +91,121 @@ class ExportManager extends BaseManager {
     toCsv(headers, rows) {
         return [headers, ...rows].map((row) => row.map((cell) => this.csvCell(cell)).join(',')).join('\r\n') + '\r\n';
     }
+    /**
+     * A rendered HTML document (print CSS and all) as PDF bytes (#1974).
+     *
+     * - __A provider renders it:__ `ngdpbase.export.pdf.provider` — `none`
+     *   (default), `local-chrome` (a Chromium on this machine) or
+     *   `chrome-service` (a Chromium service by URL, e.g. Gotenberg); see
+     *   `src/export/PdfProvider.ts`. Read on every render, so a change applies
+     *   without a restart.
+     * - __Sandboxed:__ `local-chrome` runs Chromium with JavaScript off and every
+     *   request refused except `data:` URIs, so images, stylesheets and fonts
+     *   must be inlined. A `chrome-service` is reached through the egress policy,
+     *   and what its Chromium may load is the service's own setting.
+     * - __Deterministic:__ the same HTML on the same core version, provider and
+     *   engine version gives the same bytes (no dates, no random ID), so an
+     *   add-on can store the document's SHA-256.
+     * - __Off the request path:__ a local render, and the metadata pass on a
+     *   service's PDF, each run in a child process; everything is bounded by
+     *   `ngdpbase.export.pdf.timeout-ms`, and at most
+     *   `ngdpbase.export.pdf.max-concurrent` run at once while the rest wait.
+     * - __Optional:__ with no engine (provider `none`, or the chosen one cannot
+     *   be used) it throws `PdfUnavailableError` (`code: 'PDF_UNAVAILABLE'`),
+     *   logs why, and this manager shows "needs attention" on the admin
+     *   dashboard until a render works. A site that never asks for a PDF is
+     *   never flagged.
+     *
+     * Records no audit event: it reads nothing and changes nothing. The caller
+     * that issues the document records that, with its own event.
+     *
+     * @param ctx - Who is asking; named in the log line
+     * @param html - A complete HTML document
+     * @param options - Page size, margins, printBackground; an `@page` rule in the HTML wins
+     * @returns The PDF
+     */
+    async htmlToPdf(ctx, html, options) {
+        if (!ctx)
+            throw new TypeError('htmlToPdf: a context is required (security-posture P1)');
+        if (typeof html !== 'string' || html.length === 0)
+            throw new TypeError('htmlToPdf: html must be a non-empty string');
+        const config = this.engine.getManager('ConfigurationManager');
+        const setting = (key, fallback) => config?.getProperty(key, fallback) ?? fallback;
+        const resolved = resolvePdfOptions(options, String(setting('ngdpbase.export.pdf.page-size', PDF_DEFAULTS.pageSize)));
+        const timeoutMs = positiveInt(setting('ngdpbase.export.pdf.timeout-ms', PDF_DEFAULTS.timeoutMs), PDF_DEFAULTS.timeoutMs);
+        const maxConcurrent = positiveInt(setting('ngdpbase.export.pdf.max-concurrent', PDF_DEFAULTS.maxConcurrent), PDF_DEFAULTS.maxConcurrent);
+        const provider = this.pdfProvider(setting);
+        const started = Date.now();
+        await this.acquirePdfSlot(maxConcurrent);
+        let rendered;
+        try {
+            rendered = await provider.render({ html, options: resolved, timeoutMs });
+        }
+        catch (err) {
+            if (err instanceof PdfUnavailableError)
+                this.pdfUnavailable(err.message);
+            throw err;
+        }
+        finally {
+            this.releasePdfSlot();
+        }
+        this.markReadyIfDegradedBy(PDF_UNAVAILABLE_REASON);
+        const pdf = Buffer.from(rendered.pdf);
+        logger.info(`[ExportManager] PDF rendered bytes=${pdf.length} ms=${Date.now() - started} engine=${rendered.engine} by=${actorOf(ctx).user}`);
+        return pdf;
+    }
+    /**
+     * The provider `ngdpbase.export.pdf.provider` names, built for this render
+     * from the current settings. A name that is not a provider is unavailable,
+     * with the reason, as `none` is.
+     */
+    pdfProvider(setting) {
+        const name = String(setting('ngdpbase.export.pdf.provider', PDF_DEFAULTS.provider));
+        switch (name) {
+            case 'none':
+                return new NonePdfProvider();
+            case 'local-chrome':
+                return new LocalChromePdfProvider(String(setting('ngdpbase.export.pdf.provider.local-chrome.chromium-path', '')), {
+                    render: (job) => this.pdfRenderer(job),
+                    resolve: (p) => this.chromiumResolver(p)
+                });
+            case 'chrome-service': {
+                const config = this.engine.getManager('ConfigurationManager');
+                const egress = resolveEgressPolicy((key, fallback) => config?.getProperty(key, fallback));
+                return new ChromeServicePdfProvider({
+                    url: String(setting('ngdpbase.export.pdf.provider.chrome-service.url', '')),
+                    policy: egress.policy,
+                    maxBytes: positiveInt(setting('ngdpbase.export.pdf.provider.chrome-service.max-bytes', PDF_DEFAULTS.serviceMaxBytes), PDF_DEFAULTS.serviceMaxBytes)
+                }, { ...(this.pdfServiceTransport ? { transport: this.pdfServiceTransport } : {}), normalize: (pdf, ms) => this.pdfNormalizer(pdf, ms) });
+            }
+            default:
+                return new NonePdfProvider(`ngdpbase.export.pdf.provider '${name}' is not a PDF provider: use ${PDF_PROVIDERS.join(', ')}`);
+        }
+    }
+    /** Log why, flag the manager (unless something worse is already shown), and refuse. */
+    pdfUnavailable(reason) {
+        logger.warn(`[ExportManager] PDF export unavailable: ${reason}`);
+        const status = this.getManagerStatus();
+        if (status.state === 'ready' || status.reason === PDF_UNAVAILABLE_REASON) {
+            this.markNeedsAttention(PDF_UNAVAILABLE_REASON, 'ngdpbase.export.pdf.provider');
+        }
+        throw new PdfUnavailableError(`PDF export unavailable: ${reason}`);
+    }
+    async acquirePdfSlot(limit) {
+        if (this.pdfActive < limit) {
+            this.pdfActive++;
+            return;
+        }
+        // The slot is handed over by releasePdfSlot, so pdfActive stays as it is.
+        await new Promise((resolve) => this.pdfWaiting.push(resolve));
+    }
+    releasePdfSlot() {
+        const next = this.pdfWaiting.shift();
+        if (next)
+            next();
+        else
+            this.pdfActive--;
+    }
     /**
      * Initialize the ExportManager
      *
@@ -90,7 +229,8 @@ class ExportManager extends BaseManager {
         }
         // Create exports directory
         await fs.mkdir(this.exportDirectory, { recursive: true });
-        logger.info('ExportManager initialized');
+        const pdfProviderName = this.engine.getManager('ConfigurationManager')?.getProperty('ngdpbase.export.pdf.provider', PDF_DEFAULTS.provider);
+        logger.info(`ExportManager initialized (PDF provider: ${pdfProviderName ?? PDF_DEFAULTS.provider})`);
     }
     /**
      * Export a single page to HTML
@@ -417,4 +557,9 @@ class ExportManager extends BaseManager {
         return date.toLocaleString();
     }
 }
+/** A positive whole number from config, or the shipped default. */
+function positiveInt(value, fallback) {
+    const n = Number(value);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+}
 export default ExportManager;