@cosmicdrift/kumiko-renderer-puppeteer-client 0.377.0 → 0.379.0

package/dist/document-pdf.js

@@ -4,11 +4,13 @@
 import { sanitizePdfAttachmentFileName } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { FileRefTooLargeError, readFileRefContent, } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
 import { RendererError, } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
-import { collectDocumentResourceKeys, compileDocumentBodyToHandlebars, createTemplateResolverApi, DEFAULT_PDF_LAYOUT_SLUG, PDF_DEFAULT_MARGIN_MM, PDF_FOOTER_MARGIN_MM, PDF_HEADER_MARGIN_MM, prepareDocumentForPrint, readLayoutRegions, readPdfTemplateMeta, readTemplateResourceMaxBytes, resolveTemplateVariables, sanitizeDocumentHtml, sanitizeLayoutHtml, TemplateNotFoundError, toResourceDataUri, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { collectDocumentImageVariables, collectDocumentResourceKeys, compileDocumentBodyToHandlebars, createTemplateResolverApi, DEFAULT_PDF_LAYOUT_SLUG, isResourceImageContentType, PDF_DEFAULT_MARGIN_MM, PDF_FOOTER_MARGIN_MM, PDF_HEADER_MARGIN_MM, prepareDocumentForPrint, readLayoutRegions, readPdfTemplateMeta, readTemplateResourceMaxBytes, resolveTemplateVariables, sanitizeDocumentHtml, sanitizeLayoutHtml, TemplateNotFoundError, toResourceDataUri, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, mergeResourceFileRefs, readBrandingAccentColor, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "@cosmicdrift/kumiko-renderer-mail-html";
 const LINE_BREAKS = /[\r\n]+/g;
 const IMAGE_CONTENT_TYPE_PREFIX = "image/";
+const MAX_RECORD_IMAGES = 24;
+const MAX_RECORD_IMAGES_TOTAL_BYTES = 20 * 1024 * 1024;
 const PREVIEW_PAGE_NUMBER = "1";
 const EMPTY_CHROMIUM_REGION = "<span></span>";
 const PAGE_NUMBER_HTML = '<span class="pageNumber"></span>';
@@ -26,6 +28,9 @@ const PRINT_CSS = [
     "[data-align=justify]{text-align:justify}",
     "[data-size=small]{font-size:8pt;color:#555}",
     "img{max-width:100%}",
+    ".kumiko-doc-images{display:grid;grid-template-columns:1fr 1fr;gap:6px;margin:8px 0}",
+    ".kumiko-doc-images:empty{display:none}",
+    ".kumiko-doc-images img{width:100%;break-inside:avoid;page-break-inside:avoid}",
 ].join("");
 const EMPTY_REGIONS = { header: "", signature: "", footer: "" };
 function describe(e) {
@@ -129,6 +134,67 @@ async function loadResourceDataUris(ctx, fileRefIds) {
     }
     return dataUris;
 }
+function fileRefIdsOf(value) {
+    if (typeof value === "string")
+        return [value];
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+// Own tenant only (no system files): the ids come from the app's record, so a foreign or
+// unreadable id drops silently like a missing image instead of failing the document.
+async function readRecordImage(ctx, filesForTenant, fileRefId, maxBytes) {
+    try {
+        const found = await readFileRefContent({
+            db: ctx.db,
+            filesForTenant,
+            fileRefId,
+            allowedTenantIds: [ctx.tenantId],
+            maxBytes,
+        });
+        if (found === null || !isResourceImageContentType(found.contentType))
+            return null;
+        return { dataUri: toResourceDataUri(found.contentType, found.content), size: found.size };
+    }
+    catch (e) {
+        if (e instanceof FileRefTooLargeError)
+            return null;
+        throw e;
+    }
+}
+async function loadRecordImageDataUris(ctx, variables, imageVariableNames) {
+    const dataUrisByVariable = new Map();
+    const { filesForTenant } = ctx;
+    if (filesForTenant === undefined || imageVariableNames.length === 0)
+        return dataUrisByVariable;
+    const maxBytes = await readTemplateResourceMaxBytes(ctx.config, ctx.registry);
+    const seenIds = new Set();
+    let loadedCount = 0;
+    let loadedBytes = 0;
+    for (const name of imageVariableNames) {
+        const dataUris = [];
+        for (const fileRefId of fileRefIdsOf(variables[name])) {
+            if (seenIds.has(fileRefId))
+                continue;
+            seenIds.add(fileRefId);
+            if (loadedCount >= MAX_RECORD_IMAGES)
+                break;
+            const image = await readRecordImage(ctx, filesForTenant, fileRefId, Math.min(maxBytes, MAX_RECORD_IMAGES_TOTAL_BYTES - loadedBytes));
+            if (image === null)
+                continue;
+            loadedCount += 1;
+            loadedBytes += image.size;
+            dataUris.push(image.dataUri);
+        }
+        dataUrisByVariable.set(name, dataUris);
+    }
+    return dataUrisByVariable;
+}
+// Text context without images variables: their value is file ids, which no placeholder,
+// title or file name pattern may print.
+function withoutImageVariables(variables, definitions) {
+    return Object.fromEntries(Object.entries(variables).filter(([name]) => !(Object.hasOwn(definitions, name) && definitions[name]?.type === "images")));
+}
 function renderRegion(hbs, region, context, resourceSrc) {
     if (region.trim() === "")
         return "";
@@ -221,9 +287,9 @@ async function findOwnPdfTemplate(tplApi, ctx, slug, locale, scope) {
         ...(scope === "system" && { scope }),
     });
 }
-async function assembleDocument(input, ctx, markers) {
+async function assembleDocument(input, ctx, markers, recordImages = "placeholder") {
     const { slug, locale, variables } = input;
-    const tplApi = createTemplateResolverApi(ctx.db);
+    const tplApi = createTemplateResolverApi(ctx.db, ctx.registry);
     const template = input.draft === undefined
         ? await resolvePdfTemplate(tplApi, ctx, slug, locale)
         : applyPdfDraft(await findStoredPdfTemplate(tplApi, ctx, slug, locale), await findOwnPdfTemplate(tplApi, ctx, slug, locale, input.draftScope ?? "tenant"), input.draft, slug, locale);
@@ -237,7 +303,18 @@ async function assembleDocument(input, ctx, markers) {
             readBrandingAccentColor(ctx),
         ]);
         const hbs = createDocumentHandlebars(format);
-        const context = { ...variables, tenantName, signature: "", imprint: "", page: "", pages: "" };
+        const variableDefinitions = resolveTemplateVariables(ctx.registry, slug, template.variableSchema);
+        const context = {
+            ...withoutImageVariables(variables, variableDefinitions),
+            tenantName,
+            signature: "",
+            imprint: "",
+            page: "",
+            pages: "",
+        };
+        const recordImageUris = recordImages === "resolve"
+            ? await loadRecordImageDataUris(ctx, variables, collectDocumentImageVariables(template.content))
+            : new Map();
         const bodyKeys = collectDocumentResourceKeys(template.content);
         const layoutKeys = collectRegionResourceKeys(layout.regions);
         const bodyRefs = await resolveResourceFileRefs(tplApi, ctx, template, bodyKeys);
@@ -247,7 +324,12 @@ async function assembleDocument(input, ctx, markers) {
         const dataUris = await loadResourceDataUris(ctx, mergeResourceFileRefs(bodyRefs, layoutRefs));
         const resourceSrc = (key) => dataUris.get(key);
         const missingResourceKeys = [...new Set([...bodyKeys, ...layoutKeys])].filter((key) => !dataUris.has(key));
-        const bodySource = compileDocumentBodyToHandlebars(template.content, resolveTemplateVariables(ctx.registry, slug, template.variableSchema), { resourceSrc, ...(accentColor !== undefined && { stepsColor: accentColor }) });
+        const bodySource = compileDocumentBodyToHandlebars(template.content, variableDefinitions, {
+            resourceSrc,
+            recordImagesSrc: (variable) => recordImageUris.get(variable) ?? [],
+            recordImagesPlaceholder: recordImages === "placeholder",
+            ...(accentColor !== undefined && { stepsColor: accentColor }),
+        });
         const bodyHtml = prepareDocumentForPrint(compileDocumentSource(hbs, bodySource)(context));
         const signatureHtml = renderRegion(hbs, layout.regions.signature, context, resourceSrc);
         const pagedContext = markers === "chromium"
@@ -283,7 +365,7 @@ async function assembleDocument(input, ctx, markers) {
     }
 }
 export async function buildDocumentPdfRequest(req, ctx) {
-    return toPdfRequest(await assembleDocument(req.payload, ctx, "chromium"), req.payload.locale);
+    return toPdfRequest(await assembleDocument(req.payload, ctx, "chromium", "resolve"), req.payload.locale);
 }
 // Prints an unsaved draft; the stored template of the slug only supplies images and the variable schema.
 export async function buildDocumentDraftPdfRequest(req, ctx) {

package/dist/feature.js

@@ -14,11 +14,12 @@ import { puppeteerStatusQuery } from "./status.query.js";
 //   - PUPPETEER_CLIENT_TIMEOUT_MS    default 60000
 //   - PUPPETEER_CLIENT_MAX_RETRIES   default 3
 //
-// **Retry strategy:** 5xx + network errors → exponential backoff (200ms,
+// **Retry strategy:** 502/503 + network errors → exponential backoff (200ms,
 // 400ms, 800ms) + jitter. 4xx → NO retry (config bug, fail immediately).
+// Other 5xx and client timeouts → NO retry (the render already ran).
 export function createRendererPuppeteerClientFeature() {
     return defineFeature("renderer-puppeteer-client", (r) => {
-        r.describe("A `renderer-foundation` plugin that prints documents to PDF through a separately deployed `puppeteer-service`. A `document-pdf` request names a stored template (`{ slug, locale, variables }`): the plugin resolves the template and its `pdf-layout` (header, signature and footer regions), embeds every image as a data URI, turns repeating table header rows into a real table head and sends the finished HTML to the service, which performs no network fetches itself. The page format, margins, file name pattern and title come from the template meta. A write handler renders with `renderPdfBeforeTransaction(ctx, { slug, locale, variables })` as its `beforeTransaction` phase, so the print service call holds no database connection, and stores the result with `storeRenderedPdf(ctx, event.prepared)` in the handler: a file plus a `rendered-pdf` record that keeps the template and layout version, so a stored document can always be traced to the text it was created from. The `puppeteer-status` query tells a TenantAdmin whether the service answers; while it does not, rendering fails with a `puppeteer_unavailable` error (HTTP 503) and no PDF is created. `image-snapshot` requests still take ready HTML in `payload.content`, which must embed all resources as data: URIs because the service fetches no http(s) resources. Configure the endpoint and token with `PUPPETEER_SERVICE_URL` and `PUPPETEER_AUTH_TOKEN`; the client retries 5xx and network errors with exponential backoff (default 3 retries), 4xx fails at once. The feature adds the `rendered_pdfs` table, so apps that mount it need a schema migration.");
+        r.describe("A `renderer-foundation` plugin that prints documents to PDF through a separately deployed `puppeteer-service`. A `document-pdf` request names a stored template (`{ slug, locale, variables }`): the plugin resolves the template and its `pdf-layout` (header, signature and footer regions), embeds every image as a data URI, turns repeating table header rows into a real table head and sends the finished HTML to the service, which performs no network fetches itself. The page format, margins, file name pattern and title come from the template meta. A write handler renders with `renderPdfBeforeTransaction(ctx, { slug, locale, variables })` as its `beforeTransaction` phase, so the print service call holds no database connection, and stores the result with `storeRenderedPdf(ctx, event.prepared)` in the handler: a file plus a `rendered-pdf` record that keeps the template and layout version, so a stored document can always be traced to the text it was created from. The `puppeteer-status` query tells a TenantAdmin whether the service answers; while it does not, rendering fails with a `puppeteer_unavailable` error (HTTP 503) and no PDF is created. `image-snapshot` requests still take ready HTML in `payload.content`, which must embed all resources as data: URIs because the service fetches no http(s) resources. Configure the endpoint and token with `PUPPETEER_SERVICE_URL` and `PUPPETEER_AUTH_TOKEN`; the client retries 502, 503 and network errors with exponential backoff (default 3 retries); 4xx, other 5xx and client timeouts fail at once, because the render has already run. The feature adds the `rendered_pdfs` table, so apps that mount it need a schema migration.");
         r.requires({ features: ["renderer-foundation"] });
         r.useExtension("renderer", "puppeteer", {
             kinds: ["document-pdf", "image-snapshot"],

package/kumiko-es-tables.json

@@ -0,0 +1,6 @@
+[
+  {
+    "module": "entity",
+    "export": "renderedPdfsTable"
+  }
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-puppeteer-client",
-  "version": "0.377.0",
+  "version": "0.379.0",
   "description": "Renderer-Foundation plugin: HTTP client for puppeteer-service (PDF + image snapshot via remote browser).",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -19,13 +19,13 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.377.0",
-    "@cosmicdrift/kumiko-framework": "0.377.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.377.0",
-    "@cosmicdrift/kumiko-types": "0.377.0"
+    "@cosmicdrift/kumiko-bundled-features": "0.379.0",
+    "@cosmicdrift/kumiko-framework": "0.379.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.379.0",
+    "@cosmicdrift/kumiko-types": "0.379.0"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.377.0"
+    "@cosmicdrift/kumiko-testing": "0.379.0"
   },
   "repository": {
     "type": "git",
@@ -52,6 +52,7 @@
   },
   "files": [
     "dist",
+    "kumiko-es-tables.json",
     "src/changes.json",
     "README.md",
     "LICENSE"

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Retry documentation matches the client",
+    "detail": "The client retries 502, 503 and network errors; other 5xx and client timeouts fail at once because the render already ran. The feature description no longer promises a retry for every 5xx."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Package ships its event-store table catalog",
+    "detail": "kumiko-es-tables.json is included in the published files; no runtime change."
+  },
   {
     "version": "0.365.0",
     "type": "improvement",