@hed-hog/core 0.0.400 → 0.0.402

package/src/pdf/pdf.module.ts

@@ -2,6 +2,7 @@ import { forwardRef, Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 
 import { SettingModule } from '../setting/setting.module';
+import { PdfDocumentService } from './document/pdf-document.service';
 import { PdfController } from './pdf.controller';
 import { PdfService } from './pdf.service';
 
@@ -10,8 +11,8 @@ import { PdfService } from './pdf.service';
     ConfigModule,
     forwardRef(() => SettingModule),
   ],
-  providers: [PdfService],
-  exports: [PdfService],
+  providers: [PdfService, PdfDocumentService],
+  exports: [PdfService, PdfDocumentService],
   controllers: [PdfController],
 })
 export class PdfModule {}

package/src/pdf/pdf.service.spec.ts

@@ -0,0 +1,131 @@
+import { ServiceUnavailableException } from '@nestjs/common';
+import { afterEach, describe, expect, it, jest } from '@jest/globals';
+
+import { PdfService, buildPdfPageOptions } from './pdf.service';
+
+/** O serviço só toca em SettingService/BrandAssetService fora do caminho de render. */
+const makeService = (env: Record<string, string> = {}): PdfService =>
+  new PdfService({} as any, {} as any, {
+    get: (key: string) => env[key],
+  } as any);
+
+describe('buildPdfPageOptions', () => {
+  // O contrato que protege ceia, certificado e material de aula: quem não passa
+  // nenhuma das opções novas tem que receber o mesmo objeto de antes delas
+  // existirem — a simples presença de `displayHeaderFooter` muda o resultado.
+  it('não acrescenta chave nenhuma quando só as opções antigas vêm', () => {
+    expect(buildPdfPageOptions({})).toEqual({
+      format: 'A4',
+      printBackground: true,
+      landscape: false,
+      margin: { top: '0', right: '0', bottom: '0', left: '0' },
+    });
+
+    expect(Object.keys(buildPdfPageOptions({ format: 'A4' })).sort()).toEqual([
+      'format',
+      'landscape',
+      'margin',
+      'printBackground',
+    ]);
+  });
+
+  it('troca format/landscape por width/height quando os dois vêm', () => {
+    const options = buildPdfPageOptions({ width: '1600px', height: '1131px' });
+
+    expect(options).toEqual({
+      width: '1600px',
+      height: '1131px',
+      printBackground: true,
+      margin: { top: '0', right: '0', bottom: '0', left: '0' },
+    });
+  });
+
+  // Com um template só, o Chromium volta a injetar o dele (URL e data) no outro.
+  it('preenche os dois templates quando o cabeçalho/rodapé é ligado', () => {
+    const options = buildPdfPageOptions({
+      displayHeaderFooter: true,
+      headerTemplate: '<div class="bar"></div>',
+    });
+
+    expect(options.displayHeaderFooter).toBe(true);
+    expect(options.headerTemplate).toBe('<div class="bar"></div>');
+    expect(options.footerTemplate).toBe('<span></span>');
+  });
+
+  it('ignora os templates enquanto displayHeaderFooter não for ligado', () => {
+    const options = buildPdfPageOptions({ footerTemplate: '<span></span>' });
+
+    expect(options).not.toHaveProperty('displayHeaderFooter');
+    expect(options).not.toHaveProperty('footerTemplate');
+  });
+
+  it('só repassa scale e pageRanges quando vêm', () => {
+    expect(buildPdfPageOptions({ scale: 0.9, pageRanges: '1-2' })).toMatchObject({
+      scale: 0.9,
+      pageRanges: '1-2',
+    });
+    expect(buildPdfPageOptions({})).not.toHaveProperty('scale');
+  });
+});
+
+describe('fila de renderização', () => {
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('segura o render acima do teto até uma vaga ser devolvida', async () => {
+    const service = makeService({ PDF_MAX_CONCURRENCY: '1' });
+    const releaseFirst = await (service as any).acquireRenderSlot('primeiro');
+
+    let liberado = false;
+    const second = (service as any)
+      .acquireRenderSlot('segundo')
+      .then((release: () => void) => {
+        liberado = true;
+        return release;
+      });
+
+    await new Promise((resolve) => process.nextTick(resolve));
+    expect(liberado).toBe(false);
+
+    releaseFirst();
+    const releaseSecond = await second;
+    expect(liberado).toBe(true);
+    releaseSecond();
+  });
+
+  it('responde 503 quando a espera na fila estoura', async () => {
+    jest.useFakeTimers();
+    const service = makeService({ PDF_MAX_CONCURRENCY: '1', PDF_QUEUE_WAIT_MS: '50' });
+    const release = await (service as any).acquireRenderSlot('primeiro');
+
+    const queued = (service as any).acquireRenderSlot('segundo');
+    const rejeicao = expect(queued).rejects.toBeInstanceOf(ServiceUnavailableException);
+
+    jest.advanceTimersByTime(50);
+    await rejeicao;
+
+    release();
+  });
+
+  // Liberar duas vezes (ex.: `finally` somado a um caminho de erro) não pode
+  // inflar a capacidade e deixar dois Chromium subirem juntos.
+  it('ignora a segunda liberação do mesmo render', async () => {
+    const service = makeService({ PDF_MAX_CONCURRENCY: '1' });
+    const release = await (service as any).acquireRenderSlot('primeiro');
+    release();
+    release();
+
+    const releaseSecond = await (service as any).acquireRenderSlot('segundo');
+
+    let terceiroEntrou = false;
+    void (service as any).acquireRenderSlot('terceiro').then(() => {
+      terceiroEntrou = true;
+    });
+
+    await new Promise((resolve) => process.nextTick(resolve));
+    expect(terceiroEntrou).toBe(false);
+
+    releaseSecond();
+  });
+});

package/src/pdf/pdf.service.ts

@@ -1,9 +1,21 @@
-import { Inject, Injectable, InternalServerErrorException, Logger, forwardRef } from '@nestjs/common';
+import {
+  Inject,
+  Injectable,
+  InternalServerErrorException,
+  Logger,
+  ServiceUnavailableException,
+  forwardRef,
+} from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 
 import { BrandAssetService } from '../setting/brand-asset.service';
 import { SettingService } from '../setting/setting.service';
 import { PdfAreaType, PdfThemeConfig } from './interfaces/pdf-theme-config.interface';
+import {
+  CommercialDocumentTheme,
+  CommercialProposalData,
+  commercialProposalTemplate,
+} from './templates/commercial-proposal.template';
 import { hcodeInstitutionalTemplate } from './templates/hcode-institutional.template';
 import { AreaDefaults, HCODE_DEFAULTS } from './themes/hcode.theme';
 
@@ -20,8 +32,46 @@ export interface PdfGenerateOptions {
   width?: string;
   /** Explicit CSS page size (e.g. '1131px'). Takes precedence over `format`/`landscape` when set. */
   height?: string;
+
+  /**
+   * Turns on Chromium's own per-page header and footer. This is the only way to
+   * get a repeating accent bar and a real page number: `counter(page)` resolves
+   * to nothing outside `@page` margin boxes, so a footer rendered as flow
+   * content (like `pdfFooter()` in ./components) prints an empty page slot.
+   *
+   * The templates are mini-documents, not part of the page: they start at
+   * `font-size: 0`, need their own `print-color-adjust: exact` to keep
+   * backgrounds, and only `<span class="pageNumber">` / `<span class="totalPages">`
+   * get substituted. Keep `margin.top`/`margin.bottom` larger than the templates,
+   * or the page content prints over them.
+   */
+  displayHeaderFooter?: boolean;
+  headerTemplate?: string;
+  footerTemplate?: string;
+
+  /** `page.setContent` wait condition. Defaults to 'networkidle'. */
+  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+  /** Ceiling for `page.setContent`, in ms. Defaults to Playwright's own (30s). */
+  timeoutMs?: number;
+  /**
+   * JS expression evaluated in the page after `setContent`; the snapshot waits
+   * until it is truthy. For HTML whose layout settles asynchronously (webfonts
+   * loaded via `document.fonts`, measuring scripts that run after them).
+   */
+  readyExpression?: string;
+  scale?: number;
+  pageRanges?: string;
+  /** Short identifier for the logs when a render fails or the queue saturates. */
+  label?: string;
 }
 
+/** A render waiting for a Chromium slot. */
+type QueuedRender = {
+  resolve: () => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -33,6 +83,55 @@ function parsePxSize(value: string | undefined, fallback: number): number {
   return match ? Math.round(Number(match[1])) : fallback;
 }
 
+const ZERO_MARGIN = { top: '0', right: '0', bottom: '0', left: '0' };
+
+/**
+ * With `displayHeaderFooter` on, a template left undefined makes Chromium fall
+ * back to its own — the page URL and the print date. The unused slot gets
+ * something deliberately empty instead.
+ */
+const EMPTY_TEMPLATE = '<span></span>';
+
+const DEFAULT_MAX_CONCURRENCY = 2;
+const DEFAULT_QUEUE_WAIT_MS = 30_000;
+
+/**
+ * Builds the object handed to `page.pdf()`.
+ *
+ * Assembled key by key on purpose: a caller that passes none of the optional
+ * fields has to get exactly the object `page.pdf()` received before they
+ * existed — Chromium changes behaviour on the mere presence of some of them
+ * (`displayHeaderFooter` with a single template filled in brings back its own
+ * URL/date footer).
+ */
+export function buildPdfPageOptions(options: PdfGenerateOptions): Record<string, unknown> {
+  const pdfOptions: Record<string, unknown> =
+    options.width && options.height
+      ? {
+          width: options.width,
+          height: options.height,
+          printBackground: options.printBackground ?? true,
+          margin: options.margin ?? ZERO_MARGIN,
+        }
+      : {
+          format: options.format ?? 'A4',
+          printBackground: options.printBackground ?? true,
+          landscape: options.landscape ?? false,
+          margin: options.margin ?? ZERO_MARGIN,
+        };
+
+  if (options.displayHeaderFooter) {
+    pdfOptions.displayHeaderFooter = true;
+    pdfOptions.headerTemplate = options.headerTemplate ?? EMPTY_TEMPLATE;
+    pdfOptions.footerTemplate = options.footerTemplate ?? EMPTY_TEMPLATE;
+  }
+
+  if (options.scale !== undefined) pdfOptions.scale = options.scale;
+  if (options.pageRanges) pdfOptions.pageRanges = options.pageRanges;
+
+  return pdfOptions;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Service
 // ─────────────────────────────────────────────────────────────────────────────
@@ -41,6 +140,10 @@ function parsePxSize(value: string | undefined, fallback: number): number {
 export class PdfService {
   private readonly logger = new Logger(PdfService.name);
 
+  /** Renders holding a Chromium right now, and the ones waiting for a slot. */
+  private activeRenders = 0;
+  private readonly renderQueue: QueuedRender[] = [];
+
   constructor(
     @Inject(forwardRef(() => SettingService))
     private readonly settingService: SettingService,
@@ -120,15 +223,136 @@ export class PdfService {
     }
   }
 
-  // ── HTML → PDF ────────────────────────────────────────────────────────────
+  /**
+   * Theme for commercial documents (proposals and the like): the area theme
+   * plus the legal footer, partner line and font stacks of the `pdf` group.
+   * The logo is embedded as a data URI so the render does not depend on the
+   * API reaching its own public URL.
+   */
+  async loadCommercialDocumentTheme(
+    area: PdfAreaType = 'training',
+  ): Promise<CommercialDocumentTheme> {
+    const base = await this.loadThemeConfig(area);
+
+    let values: Record<string, any> = {};
+    try {
+      values = await this.settingService.getSettingValues([
+        'pdf-legal-footer',
+        'pdf-partner-line',
+        'pdf-font-family',
+        'pdf-font-mono',
+      ]);
+    } catch {
+      this.logger.warn('Could not load commercial PDF settings – using defaults.');
+    }
+
+    const logoOverride = base.logoOverride
+      ? ((await this.brandAsset.fetchAsDataUri(base.logoOverride)) ?? base.logoOverride)
+      : '';
+
+    return {
+      ...base,
+      logoOverride,
+      legalFooter: String(values['pdf-legal-footer'] ?? '').trim(),
+      partnerLine: String(values['pdf-partner-line'] ?? '').trim(),
+      fontFamily: String(values['pdf-font-family'] ?? '').trim() || "'Inter', sans-serif",
+      fontMono: String(values['pdf-font-mono'] ?? '').trim() || "'JetBrains Mono', monospace",
+    };
+  }
 
   /**
-   * Renders an HTML string to a PDF buffer using Playwright/Chromium.
+   * Renders a commercial proposal with the installation's branding. Returns
+   * the HTML too, so the caller can keep the exact source of what was printed.
+   */
+  async renderCommercialProposal(
+    data: CommercialProposalData,
+    area: PdfAreaType = 'training',
+  ): Promise<{ html: string; buffer: Buffer }> {
+    const theme = await this.loadCommercialDocumentTheme(area);
+    const { html, pdfOptions } = commercialProposalTemplate(data, theme);
+    const buffer = await this.generatePdfFromHtml(html, pdfOptions);
+    return { html, buffer };
+  }
+
+  // ── Chromium runtime ──────────────────────────────────────────────────────
+
+  private get maxConcurrency(): number {
+    const raw = Number(this.configService.get<string>('PDF_MAX_CONCURRENCY'));
+    return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : DEFAULT_MAX_CONCURRENCY;
+  }
+
+  private get queueWaitMs(): number {
+    const raw = Number(this.configService.get<string>('PDF_QUEUE_WAIT_MS'));
+    return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : DEFAULT_QUEUE_WAIT_MS;
+  }
+
+  /**
+   * Every render launches a Chromium of its own, which costs a few hundred MB.
+   * The API pod is capped well below what a burst of simultaneous report
+   * downloads would ask for, and an OOM kill takes the whole API down — not
+   * just the PDF. So renders queue, and a queue that waits too long answers a
+   * retryable 503 instead of dragging the process down with it.
+   */
+  private async acquireRenderSlot(label?: string): Promise<() => void> {
+    if (this.activeRenders < this.maxConcurrency) {
+      this.activeRenders += 1;
+    } else {
+      await new Promise<void>((resolve, reject) => {
+        const entry: QueuedRender = {
+          resolve,
+          reject,
+          timer: setTimeout(() => {
+            const index = this.renderQueue.indexOf(entry);
+            if (index >= 0) this.renderQueue.splice(index, 1);
+            this.logger.warn(
+              `PDF render queue is saturated; gave up after ${this.queueWaitMs}ms${label ? ` (${label})` : ''}.`,
+            );
+            reject(
+              new ServiceUnavailableException(
+                'The server is busy rendering other documents. Try again in a moment.',
+              ),
+            );
+          }, this.queueWaitMs),
+        };
+        this.renderQueue.push(entry);
+      });
+      // Resolved by releaseRenderSlot, which hands its slot over without
+      // decrementing — the counter already accounts for this render.
+    }
+
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.releaseRenderSlot();
+    };
+  }
+
+  private releaseRenderSlot(): void {
+    const next = this.renderQueue.shift();
+    if (next) {
+      clearTimeout(next.timer);
+      next.resolve();
+      return;
+    }
+    this.activeRenders = Math.max(0, this.activeRenders - 1);
+  }
+
+  /**
+   * Opens a Chromium page with the HTML loaded and hands it to `run`, taking
+   * care of the slot, the viewport and the teardown.
    *
    * Uses dynamic `import()` via `new Function` to remain compatible with
    * CommonJS bundle output (same pattern as operations.service.ts).
    */
-  async generatePdfFromHtml(html: string, options: PdfGenerateOptions = {}): Promise<Buffer> {
+  private async renderWithChromium(
+    kind: 'PDF' | 'Image',
+    html: string,
+    options: PdfGenerateOptions,
+    run: (page: any) => Promise<any>,
+  ): Promise<Buffer> {
+    const release = await this.acquireRenderSlot(options.label);
+
     const executablePath = this.configService.get<string>('CHROMIUM_EXECUTABLE_PATH');
     const noSandbox = this.configService.get<string>('CHROMIUM_NO_SANDBOX') === 'true';
 
@@ -163,25 +387,17 @@ export class PdfService {
         width: parsePxSize(options.width, 794),
         height: parsePxSize(options.height, 1123),
       });
-      await page.setContent(html, { waitUntil: 'networkidle' });
-
-      const pdfBuffer = await page.pdf(
-        options.width && options.height
-          ? {
-              width: options.width,
-              height: options.height,
-              printBackground: options.printBackground ?? true,
-              margin: options.margin ?? { top: '0', right: '0', bottom: '0', left: '0' },
-            }
-          : {
-              format: options.format ?? 'A4',
-              printBackground: options.printBackground ?? true,
-              landscape: options.landscape ?? false,
-              margin: options.margin ?? { top: '0', right: '0', bottom: '0', left: '0' },
-            },
-      );
+      await page.setContent(html, {
+        waitUntil: options.waitUntil ?? 'networkidle',
+        ...(options.timeoutMs ? { timeout: options.timeoutMs } : {}),
+      });
+      if (options.readyExpression) {
+        await page.waitForFunction(options.readyExpression, undefined, {
+          ...(options.timeoutMs ? { timeout: options.timeoutMs } : {}),
+        });
+      }
 
-      return Buffer.from(pdfBuffer);
+      return Buffer.from(await run(page));
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       const errorStack = error instanceof Error ? (error.stack ?? errorMessage) : String(error);
@@ -191,7 +407,7 @@ export class PdfService {
           errorMessage,
         );
 
-      this.logger.error(`PDF generation failed. ${errorMessage}`, errorStack);
+      this.logger.error(`${kind} generation failed. ${errorMessage}`, errorStack);
 
       if (missingRuntime) {
         throw new InternalServerErrorException(
@@ -199,7 +415,7 @@ export class PdfService {
         );
       }
 
-      throw new InternalServerErrorException(`PDF generation failed: ${errorMessage}`);
+      throw new InternalServerErrorException(`${kind} generation failed: ${errorMessage}`);
     } finally {
       if (browser) {
         try {
@@ -208,9 +424,21 @@ export class PdfService {
           // Ignore close errors
         }
       }
+      release();
     }
   }
 
+  // ── HTML → PDF ────────────────────────────────────────────────────────────
+
+  /**
+   * Renders an HTML string to a PDF buffer using Playwright/Chromium.
+   */
+  async generatePdfFromHtml(html: string, options: PdfGenerateOptions = {}): Promise<Buffer> {
+    const pdfOptions = buildPdfPageOptions(options);
+
+    return this.renderWithChromium('PDF', html, options, (page) => page.pdf(pdfOptions));
+  }
+
   // ── HTML → PNG image ──────────────────────────────────────────────────────
 
   /**
@@ -221,69 +449,15 @@ export class PdfService {
    * certificate thumbnails on the web/app.
    */
   async generateImageFromHtml(html: string, options: PdfGenerateOptions = {}): Promise<Buffer> {
-    const executablePath = this.configService.get<string>('CHROMIUM_EXECUTABLE_PATH');
-    const noSandbox = this.configService.get<string>('CHROMIUM_NO_SANDBOX') === 'true';
-
-    const launchArgs = noSandbox
-      ? ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage']
-      : [];
-
     const width = parsePxSize(options.width, 794);
     const height = parsePxSize(options.height, 1123);
 
-    let browser: any = null;
-
-    try {
-      const importPlaywright = new Function(
-        'moduleName',
-        'return import(moduleName);',
-      ) as (moduleName: string) => Promise<any>;
-
-      const playwright = await importPlaywright('playwright');
-
-      browser = await playwright.chromium.launch({
-        headless: true,
-        ...(executablePath ? { executablePath } : {}),
-        args: launchArgs,
-      });
-
-      const page = await browser.newPage();
-      await page.setViewportSize({ width, height });
-      await page.setContent(html, { waitUntil: 'networkidle' });
-
-      const imageBuffer = await page.screenshot({
+    return this.renderWithChromium('Image', html, options, (page) =>
+      page.screenshot({
         type: 'png',
         clip: { x: 0, y: 0, width, height },
-      });
-
-      return Buffer.from(imageBuffer);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      const errorStack = error instanceof Error ? (error.stack ?? errorMessage) : String(error);
-
-      const missingRuntime =
-        /Cannot find package ['"]playwright['"]|Cannot find module ['"]playwright['"]|Executable doesn't exist|browserType\.launch|Failed to launch|Please run the following command/i.test(
-          errorMessage,
-        );
-
-      this.logger.error(`Image generation failed. ${errorMessage}`, errorStack);
-
-      if (missingRuntime) {
-        throw new InternalServerErrorException(
-          'Playwright runtime is not available. Run `pnpm --filter api run playwright:install` in the API environment.',
-        );
-      }
-
-      throw new InternalServerErrorException(`Image generation failed: ${errorMessage}`);
-    } finally {
-      if (browser) {
-        try {
-          await browser.close();
-        } catch {
-          // Ignore close errors
-        }
-      }
-    }
+      }),
+    );
   }
 
   // ── Template engine ───────────────────────────────────────────────────────