@oondemand/oon-core-back 0.4.6 → 0.4.8

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@oondemand/oon-core-back",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",
     "directory": "packages/oonCore-back"
   },
-  "description": "Core runtime para Centrais Oon: Model Registry, CRUD/RBAC automáticos, módulos opinativos (Omie, Assistentes, Multi-moedas, Esteiras, Documentos) e deploy embutido.",
+  "description": "Core runtime para Centrais Oon: Model Registry, CRUD/RBAC automáticos, módulos opinativos e capabilities nativas.",
   "main": "src/index.js",
   "bin": {
     "oonCore-back": "bin/cli.js",
@@ -29,7 +29,8 @@
     "central",
     "model-registry",
     "express",
-    "mongoose"
+    "mongoose",
+    "capabilities"
   ],
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {

package/src/capabilities/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+const pdfRendering = require("./pdfRendering");
+
+const pdf = Object.freeze({ render: pdfRendering.render });
+
+module.exports = Object.freeze({
+  pdf,
+  pdfRendering: pdf,
+  configurePdfRendering: pdfRendering.configurePdfRendering,
+  PdfRenderingError: pdfRendering.PdfRenderingError,
+});

package/src/capabilities/pdfRendering.js

@@ -0,0 +1,188 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const GenericError = require("../core/errors/GenericError");
+
+const PAPER = Object.freeze({
+  A3: [11.7, 16.5],
+  A4: [8.27, 11.7],
+  A5: [5.83, 8.27],
+  Letter: [8.5, 11],
+  Legal: [8.5, 14],
+});
+
+class PdfRenderingError extends GenericError {
+  constructor(message, { code = "PDF_RENDERING_ERROR", statusCode = 502, retryable = true, details } = {}) {
+    super(message, { code, statusCode, details });
+    this.name = "PdfRenderingError";
+    this.retryable = retryable;
+  }
+}
+
+function numberLimit(name, fallback) {
+  const value = Number(process.env[name] || fallback);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function sanitizeOptions(options = {}) {
+  const allowed = new Set(["html", "format", "landscape", "marginTop", "marginBottom", "marginLeft", "marginRight", "printBackground", "timeoutMs"]);
+  for (const key of Object.keys(options)) {
+    if (!allowed.has(key)) throw new PdfRenderingError(`Opção PDF não suportada: ${key}.`, {
+      code: "PDF_RENDERING_INVALID_OPTIONS", statusCode: 422, retryable: false,
+    });
+  }
+  const format = options.format || "A4";
+  if (!PAPER[format]) throw new PdfRenderingError(`Formato PDF não suportado: ${format}.`, {
+    code: "PDF_RENDERING_INVALID_OPTIONS", statusCode: 422, retryable: false,
+  });
+  const margin = (key, fallback) => {
+    const value = Number(options[key] ?? fallback);
+    if (!Number.isFinite(value) || value < 0 || value > 4) throw new PdfRenderingError(`${key} deve estar entre 0 e 4 polegadas.`, {
+      code: "PDF_RENDERING_INVALID_OPTIONS", statusCode: 422, retryable: false,
+    });
+    return value;
+  };
+  return {
+    format,
+    landscape: options.landscape === true,
+    marginTop: margin("marginTop", 0.39),
+    marginBottom: margin("marginBottom", 0.39),
+    marginLeft: margin("marginLeft", 0.39),
+    marginRight: margin("marginRight", 0.39),
+    printBackground: options.printBackground !== false,
+    timeoutMs: Math.min(numberLimit("OON_PDF_RENDERING_TIMEOUT_MAX_MS", 60_000), Math.max(1_000, Number(options.timeoutMs || 30_000))),
+  };
+}
+
+function pdfError(message, options) {
+  return new PdfRenderingError(message, options);
+}
+
+function providerConfig() {
+  const baseUrl = String(process.env.OON_CAPABILITY_PDF_RENDERING_URL || "").replace(/\/+$/, "");
+  if (!baseUrl) throw pdfError("A capability pdfRendering não está resolvida neste ambiente.", {
+    code: "PDF_RENDERING_UNAVAILABLE", statusCode: 503,
+  });
+  const username = String(process.env.OON_CAPABILITY_PDF_RENDERING_USERNAME || "");
+  const password = String(process.env.OON_CAPABILITY_PDF_RENDERING_PASSWORD || "");
+  if (!username || !password) throw pdfError("A credencial interna de pdfRendering não está disponível.", {
+    code: "PDF_RENDERING_CREDENTIAL_UNAVAILABLE", statusCode: 503,
+  });
+  return { baseUrl, username, password };
+}
+
+function validatePdf(input) {
+  const pdf = Buffer.isBuffer(input) ? input : Buffer.from(input || "");
+  const maxBytes = numberLimit("OON_PDF_RENDERING_MAX_OUTPUT_BYTES", 20 * 1024 * 1024);
+  if (pdf.length < 8 || pdf.length > maxBytes || !pdf.subarray(0, 5).equals(Buffer.from("%PDF-"))) {
+    throw pdfError("O provider retornou um PDF inválido ou acima do limite.", {
+      code: "PDF_RENDERING_INVALID_OUTPUT", details: { outputBytes: pdf.length, maxBytes },
+    });
+  }
+  return pdf;
+}
+
+function traceContext(context = {}) {
+  return {
+    correlationId: String(context.correlationId || context.requestId || crypto.randomUUID()).slice(0, 128),
+    tenantId: String(context.tenantId || "unknown").slice(0, 128),
+    appCode: String(context.appCode || process.env.APP_CODE || "unknown").slice(0, 128),
+    environment: String(context.environment || process.env.APP_ENVIRONMENT || "unknown").slice(0, 64),
+    integrationTicketId: String(context.integrationTicketId || "").slice(0, 128),
+  };
+}
+
+function formFor(html, options) {
+  const form = new FormData();
+  const [width, height] = PAPER[options.format];
+  form.append("files", new Blob([html], { type: "text/html; charset=utf-8" }), "index.html");
+  form.append("paperWidth", String(width));
+  form.append("paperHeight", String(height));
+  form.append("landscape", String(options.landscape));
+  form.append("marginTop", String(options.marginTop));
+  form.append("marginBottom", String(options.marginBottom));
+  form.append("marginLeft", String(options.marginLeft));
+  form.append("marginRight", String(options.marginRight));
+  form.append("printBackground", String(options.printBackground));
+  form.append("emulatedMediaType", "print");
+  return form;
+}
+
+function defaultTransport({ html, options, trace, signal, fetchImpl = globalThis.fetch }) {
+  const provider = providerConfig();
+  return fetchImpl(`${provider.baseUrl}/forms/chromium/convert/html`, {
+    method: "POST",
+    headers: {
+      authorization: `Basic ${Buffer.from(`${provider.username}:${provider.password}`).toString("base64")}`,
+      "Gotenberg-Trace": trace.correlationId,
+      "X-Oon-App-Code": trace.appCode,
+      "X-Oon-Environment": trace.environment,
+    },
+    body: formFor(html, options),
+    signal,
+  });
+}
+
+let configuredTransport = defaultTransport;
+let active = 0;
+const queue = [];
+
+async function acquire() {
+  const max = Math.max(1, Math.min(32, numberLimit("OON_PDF_RENDERING_CONCURRENCY", 4)));
+  const maxQueue = Math.max(0, Math.min(1000, numberLimit("OON_PDF_RENDERING_MAX_QUEUE", 20)));
+  if (active < max) { active += 1; return; }
+  if (queue.length >= maxQueue) throw pdfError("A fila de pdfRendering está saturada.", {
+    code: "PDF_RENDERING_SATURATED", statusCode: 503,
+  });
+  await new Promise((resolve) => queue.push(resolve));
+  active += 1;
+}
+
+function release() {
+  active = Math.max(0, active - 1);
+  queue.shift()?.();
+}
+
+async function render(input = {}, context = {}) {
+  const html = String(input.html || "");
+  const maxInput = numberLimit("OON_PDF_RENDERING_MAX_INPUT_BYTES", 2 * 1024 * 1024);
+  const inputBytes = Buffer.byteLength(html);
+  if (!html.trim() || inputBytes > maxInput) throw pdfError("HTML ausente ou acima do limite de pdfRendering.", {
+    code: "PDF_RENDERING_INVALID_INPUT", statusCode: 422, retryable: false,
+    details: { inputBytes, maxInput },
+  });
+  const options = sanitizeOptions(input);
+  const trace = traceContext(context);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error("timeout")), options.timeoutMs);
+  const abort = () => controller.abort(context.signal.reason);
+  context.signal?.addEventListener?.("abort", abort, { once: true });
+  const startedAt = Date.now();
+  await acquire();
+  try {
+    const response = await configuredTransport({ html, options, trace, signal: controller.signal, fetchImpl: context.fetchImpl });
+    if (!response?.ok) throw pdfError(`Provider de pdfRendering indisponível (HTTP ${response?.status || 502}).`, {
+      code: "PDF_RENDERING_PROVIDER_ERROR", statusCode: 502,
+    });
+    const pdf = validatePdf(Buffer.from(await response.arrayBuffer()));
+    console.info(JSON.stringify({ event: "pdfRendering.completed", ...trace, durationMs: Date.now() - startedAt, inputBytes, outputBytes: pdf.length, providerVersion: process.env.OON_CAPABILITY_PDF_RENDERING_VERSION || "unknown" }));
+    return pdf;
+  } catch (error) {
+    const normalized = error instanceof PdfRenderingError ? error : pdfError(
+      controller.signal.aborted ? "Tempo limite excedido em pdfRendering." : "Falha transitória ao renderizar PDF.",
+      { code: controller.signal.aborted ? "PDF_RENDERING_TIMEOUT" : "PDF_RENDERING_TRANSPORT_ERROR", statusCode: 503 },
+    );
+    console.error(JSON.stringify({ event: "pdfRendering.failed", ...trace, durationMs: Date.now() - startedAt, inputBytes, code: normalized.code }));
+    throw normalized;
+  } finally {
+    clearTimeout(timer);
+    context.signal?.removeEventListener?.("abort", abort);
+    release();
+  }
+}
+
+function configurePdfRendering({ transport } = {}) {
+  configuredTransport = transport || defaultTransport;
+}
+
+module.exports = { PdfRenderingError, configurePdfRendering, render, sanitizeOptions, validatePdf };

package/src/deploy/contracts/deploy-contract.js

@@ -9,6 +9,7 @@ const SUPPORTED_MAJOR = 1;
 const RUNTIMES = ["ooncore-node-react"];
 const RESOURCE_PROFILES = ["nano", "small", "medium", "large"];
 const REQUIRED = ["schemaVersion", "appCode", "runtime", "components", "resourceProfile", "health"];
+const ROOT_FIELDS = [...REQUIRED, "capabilities"];
 const COMPONENTS = ["backend", "frontend"];
 const HEALTH = ["livePath", "readyPath", "versionPath"];
 
@@ -49,6 +50,29 @@ function noExtra(object, allowed, base, issues) {
   }
 }
 
+function validateCapabilities(capabilities, issues) {
+  if (capabilities === undefined) return;
+  if (!capabilities || typeof capabilities !== "object" || Array.isArray(capabilities)) {
+    issues.push(toIssue("$.capabilities", "capabilities deve ser um objeto."));
+    return;
+  }
+  for (const [name, requirement] of Object.entries(capabilities)) {
+    const base = `$.capabilities.${name}`;
+    if (!/^[a-z][A-Za-z0-9]{1,63}$/.test(name)) issues.push(toIssue(base, "Nome de capability inválido."));
+    if (!requirement || typeof requirement !== "object" || Array.isArray(requirement)) {
+      issues.push(toIssue(base, "Requisito da capability deve ser um objeto."));
+      continue;
+    }
+    noExtra(requirement, ["required", "minVersion"], base, issues);
+    if (requirement.required !== undefined && typeof requirement.required !== "boolean") {
+      issues.push(toIssue(`${base}.required`, "required deve ser booleano."));
+    }
+    if (requirement.minVersion !== undefined && majorOf(requirement.minVersion) === null) {
+      issues.push(toIssue(`${base}.minVersion`, "minVersion deve seguir semver."));
+    }
+  }
+}
+
 function validateDeployContract(manifest) {
   const issues = [];
   if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
@@ -57,15 +81,12 @@ function validateDeployContract(manifest) {
     const major = majorOf(manifest.schemaVersion);
     if (major === null) issues.push(toIssue("$.schemaVersion", "schemaVersion deve seguir semver."));
     else if (major !== SUPPORTED_MAJOR) throw new ContractError("UNSUPPORTED_CONTRACT_VERSION", `Major não suportado: ${manifest.schemaVersion}. Migre para 1.x.`, { path: "$.schemaVersion" });
-
     REQUIRED.forEach((key) => { if (manifest[key] === undefined) issues.push(toIssue(`$.${key}`, "Campo obrigatório ausente.")); });
-    noExtra(manifest, REQUIRED, "$", issues);
+    noExtra(manifest, ROOT_FIELDS, "$", issues);
     walkSecrets(manifest, "$", issues);
-
     if (manifest.appCode !== undefined && !/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(manifest.appCode)) issues.push(toIssue("$.appCode", "appCode deve ser compatível com DNS/Kubernetes."));
     if (manifest.runtime !== undefined && !RUNTIMES.includes(manifest.runtime)) issues.push(toIssue("$.runtime", "Runtime não suportado."));
     if (manifest.resourceProfile !== undefined && !RESOURCE_PROFILES.includes(manifest.resourceProfile)) issues.push(toIssue("$.resourceProfile", "Perfil de recursos não suportado."));
-
     if (manifest.components && typeof manifest.components === "object" && !Array.isArray(manifest.components)) {
       noExtra(manifest.components, COMPONENTS, "$.components", issues);
       COMPONENTS.forEach((name) => {
@@ -77,13 +98,13 @@ function validateDeployContract(manifest) {
         }
       });
     } else if (manifest.components !== undefined) issues.push(toIssue("$.components", "components deve ser um objeto."));
-
     if (manifest.health && typeof manifest.health === "object" && !Array.isArray(manifest.health)) {
       noExtra(manifest.health, HEALTH, "$.health", issues);
       HEALTH.forEach((key) => {
         if (typeof manifest.health[key] !== "string" || !manifest.health[key].startsWith("/")) issues.push(toIssue(`$.health.${key}`, "Health path deve iniciar por /."));
       });
     } else if (manifest.health !== undefined) issues.push(toIssue("$.health", "health deve ser um objeto."));
+    validateCapabilities(manifest.capabilities, issues);
   }
   if (issues.length) throw new ContractError("SCHEMA_VALIDATION_ERROR", "oon.deploy.json inválido.", { details: issues });
   return { ok: true, contract: CONTRACT, version: manifest.schemaVersion, manifest };
@@ -93,4 +114,4 @@ function validateDeployFile(file = path.join(process.cwd(), "oon.deploy.json"))
   return validateDeployContract(readJsonFile(file));
 }
 
-module.exports = { validateDeployContract, validateDeployFile, readJsonFile, RUNTIMES, RESOURCE_PROFILES };
+module.exports = { validateDeployContract, validateDeployFile, validateCapabilities, readJsonFile, RUNTIMES, RESOURCE_PROFILES };

package/src/index.js

@@ -12,6 +12,7 @@ const { requirePermission } = require("./core/middlewares/permissions");
 const rbacPolicy = require("./core/rbac/policy");
 const omieModule = require("./modules/omie");
 const integrations = require("./modules/integrations");
+const capabilities = require("./capabilities");
 const appManifest = require("./manifest/appManifest");
 const domainManifest = require("./manifest/domainManifest");
 const domainRules = require("./manifest/domainRules");
@@ -20,35 +21,20 @@ const processRuntime = require("./manifest/processRuntime");
 const referencePolicies = require("./manifest/referencePolicies");
 
 module.exports = {
-  start,
-  createApp,
-  activate,
-  defineCentral: define.defineCentral,
-  defineModel: define.defineModel,
-  defineCollection: define.defineCollection,
-  defineDocument: define.defineDocument,
-  definePipeline: define.definePipeline,
-  defineOmieMapping: define.defineOmieMapping,
-  defineRoutes: define.defineRoutes,
-  defineValidation: define.defineValidation,
+  start, createApp, activate,
+  defineCentral: define.defineCentral, defineModel: define.defineModel,
+  defineCollection: define.defineCollection, defineDocument: define.defineDocument,
+  definePipeline: define.definePipeline, defineOmieMapping: define.defineOmieMapping,
+  defineRoutes: define.defineRoutes, defineValidation: define.defineValidation,
   defineTrigger: define.defineTrigger,
-
-  requirePermission,
-  CORE_PERMISSIONS: rbacPolicy.CORE_PERMISSIONS,
-  rbacPolicy: rbacPolicy.policy,
-  roleByCode: rbacPolicy.roleByCode,
+  requirePermission, CORE_PERMISSIONS: rbacPolicy.CORE_PERMISSIONS,
+  rbacPolicy: rbacPolicy.policy, roleByCode: rbacPolicy.roleByCode,
   permissionGranted: rbacPolicy.granted,
-
-  TENANT_HEADER: tenancy.TENANT_HEADER,
-  TENANCY_MODELS: tenancy.TENANCY_MODELS,
-  DATA_SCOPES: tenancy.DATA_SCOPES,
-  createAccessContext: tenancy.createAccessContext,
-  readRequestedTenantId: tenancy.readRequestedTenantId,
-  scopeFilter: tenancy.scopeFilter,
-  mergeScopedFilter: tenancy.mergeScopedFilter,
-  scopeMutation: tenancy.scopeMutation,
+  TENANT_HEADER: tenancy.TENANT_HEADER, TENANCY_MODELS: tenancy.TENANCY_MODELS,
+  DATA_SCOPES: tenancy.DATA_SCOPES, createAccessContext: tenancy.createAccessContext,
+  readRequestedTenantId: tenancy.readRequestedTenantId, scopeFilter: tenancy.scopeFilter,
+  mergeScopedFilter: tenancy.mergeScopedFilter, scopeMutation: tenancy.scopeMutation,
   scopedIdFilter: tenancy.scopedIdFilter,
-
   APP_MANIFEST_FILENAME: appManifest.APP_MANIFEST_FILENAME,
   APP_MANIFEST_SCHEMA_VERSION: appManifest.APP_MANIFEST_SCHEMA_VERSION,
   SUPPORTED_APP_KINDS: appManifest.SUPPORTED_APP_KINDS,
@@ -59,7 +45,6 @@ module.exports = {
   appManifestToConfig: appManifest.appManifestToConfig,
   registerAppManifest: appManifest.registerAppManifest,
   loadAppManifest: appManifest.loadAppManifest,
-
   DOMAIN_MANIFEST_FILENAME: domainManifest.DOMAIN_MANIFEST_FILENAME,
   DOMAIN_MANIFEST_SCHEMA_VERSION: domainManifest.DOMAIN_MANIFEST_SCHEMA_VERSION,
   SUPPORTED_DOMAIN_FIELD_KINDS: domainManifest.SUPPORTED_FIELD_KINDS,
@@ -74,7 +59,6 @@ module.exports = {
   applyDomainMutation: domainRules.applyDomainMutation,
   validateDomainRecord: domainRules.validateDomainRecord,
   detectChangedFields: domainRules.detectChangedFields,
-
   PROCESS_MANIFEST_FILENAME: processManifest.PROCESS_MANIFEST_FILENAME,
   PROCESS_MANIFEST_SCHEMA_VERSION: processManifest.PROCESS_MANIFEST_SCHEMA_VERSION,
   ProcessManifestError: processManifest.ProcessManifestError,
@@ -88,10 +72,7 @@ module.exports = {
   assertDeleteAllowed: processRuntime.assertDeleteAllowed,
   recalculateDependents: processRuntime.recalculateDependents,
   drainProcessJobs: processRuntime.drainProcessJobs,
-
-  fields,
-  omie: omieModule.omie,
-  omieModule,
+  fields, omie: omieModule.omie, omieModule,
   createOmieClient: omieModule.createOmieClient,
   OmieApiError: omieModule.OmieApiError,
   enqueueOmieCall: omieModule.enqueueOmieCall,
@@ -101,10 +82,10 @@ module.exports = {
   saveOmieConfiguration: omieModule.saveOmieConfiguration,
   listOmieConfigurations: omieModule.listOmieConfigurations,
   testOmieConnection: omieModule.testOmieConnection,
-  integrations,
-  registerIntegrationProvider: integrations.registerIntegrationProvider,
+  integrations, registerIntegrationProvider: integrations.registerIntegrationProvider,
   enqueueIntegration: integrations.enqueueIntegration,
   receiveIntegrationWebhook: integrations.receiveWebhook,
-  GenericError,
-  registry,
+  capabilities,
+  PdfRenderingError: capabilities.PdfRenderingError,
+  GenericError, registry,
 };