@oondemand/oon-core-back 0.7.17 → 0.7.20

package/src/manifest/appManifest.js

@@ -5,6 +5,7 @@ const path = require("node:path");
 const ctx = require("../core/context");
 const corePackage = require("../../package.json");
 const { validateRbac } = require("./rbacManifest");
+const { validateUsageMetrics } = require("./usageMetrics");
 const { deriveDeploymentMode, resolveAppArchitecture } = require("./appArchitecture");
 
 const APP_MANIFEST_FILENAME = "central.app.json";
@@ -214,7 +215,7 @@ function validateAppManifest(input, { coreVersion = corePackage.version } = {})
   const allowedTopLevel = new Set([
     "$schema", "schemaVersion", "id", "name", "slug", "appKind",
     "tenancyModel", "availability", "accessMode", "authorizationMode", "deploymentMode",
-    "modules", "capabilities", "capabilitySettings", "compatibility", "activation", "auth", "rbac",
+    "modules", "capabilities", "capabilitySettings", "compatibility", "activation", "auth", "rbac", "usageMetrics",
   ]);
   for (const key of Object.keys(input)) {
     if (!allowedTopLevel.has(key)) addIssue(issues, key, "propriedade não suportada.");
@@ -315,6 +316,7 @@ function validateAppManifest(input, { coreVersion = corePackage.version } = {})
     }
   }
   validateRbac(input.rbac, issues);
+  validateUsageMetrics(input.usageMetrics, issues);
   if (issues.length) throw new AppManifestError("central.app.json inválido.", issues);
   return JSON.parse(JSON.stringify(input));
 }
@@ -350,6 +352,7 @@ function appManifestToConfig(manifest, manifestPath) {
     capabilitySettings: JSON.parse(JSON.stringify(manifest.capabilitySettings || {})),
     auth: manifest.auth ? JSON.parse(JSON.stringify(manifest.auth)) : undefined,
     rbac: manifest.rbac ? JSON.parse(JSON.stringify(manifest.rbac)) : undefined,
+    usageMetrics: manifest.usageMetrics ? JSON.parse(JSON.stringify(manifest.usageMetrics)) : [],
     appManifest: manifest,
     appManifestPath: manifestPath,
   };

package/src/manifest/processJobs.js

@@ -0,0 +1,252 @@
+"use strict";
+
+/**
+ * Fila persistida dos recálculos assíncronos (`recalculate: "async"`).
+ *
+ * Antes a fila ficava só na memória do processo: tarefas pendentes se perdiam
+ * quando a réplica reiniciava, e duas réplicas podiam recalcular o mesmo
+ * registro ao mesmo tempo. Agora:
+ * - cada tarefa é um documento em `oon_process_jobs`; dentro de uma transação
+ *   de domínio ela é gravada na mesma sessão, então só existe se a mudança que
+ *   a originou for confirmada;
+ * - uma réplica reserva a tarefa com lease (como o worker de e-mail) e, se o
+ *   processo morrer, outra réplica a retoma quando o lease expira;
+ * - uma trava por alvo (`oon_process_job_locks`) impede duas réplicas de
+ *   recalcular o mesmo conjunto de registros ao mesmo tempo;
+ * - tarefas pendentes iguais, já visíveis quando o recálculo começa, são
+ *   cobertas por ele e removidas juntas (deduplicação).
+ */
+const crypto = require("node:crypto");
+const mongoose = require("../core/database/mongoose");
+
+const JOBS = "oon_process_jobs";
+const LOCKS = "oon_process_job_locks";
+const LEASE_MS = 60000;
+const MAX_ATTEMPTS = 5;
+const TICK_MS = 1000;
+
+const state = {
+  owner: `${process.pid}:${crypto.randomUUID()}`,
+  running: false,
+  timer: null,
+  inFlight: null,
+  ready: null,
+};
+
+function stableValue(value) {
+  if (value === null || value === undefined) return value ?? null;
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object") {
+    if (typeof value.toHexString === "function") return value.toHexString();
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+  }
+  return value;
+}
+
+function dedupeKey(modelName, selectors, accessContext) {
+  const material = JSON.stringify(stableValue({ modelName, selectors, accessContext: accessContext || null }));
+  return crypto.createHash("sha256").update(material).digest("hex");
+}
+
+function db(connection = mongoose.connection) {
+  return connection?.readyState === 1 ? connection : null;
+}
+
+async function ensureReady(connection = db()) {
+  if (!connection) return false;
+  if (!state.ready) {
+    state.ready = Promise.all([
+      connection.collection(JOBS).createIndex({ status: 1, nextRunAt: 1 }),
+      connection.collection(JOBS).createIndex({ dedupeKey: 1, status: 1 }),
+      connection.collection(LOCKS).createIndex({ expiresAt: 1 }),
+    ]).catch((error) => {
+      state.ready = null;
+      throw error;
+    });
+  }
+  await state.ready;
+  return true;
+}
+
+function available() {
+  return Boolean(db());
+}
+
+async function enqueue({ modelName, selectors, accessContext, session } = {}) {
+  const connection = db();
+  if (!connection) throw new Error("Fila persistida indisponível sem conexão com o banco.");
+  // Índices e coleção são criados fora da transação; dentro dela só o insert.
+  await ensureReady(connection);
+  const now = new Date();
+  await connection.collection(JOBS).insertOne({
+    model: modelName,
+    selectors,
+    accessContext: accessContext || null,
+    dedupeKey: dedupeKey(modelName, selectors, accessContext),
+    status: "pending",
+    attempts: 0,
+    nextRunAt: now,
+    createdAt: now,
+  }, session ? { session } : {});
+  if (!session) kick();
+}
+
+async function lease(connection) {
+  const now = new Date();
+  const result = await connection.collection(JOBS).findOneAndUpdate(
+    {
+      $or: [
+        { status: "pending", nextRunAt: { $lte: now } },
+        { status: "processing", leaseExpiresAt: { $lte: now } },
+      ],
+    },
+    {
+      $set: { status: "processing", leaseOwner: state.owner, leaseExpiresAt: new Date(now.getTime() + LEASE_MS) },
+      $inc: { attempts: 1 },
+    },
+    { sort: { nextRunAt: 1, createdAt: 1 }, returnDocument: "after" },
+  );
+  return result && Object.hasOwn(result, "value") ? result.value : result;
+}
+
+async function acquireLock(connection, key) {
+  const locks = connection.collection(LOCKS);
+  const expiresAt = new Date(Date.now() + LEASE_MS);
+  try {
+    await locks.insertOne({ _id: key, owner: state.owner, expiresAt });
+    return true;
+  } catch (error) {
+    if (error?.code !== 11000) throw error;
+  }
+  const takeover = await locks.updateOne(
+    { _id: key, expiresAt: { $lte: new Date() } },
+    { $set: { owner: state.owner, expiresAt } },
+  );
+  return Number(takeover?.modifiedCount || 0) > 0;
+}
+
+async function releaseLock(connection, key) {
+  await connection.collection(LOCKS).deleteOne({ _id: key, owner: state.owner });
+}
+
+function backoff(attempts) {
+  return Math.min(300000, 1000 * (2 ** Math.max(0, attempts - 1)));
+}
+
+/**
+ * Processa uma tarefa. Retorna `false` quando não há tarefa disponível agora.
+ * `run(modelName, selectors, accessContext)` executa o recálculo.
+ */
+async function processOne(run, connection = db()) {
+  if (!connection) return false;
+  await ensureReady(connection);
+  const jobs = connection.collection(JOBS);
+  const job = await lease(connection);
+  if (!job) return false;
+
+  if (!await acquireLock(connection, job.dedupeKey)) {
+    // Outra réplica está recalculando o mesmo alvo: tenta de novo em seguida.
+    await jobs.updateOne(
+      { _id: job._id, leaseOwner: state.owner },
+      { $set: { status: "pending", nextRunAt: new Date(Date.now() + 500) }, $unset: { leaseOwner: "", leaseExpiresAt: "" }, $inc: { attempts: -1 } },
+    );
+    return true;
+  }
+  try {
+    // Pendentes iguais já visíveis agora são cobertas por este recálculo, que lê o estado atual.
+    const siblings = await jobs.find(
+      { dedupeKey: job.dedupeKey, status: "pending", _id: { $ne: job._id } },
+      { projection: { _id: 1 } },
+    ).toArray();
+    try {
+      await run(job.model, job.selectors, job.accessContext || undefined);
+    } catch (error) {
+      const failed = job.attempts >= MAX_ATTEMPTS;
+      await jobs.updateOne(
+        { _id: job._id, leaseOwner: state.owner },
+        {
+          $set: failed
+            ? { status: "failed", failedAt: new Date(), lastError: String(error?.message || error) }
+            : { status: "pending", nextRunAt: new Date(Date.now() + backoff(job.attempts)), lastError: String(error?.message || error) },
+          $unset: { leaseOwner: "", leaseExpiresAt: "" },
+        },
+      );
+      console.error("OON_PROCESS_ASYNC_RECALCULATION_FAILED", { model: job.model, attempts: job.attempts, final: failed, message: error?.message });
+      return true;
+    }
+    await jobs.deleteOne({ _id: job._id, leaseOwner: state.owner });
+    if (siblings.length) await jobs.deleteMany({ _id: { $in: siblings.map((doc) => doc._id) }, status: "pending" });
+    return true;
+  } finally {
+    await releaseLock(connection, job.dedupeKey);
+  }
+}
+
+let runner = null;
+
+function setRunner(fn) {
+  runner = fn;
+}
+
+async function drainAvailable() {
+  if (!runner) return;
+  // eslint-disable-next-line no-await-in-loop
+  while (await processOne(runner)) { /* continua até não haver tarefa disponível */ }
+}
+
+function runExclusive() {
+  if (state.inFlight) return state.inFlight;
+  state.inFlight = drainAvailable()
+    .catch((error) => console.error("OON_PROCESS_JOBS_WORKER_FAILED", { message: error?.message }))
+    .finally(() => { state.inFlight = null; });
+  return state.inFlight;
+}
+
+function schedule(delay = TICK_MS) {
+  if (!state.running) return;
+  clearTimeout(state.timer);
+  state.timer = setTimeout(() => { void runExclusive().finally(() => schedule()); }, delay);
+  state.timer.unref?.();
+}
+
+function kick() {
+  if (state.running) schedule(0);
+}
+
+async function start() {
+  if (state.running || !available()) return false;
+  await ensureReady();
+  state.running = true;
+  schedule(10);
+  return true;
+}
+
+async function stop() {
+  state.running = false;
+  clearTimeout(state.timer);
+  state.timer = null;
+  if (state.inFlight) await state.inFlight;
+}
+
+/** Processa todas as tarefas disponíveis agora e espera a que estiver em andamento. */
+async function drain() {
+  if (state.inFlight) await state.inFlight;
+  await runExclusive();
+}
+
+module.exports = {
+  JOBS,
+  LOCKS,
+  MAX_ATTEMPTS,
+  available,
+  dedupeKey,
+  drain,
+  enqueue,
+  ensureReady,
+  processOne,
+  setRunner,
+  start,
+  state,
+  stop,
+};

package/src/manifest/processRuntime.js

@@ -10,6 +10,7 @@ const {
   roundValue,
   valuesEquivalent,
 } = require("./domainRules");
+const processJobs = require("./processJobs");
 
 const MAX_AUTOMATIC_TRANSITIONS = 8;
 const MAX_TRANSACTION_ATTEMPTS = 3;
@@ -535,11 +536,29 @@ async function recalculateTarget(entry, selectors, options = {}) {
   return { matched: documents.length, modified: result.modifiedCount || 0 };
 }
 
-function enqueueAsynchronousRecalculation(target, options) {
+function frozenAccessContext(accessContext) {
   // Capture a value, never a mutable request/session or the next user's context.
-  const accessContext = options.accessContext ? Object.freeze({ ...options.accessContext,
-    permissions: Object.freeze([...(options.accessContext.permissions || [])]) }) : undefined;
+  return accessContext ? Object.freeze({ ...accessContext,
+    permissions: Object.freeze([...(accessContext.permissions || [])]) }) : undefined;
+}
+
+function plainAccessContext(accessContext) {
+  return accessContext ? { ...accessContext, permissions: [...(accessContext.permissions || [])] } : undefined;
+}
+
+// Com banco conectado, a fila é persistida (processJobs): sobrevive a reinícios
+// e é compartilhada entre réplicas. Sem banco, mantém a fila em memória.
+function enqueueAsynchronousRecalculation(target, options) {
+  const accessContext = frozenAccessContext(options.accessContext);
   scopeFilter(target.entry, accessContext);
+  if (processJobs.available()) {
+    return processJobs.enqueue({
+      modelName: target.entry.name,
+      selectors: target.selectors,
+      accessContext: plainAccessContext(accessContext),
+      session: options.session?.inTransaction?.() ? options.session : undefined,
+    });
+  }
   asynchronousQueue = asynchronousQueue
     .then(() => new Promise((resolve) => setImmediate(resolve)))
     .then(() => recalculateTarget(target.entry, target.selectors, { session: null, accessContext }))
@@ -565,11 +584,16 @@ async function recalculateDependents(entry, before, after, options = {}) {
   const results = [];
   for (const target of targets) {
     if (target.mode === "async") {
-      if (options.session?.inTransaction()) {
+      if (options.session?.inTransaction() && processJobs.available()) {
+        // Gravada na mesma transação: a tarefa só existe se a mudança for confirmada.
+        await enqueueAsynchronousRecalculation(target, options);
+      } else if (options.session?.inTransaction()) {
         const jobs = transactionJobs.get(options.session);
         if (!jobs) throw new DomainRuleError("Fila assíncrona exige transação gerenciada.", { code: "OON_PROCESS_TRANSACTION_REQUIRED", statusCode: 409 });
         scopeFilter(target.entry, options.accessContext);
         jobs.push({ target, options: { accessContext: options.accessContext ? { ...options.accessContext } : undefined } });
+      } else if (processJobs.available()) {
+        await enqueueAsynchronousRecalculation(target, options);
       } else enqueueAsynchronousRecalculation(target, options);
       results.push({ model: target.entry.name, mode: "async" });
     } else {
@@ -583,8 +607,30 @@ async function recalculateDependents(entry, before, after, options = {}) {
   return results;
 }
 
+processJobs.setRunner((modelName, selectors, accessContext) => {
+  const entry = registry.getModel(modelName);
+  if (!entry) throw new Error(`Model ${modelName} não registrada para o recálculo assíncrono.`);
+  return recalculateTarget(entry, selectors, { session: null, accessContext });
+});
+
+/** Processa as tarefas assíncronas disponíveis agora (fila persistida e em memória). */
 async function drainProcessJobs() {
   await asynchronousQueue;
+  if (processJobs.available()) await processJobs.drain();
+}
+
+/** Inicia o worker da fila persistida; chamado no boot, depois de conectar ao banco. */
+function startProcessJobs() {
+  return processJobs.start();
+}
+
+/**
+ * Encerramento: para o worker persistido (as pendentes ficam para outra
+ * réplica) e espera a fila em memória e a tarefa em andamento.
+ */
+async function stopProcessJobs() {
+  await processJobs.stop();
+  await asynchronousQueue;
 }
 
 module.exports = {
@@ -601,5 +647,7 @@ module.exports = {
   recalculateDependents,
   recalculateTarget,
   drainProcessJobs,
+  startProcessJobs,
+  stopProcessJobs,
   toPlainRecord,
 };

package/src/manifest/usageMetrics.js

@@ -0,0 +1,39 @@
+"use strict";
+
+// F5.2: métricas de uso que o App declara no central.app.json (`usageMetrics`).
+// A Central lê em GET /api/core/usage-metrics para pré-preencher os limites
+// do plano do App (Revenda > Planos), como faz com o catálogo de perfis.
+const METRIC = /^[a-z][a-z0-9_.-]{1,62}$/;
+const MAX_METRICS = 10;
+
+function validateUsageMetrics(input, issues) {
+  if (input === undefined) return;
+  const add = (path, message) => issues.push({ path, message });
+  if (!Array.isArray(input) || input.length > MAX_METRICS) return add("usageMetrics", `deve ser uma lista com até ${MAX_METRICS} métricas.`);
+  const seen = new Set();
+  input.forEach((metric, index) => {
+    const path = `usageMetrics[${index}]`;
+    if (!metric || typeof metric !== "object" || Array.isArray(metric)) return add(path, "deve ser um objeto.");
+    for (const key of Object.keys(metric)) if (!["code", "name", "unit", "description", "defaults"].includes(key)) add(`${path}.${key}`, "propriedade não suportada.");
+    if (typeof metric.code !== "string" || !METRIC.test(metric.code)) add(`${path}.code`, "use letras minúsculas, números, ponto, hífen ou sublinhado.");
+    else if (seen.has(metric.code)) add(`${path}.code`, "código repetido."); else seen.add(metric.code);
+    if (typeof metric.name !== "string" || !metric.name.trim() || metric.name.length > 80) add(`${path}.name`, "obrigatório, até 80 caracteres.");
+    const d = metric.defaults;
+    if (d === undefined) return;
+    if (!d || typeof d !== "object") return add(`${path}.defaults`, "deve ser um objeto.");
+    if (d.included !== undefined && (!Number.isSafeInteger(d.included) || d.included < 0)) add(`${path}.defaults.included`, "inteiro maior ou igual a zero.");
+    if (d.onLimit !== undefined && !["block", "auto_addon"].includes(d.onLimit)) add(`${path}.defaults.onLimit`, "block ou auto_addon.");
+    if (d.overage !== undefined) {
+      const o = d.overage || {};
+      if (!["unit", "block"].includes(o.mode)) add(`${path}.defaults.overage.mode`, "unit ou block.");
+      if (!Number.isSafeInteger(o.priceMinor) || o.priceMinor < 1) add(`${path}.defaults.overage.priceMinor`, "valor em centavos, maior que zero.");
+      if (o.mode === "block" && (!Number.isSafeInteger(o.blockSize) || o.blockSize < 1)) add(`${path}.defaults.overage.blockSize`, "tamanho do bloco, maior que zero.");
+    }
+  });
+}
+
+function publicUsageMetrics(config) {
+  return { schemaVersion: 1, appCode: String(config.appCode || config.slug || "central"), metrics: JSON.parse(JSON.stringify(config.usageMetrics || [])) };
+}
+
+module.exports = { validateUsageMetrics, publicUsageMetrics, MAX_METRICS };