@k2b/cloud 0.6.0-rc.0

package/src/services/outbox.ts

@@ -0,0 +1,187 @@
+import { sql } from "bun";
+import { logger } from "./logging";
+
+/**
+ * PostgreSQL transactional-outbox dispatcher.
+ *
+ * Domain writers insert a row in their own transaction; this dispatcher claims
+ * pending rows (`FOR UPDATE SKIP LOCKED`), publishes them, and records
+ * delivery or an exponential-backoff retry. Rows stay durable until they are
+ * delivered (or dead after `maxAttempts`, when the table has a `dead_at`
+ * column), and delivered rows are pruned after a retention period.
+ *
+ * Required columns: `id uuid`, `attempts int`, `next_attempt_at timestamptz`,
+ * `claimed_until timestamptz`, `delivered_at timestamptz`, `last_error text`,
+ * `created_at timestamptz`. `maxAttempts` additionally needs `dead_at`.
+ */
+
+const DEFAULT_CLAIM_MS = 30_000;
+const DEFAULT_BATCH_SIZE = 100;
+const DELIVERED_RETENTION = "7 days";
+const DEAD_RETENTION = "30 days";
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+
+export type OutboxRow = {
+  id: string;
+  attempts: number;
+};
+
+export type PgOutboxConfig<Row extends OutboxRow> = {
+  /** Schema-qualified table, e.g. `mail.live_invalidation_outbox`. */
+  table: string;
+  /** Log source. */
+  name: string;
+  publish: (row: Row) => Promise<unknown>;
+  reconcileIntervalMs: number;
+  /**
+   * Column whose rows must be delivered in insertion order. A pending earlier
+   * row with the same value blocks later ones until it is delivered or dead.
+   */
+  orderBy?: string;
+  /** Mark rows dead after this many failed attempts (requires `dead_at`). */
+  maxAttempts?: number;
+  claimMs?: number;
+  batchSize?: number;
+};
+
+export type PgOutbox<Row extends OutboxRow> = {
+  claim(limit?: number): Promise<Row[]>;
+  dispatch(row: Row, publish?: (row: Row) => Promise<unknown>): Promise<void>;
+  /** Drain every claimable row; concurrent calls join the active pass. */
+  reconcile(): Promise<number>;
+  /** `reconcile()` with failures logged instead of thrown. */
+  notify(): Promise<void>;
+  start(): void;
+  stop(): Promise<void>;
+};
+
+const identifier = (name: string, label: string): ReturnType<typeof sql.unsafe> => {
+  if (!name.split(".").every((part) => IDENTIFIER.test(part))) throw new Error(`Invalid outbox ${label}: ${name}`);
+  return sql.unsafe(name);
+};
+
+export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row>): PgOutbox<Row> => {
+  const table = identifier(config.table, "table");
+  const orderBy = config.orderBy ? identifier(config.orderBy, "ordering column") : null;
+  const maxAttempts = config.maxAttempts ?? null;
+  const claimMs = config.claimMs ?? DEFAULT_CLAIM_MS;
+  const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
+  const log = logger(config.name);
+  const notDead = maxAttempts === null ? sql`` : sql`AND dead_at IS NULL`;
+  const earlierNotDead = maxAttempts === null ? sql`` : sql`AND earlier.dead_at IS NULL`;
+
+  const claim: PgOutbox<Row>["claim"] = async (limit = batchSize) => {
+    const cap = Math.min(Math.max(limit, 1), batchSize);
+    const ordered =
+      orderBy === null
+        ? sql``
+        : sql`
+          AND NOT EXISTS (
+            SELECT 1
+            FROM ${table} earlier
+            WHERE earlier.${orderBy} = current.${orderBy}
+              AND earlier.delivered_at IS NULL
+              ${earlierNotDead}
+              AND (earlier.created_at, earlier.id) < (current.created_at, current.id)
+          )
+        `;
+    // One statement: the CTE claim and the update commit atomically.
+    return sql<Row[]>`
+      WITH candidates AS MATERIALIZED (
+        SELECT current.id
+        FROM ${table} current
+        WHERE current.delivered_at IS NULL
+          ${notDead}
+          AND current.next_attempt_at <= now()
+          AND (current.claimed_until IS NULL OR current.claimed_until <= now())
+          ${ordered}
+        ORDER BY current.next_attempt_at, current.created_at, current.id
+        LIMIT ${cap}
+        FOR UPDATE SKIP LOCKED
+      )
+      UPDATE ${table} outbox
+      SET claimed_until = now() + (${claimMs} * interval '1 millisecond')
+      FROM candidates
+      WHERE outbox.id = candidates.id
+      RETURNING outbox.*
+    `;
+  };
+
+  const dispatch: PgOutbox<Row>["dispatch"] = async (row, publish = config.publish) => {
+    try {
+      await publish(row);
+      await sql`
+        UPDATE ${table}
+        SET delivered_at = now(), claimed_until = NULL, last_error = NULL
+        WHERE id = ${row.id}::uuid AND delivered_at IS NULL ${notDead} AND attempts = ${row.attempts}
+      `;
+    } catch (error) {
+      const attempts = row.attempts + 1;
+      const message = error instanceof Error ? error.message : String(error);
+      const delaySeconds = Math.min(300, 2 ** Math.min(attempts, 8));
+      const dead = maxAttempts === null ? sql`` : sql`dead_at = CASE WHEN ${attempts} >= ${maxAttempts} THEN now() ELSE dead_at END,`;
+      await sql`
+        UPDATE ${table}
+        SET attempts = ${attempts},
+            next_attempt_at = now() + (${delaySeconds} * interval '1 second'),
+            claimed_until = NULL,
+            ${dead}
+            last_error = ${message.slice(0, 1_000)}
+        WHERE id = ${row.id}::uuid AND delivered_at IS NULL ${notDead} AND attempts = ${row.attempts}
+      `;
+      log.warn("Outbox delivery failed", { outboxId: row.id, attempts, error: message });
+    }
+  };
+
+  let activeReconcile: Promise<number> | null = null;
+  let reconcileRequested = false;
+
+  const reconcile: PgOutbox<Row>["reconcile"] = () => {
+    reconcileRequested = true;
+    if (activeReconcile) return activeReconcile;
+    activeReconcile = (async () => {
+      const deadExpired = maxAttempts === null ? sql`` : sql`OR dead_at < now() - ${DEAD_RETENTION}::interval`;
+      await sql`
+        DELETE FROM ${table}
+        WHERE delivered_at < now() - ${DELIVERED_RETENTION}::interval
+           ${deadExpired}
+      `;
+      let processed = 0;
+      let rows: Row[];
+      do {
+        reconcileRequested = false;
+        rows = await claim();
+        // Sequential: a claimed batch may contain ordered rows of one key.
+        for (const row of rows) await dispatch(row);
+        processed += rows.length;
+      } while (reconcileRequested || rows.length > 0);
+      return processed;
+    })().finally(() => {
+      activeReconcile = null;
+    });
+    return activeReconcile;
+  };
+
+  const notify: PgOutbox<Row>["notify"] = async () => {
+    await reconcile().catch((error) => {
+      log.warn("Outbox reconcile failed", { error: error instanceof Error ? error.message : String(error) });
+    });
+  };
+
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const start: PgOutbox<Row>["start"] = () => {
+    if (timer) return;
+    timer = setInterval(() => void notify(), config.reconcileIntervalMs);
+    if (typeof timer === "object" && "unref" in timer) timer.unref();
+    void notify();
+  };
+
+  const stop: PgOutbox<Row>["stop"] = async () => {
+    if (timer) clearInterval(timer);
+    timer = null;
+    await activeReconcile;
+  };
+
+  return { claim, dispatch, reconcile, notify, start, stop };
+};

package/src/services/pdf/gotenberg.ts

@@ -0,0 +1,290 @@
+import * as settings from "../settings";
+
+export type GotenbergRenderErrorCode =
+  | "bad_input"
+  | "not_configured"
+  | "html_too_large"
+  | "pdf_too_large"
+  | "request_failed"
+  | "bad_response"
+  | "timeout";
+
+export class GotenbergRenderError extends Error {
+  constructor(
+    readonly code: GotenbergRenderErrorCode,
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "GotenbergRenderError";
+  }
+}
+
+export type GotenbergConfig = {
+  url: string;
+  username?: string;
+  password?: string;
+  timeoutMs: number;
+  maxHtmlBytes: number;
+  maxPdfBytes: number;
+};
+
+export type RenderHtmlToPdfInput = {
+  html: string;
+  headerHtml?: string | null;
+  footerHtml?: string | null;
+  filename?: string;
+};
+
+export type RenderFacturXHtmlToPdfInput = RenderHtmlToPdfInput & {
+  xml: string;
+  conformanceLevel?: "MINIMUM" | "BASIC WL" | "BASIC" | "EN 16931" | "EXTENDED";
+  documentType?: "INVOICE" | "ORDER" | "ORDER RESPONSE";
+  facturXVersion?: "1.0";
+};
+
+export type RenderHtmlToPdfResult = {
+  pdf: Uint8Array;
+  contentType: string;
+};
+
+export type MergePdfsInput = {
+  files: Array<{
+    pdf: Uint8Array;
+    filename?: string;
+  }>;
+};
+
+export type GotenbergFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export type RenderHtmlToPdfOptions = {
+  fetch?: GotenbergFetch;
+};
+
+const DEFAULT_PDF_CONTENT_TYPE = "application/pdf";
+const TEST_HTML = "<!doctype html><html><body><h1>Cloud PDF renderer test</h1></body></html>";
+
+const byteLength = (value: string): number => new TextEncoder().encode(value).byteLength;
+
+const normalizeBaseUrl = (url: string): string => {
+  const trimmed = url.trim();
+  if (!trimmed) {
+    throw new GotenbergRenderError("not_configured", "Gotenberg URL is not configured.");
+  }
+
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.toString().replace(/\/+$/, "");
+  } catch {
+    throw new GotenbergRenderError("not_configured", "Gotenberg URL is invalid.");
+  }
+};
+
+const basicAuthHeader = (config: GotenbergConfig): string | null => {
+  const username = config.username?.trim() ?? "";
+  const password = config.password ?? "";
+  if (!username && !password) return null;
+  return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+};
+
+const abortSignal = (timeoutMs: number): AbortSignal => {
+  if (timeoutMs <= 0) {
+    throw new GotenbergRenderError("not_configured", "Gotenberg timeout must be greater than 0 ms.");
+  }
+  return AbortSignal.timeout(timeoutMs);
+};
+
+const sanitizeFetchError = (error: unknown): GotenbergRenderError => {
+  if (error instanceof GotenbergRenderError) return error;
+  if (error instanceof DOMException && error.name === "TimeoutError") {
+    return new GotenbergRenderError("timeout", "Gotenberg request timed out.");
+  }
+  if (error instanceof Error && error.name === "AbortError") {
+    return new GotenbergRenderError("timeout", "Gotenberg request timed out.");
+  }
+  return new GotenbergRenderError("request_failed", "Gotenberg request failed.");
+};
+
+export const renderHtmlToPdfWithConfig = async (
+  input: RenderHtmlToPdfInput,
+  config: GotenbergConfig,
+  options: RenderHtmlToPdfOptions = {},
+): Promise<RenderHtmlToPdfResult> => {
+  const htmlBytes = byteLength(input.html);
+  if (htmlBytes > config.maxHtmlBytes) {
+    throw new GotenbergRenderError("html_too_large", `HTML input is too large (${htmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`);
+  }
+
+  const baseUrl = normalizeBaseUrl(config.url);
+  const form = new FormData();
+  form.append("files", new Blob([input.html], { type: "text/html" }), "index.html");
+  if (input.headerHtml?.trim()) form.append("files", new Blob([input.headerHtml], { type: "text/html" }), "header.html");
+  if (input.footerHtml?.trim()) form.append("files", new Blob([input.footerHtml], { type: "text/html" }), "footer.html");
+  form.append("preferCssPageSize", "true");
+  form.append("printBackground", "true");
+
+  const headers = new Headers();
+  const authHeader = basicAuthHeader(config);
+  if (authHeader) headers.set("Authorization", authHeader);
+
+  const transport = options.fetch ?? fetch;
+  let response: Response;
+  try {
+    response = await transport(`${baseUrl}/forms/chromium/convert/html`, {
+      method: "POST",
+      headers,
+      body: form,
+      signal: abortSignal(config.timeoutMs),
+    });
+  } catch (error) {
+    throw sanitizeFetchError(error);
+  }
+
+  if (!response.ok) {
+    throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
+  }
+
+  const buffer = await response.arrayBuffer();
+  if (buffer.byteLength > config.maxPdfBytes) {
+    throw new GotenbergRenderError(
+      "pdf_too_large",
+      `PDF output is too large (${buffer.byteLength} bytes, limit ${config.maxPdfBytes} bytes).`,
+    );
+  }
+
+  return {
+    pdf: new Uint8Array(buffer),
+    contentType: response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE,
+  };
+};
+
+export const renderFacturXHtmlToPdfWithConfig = async (
+  input: RenderFacturXHtmlToPdfInput,
+  config: GotenbergConfig,
+  options: RenderHtmlToPdfOptions = {},
+): Promise<RenderHtmlToPdfResult> => {
+  const htmlBytes = byteLength(input.html);
+  const xmlBytes = byteLength(input.xml);
+  if (htmlBytes > config.maxHtmlBytes) {
+    throw new GotenbergRenderError("html_too_large", `HTML input is too large (${htmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`);
+  }
+  if (xmlBytes === 0 || xmlBytes > config.maxHtmlBytes) {
+    throw new GotenbergRenderError(
+      xmlBytes === 0 ? "bad_input" : "html_too_large",
+      xmlBytes === 0
+        ? "Factur-X XML must not be empty."
+        : `Factur-X XML input is too large (${xmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`,
+    );
+  }
+
+  const baseUrl = normalizeBaseUrl(config.url);
+  const form = new FormData();
+  form.append("files", new Blob([input.html], { type: "text/html" }), "index.html");
+  if (input.headerHtml?.trim()) form.append("files", new Blob([input.headerHtml], { type: "text/html" }), "header.html");
+  if (input.footerHtml?.trim()) form.append("files", new Blob([input.footerHtml], { type: "text/html" }), "footer.html");
+  form.append("facturxXml", new Blob([input.xml], { type: "application/xml" }), "factur-x.xml");
+  form.append("facturxConformanceLevel", input.conformanceLevel ?? "EN 16931");
+  form.append("facturxDocumentType", input.documentType ?? "INVOICE");
+  form.append("facturxVersion", input.facturXVersion ?? "1.0");
+  form.append("pdfa", "PDF/A-3b");
+  form.append("preferCssPageSize", "true");
+  form.append("printBackground", "true");
+
+  const headers = new Headers();
+  const authHeader = basicAuthHeader(config);
+  if (authHeader) headers.set("Authorization", authHeader);
+  let response: Response;
+  try {
+    response = await (options.fetch ?? fetch)(`${baseUrl}/forms/chromium/convert/html`, {
+      method: "POST",
+      headers,
+      body: form,
+      signal: abortSignal(config.timeoutMs),
+    });
+  } catch (error) {
+    throw sanitizeFetchError(error);
+  }
+  if (!response.ok) throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
+  const buffer = await response.arrayBuffer();
+  if (buffer.byteLength > config.maxPdfBytes) {
+    throw new GotenbergRenderError("pdf_too_large", `PDF output is too large (${buffer.byteLength} bytes, limit ${config.maxPdfBytes} bytes).`);
+  }
+  return { pdf: new Uint8Array(buffer), contentType: response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE };
+};
+
+export const mergePdfsWithConfig = async (
+  input: MergePdfsInput,
+  config: GotenbergConfig,
+  options: RenderHtmlToPdfOptions = {},
+): Promise<RenderHtmlToPdfResult> => {
+  if (input.files.length === 0) {
+    throw new GotenbergRenderError("bad_input", "At least one PDF file is required.");
+  }
+
+  const baseUrl = normalizeBaseUrl(config.url);
+  const form = new FormData();
+  input.files.forEach((file, index) => {
+    const filename = `${String(index + 1).padStart(6, "0")}.pdf`;
+    const bytes = file.pdf.buffer.slice(file.pdf.byteOffset, file.pdf.byteOffset + file.pdf.byteLength) as ArrayBuffer;
+    form.append("files", new Blob([bytes], { type: DEFAULT_PDF_CONTENT_TYPE }), filename);
+  });
+
+  const headers = new Headers();
+  const authHeader = basicAuthHeader(config);
+  if (authHeader) headers.set("Authorization", authHeader);
+
+  const transport = options.fetch ?? fetch;
+  let response: Response;
+  try {
+    response = await transport(`${baseUrl}/forms/pdfengines/merge`, {
+      method: "POST",
+      headers,
+      body: form,
+      signal: abortSignal(config.timeoutMs),
+    });
+  } catch (error) {
+    throw sanitizeFetchError(error);
+  }
+
+  if (!response.ok) {
+    throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
+  }
+
+  const buffer = await response.arrayBuffer();
+  if (buffer.byteLength > config.maxPdfBytes) {
+    throw new GotenbergRenderError(
+      "pdf_too_large",
+      `PDF output is too large (${buffer.byteLength} bytes, limit ${config.maxPdfBytes} bytes).`,
+    );
+  }
+
+  return {
+    pdf: new Uint8Array(buffer),
+    contentType: response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE,
+  };
+};
+
+export const getGotenbergConfig = async (): Promise<GotenbergConfig> => ({
+  url: await settings.get<string>("gotenberg.url"),
+  username: await settings.get<string>("gotenberg.username"),
+  password: await settings.get<string>("gotenberg.password"),
+  timeoutMs: await settings.get<number>("gotenberg.timeout_ms"),
+  maxHtmlBytes: await settings.get<number>("gotenberg.max_html_bytes"),
+  maxPdfBytes: await settings.get<number>("gotenberg.max_pdf_bytes"),
+});
+
+export const renderHtmlToPdf = async (input: RenderHtmlToPdfInput, options: RenderHtmlToPdfOptions = {}): Promise<RenderHtmlToPdfResult> =>
+  renderHtmlToPdfWithConfig(input, await getGotenbergConfig(), options);
+
+export const renderFacturXHtmlToPdf = async (
+  input: RenderFacturXHtmlToPdfInput,
+  options: RenderHtmlToPdfOptions = {},
+): Promise<RenderHtmlToPdfResult> => renderFacturXHtmlToPdfWithConfig(input, await getGotenbergConfig(), options);
+
+export const mergePdfs = async (input: MergePdfsInput, options: RenderHtmlToPdfOptions = {}): Promise<RenderHtmlToPdfResult> =>
+  mergePdfsWithConfig(input, await getGotenbergConfig(), options);
+
+export const testGotenberg = async (options: RenderHtmlToPdfOptions = {}): Promise<{ bytes: number; contentType: string }> => {
+  const result = await renderHtmlToPdf({ html: TEST_HTML, filename: "index.html" }, options);
+  return { bytes: result.pdf.byteLength, contentType: result.contentType };
+};

package/src/services/pdf/index.ts

@@ -0,0 +1,43 @@
+export type {
+  GotenbergConfig,
+  GotenbergRenderErrorCode,
+  MergePdfsInput,
+  RenderFacturXHtmlToPdfInput,
+  RenderHtmlToPdfInput,
+  RenderHtmlToPdfOptions,
+  RenderHtmlToPdfResult,
+} from "./gotenberg";
+export {
+  GotenbergRenderError,
+  getGotenbergConfig,
+  mergePdfs,
+  mergePdfsWithConfig,
+  renderFacturXHtmlToPdf,
+  renderFacturXHtmlToPdfWithConfig,
+  renderHtmlToPdf,
+  renderHtmlToPdfWithConfig,
+  testGotenberg,
+} from "./gotenberg";
+export type {
+  RenderTemplatePdfPreviewInput,
+  RenderTemplatePdfPreviewOptions,
+  TemplatePdfPreviewError,
+  TemplatePdfPreviewPhase,
+  TemplatePdfPreviewResult,
+} from "./template-preview";
+export { renderTemplatePdfPreview } from "./template-preview";
+export type {
+  MarkdownPdfErrorCode,
+  MarkdownPdfTemplateId,
+  RenderMarkdownToPdfInput,
+  RenderMarkdownToPdfOptions,
+} from "./markdown";
+export {
+  buildMarkdownPdfHtml,
+  MARKDOWN_PDF_MAX_CUSTOM_CSS_BYTES,
+  MARKDOWN_PDF_MAX_MARKDOWN_BYTES,
+  MARKDOWN_PDF_TEMPLATE_IDS,
+  MarkdownPdfError,
+  renderMarkdownToPdf,
+  renderMarkdownToPdfWithConfig,
+} from "./markdown";