@oondemand/oon-core-back 0.7.16 → 0.7.19

package/src/delivery/runtime.js

@@ -38,7 +38,40 @@ function readSecret(namespace, name, key) {
   } catch { return null; }
 }
 
+// Piso da cota do namespace (valores anteriores, fixos para todo App).
+const QUOTA_FLOOR = Object.freeze({ requestsCpuMilli: 2000, requestsMemoryMi: 2048, limitsCpuMilli: 4000, limitsMemoryMi: 4096, pods: 20 });
+
+function cpuMilli(value) {
+  const text = String(value);
+  return text.endsWith("m") ? Number(text.slice(0, -1)) : Number(text) * 1000;
+}
+
+function memoryMi(value) {
+  const text = String(value);
+  if (text.endsWith("Gi")) return Number(text.slice(0, -2)) * 1024;
+  if (text.endsWith("Mi")) return Number(text.slice(0, -2));
+  throw new Error(`Unidade de memória não suportada: ${text}`);
+}
+
+/**
+ * Cota do namespace calculada pelas réplicas e pelo perfil de recursos, com
+ * espaço para o pod extra do rolling update (maxSurge 1). Nunca fica abaixo
+ * do piso anterior, então Apps de 1 réplica mantêm a cota de sempre.
+ */
+function namespaceQuota({ replicas = 1, profile = "small" } = {}) {
+  const resources = RESOURCE_PROFILES[profile] || RESOURCE_PROFILES.small;
+  const pods = replicas + 1;
+  return {
+    requestsCpu: `${Math.max(QUOTA_FLOOR.requestsCpuMilli, pods * cpuMilli(resources.cpuRequest))}m`,
+    requestsMemory: `${Math.max(QUOTA_FLOOR.requestsMemoryMi, pods * memoryMi(resources.memoryRequest))}Mi`,
+    limitsCpu: `${Math.max(QUOTA_FLOOR.limitsCpuMilli, pods * cpuMilli(resources.cpuLimit))}m`,
+    limitsMemory: `${Math.max(QUOTA_FLOOR.limitsMemoryMi, pods * memoryMi(resources.memoryLimit))}Mi`,
+    pods: Math.max(QUOTA_FLOOR.pods, pods),
+  };
+}
+
 function baselineManifest({ context }) {
+  const quota = namespaceQuota({ replicas: replicaCount(context), profile: context.resourceProfile });
   return `apiVersion: v1
 kind: Namespace
 metadata:
@@ -66,7 +99,7 @@ apiVersion: v1
 kind: ResourceQuota
 metadata: { name: oon-runtime-quota, namespace: ${context.namespace} }
 spec:
-  hard: { requests.cpu: "2", requests.memory: 2Gi, limits.cpu: "4", limits.memory: 4Gi, pods: "20", services: "10" }
+  hard: { requests.cpu: "${quota.requestsCpu}", requests.memory: ${quota.requestsMemory}, limits.cpu: "${quota.limitsCpu}", limits.memory: ${quota.limitsMemory}, pods: "${quota.pods}", services: "10" }
 ---
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
@@ -83,8 +116,74 @@ spec:
 `;
 }
 
+// Cada slot contratado é uma réplica. O teto acompanha a cota de pods do
+// namespace (baselineManifest), com folga para o pod extra do rolling update.
+const MAX_REPLICAS = 10;
+// preStop + OON_SHUTDOWN_GRACE_MS do supervisor (25 s) cabem neste prazo.
+const PRE_STOP_SECONDS = 5;
+const TERMINATION_GRACE_SECONDS = 40;
+
+function replicaCount(context = {}) {
+  const value = context.replicas ?? 1;
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_REPLICAS) {
+    throw new Error(`Número de réplicas inválido no contexto de delivery: ${JSON.stringify(value)} (esperado 1 a ${MAX_REPLICAS}).`);
+  }
+  return value;
+}
+
+// F4.2: modo de performance do ambiente (pool MongoDB 4, 8 ou 16).
+const PERFORMANCE_MODES = ["min", "normal", "ultra"];
+function performanceMode(context = {}) {
+  const value = context.performanceMode ?? "min";
+  if (!PERFORMANCE_MODES.includes(value)) {
+    throw new Error(`Modo de performance inválido no contexto de delivery: ${JSON.stringify(value)} (esperado ${PERFORMANCE_MODES.join(", ")}).`);
+  }
+  return value;
+}
+
+// F4.6: domínios personalizados do App (raiz e www), já com DNS aprovado na
+// Central. Ficam num Ingress próprio, com certificado HTTP-01 do cert-manager
+// (renovação automática), para que um domínio com problema não afete o host
+// da plataforma.
+const MAX_CUSTOM_DOMAINS = 10;
+const HOSTNAME = /^(?=.{4,253}$)(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/;
+function customDomains(context = {}) {
+  const value = context.customDomains ?? [];
+  if (!Array.isArray(value) || value.length > MAX_CUSTOM_DOMAINS
+    || value.some((host) => typeof host !== "string" || !HOSTNAME.test(host) || host === context.hostname)
+    || new Set(value).size !== value.length) {
+    throw new Error(`Domínios personalizados inválidos no contexto de delivery: ${JSON.stringify(value)}.`);
+  }
+  return value;
+}
+function customDomainIngress({ context, infra }) {
+  const hosts = customDomains(context);
+  if (!hosts.length) return "";
+  return `---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: ${context.appCode}-custom
+  namespace: ${context.namespace}
+  annotations: { cert-manager.io/cluster-issuer: ${infra.CUSTOM_DOMAIN_CLUSTER_ISSUER || "letsencrypt-production-http01"} }
+spec:
+  ingressClassName: ${infra.INGRESS_CLASS}
+  tls: [{ hosts: [${hosts.join(", ")}], secretName: ${context.appCode}-custom-tls }]
+  rules:
+${hosts.map((host) => `    - host: ${host}
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service: { name: ${context.appCode}, port: { name: http } }`).join("\n")}
+`;
+}
+
 function runtimeManifest({ context, infra, imageRef, profile = "small" }) {
   const resources = RESOURCE_PROFILES[profile] || RESOURCE_PROFILES.small;
+  const replicas = replicaCount(context);
+  const mode = performanceMode(context);
   const releaseLabel = kubernetesLabelValue(context.releaseId);
   const releaseAnnotation = JSON.stringify(String(context.releaseId));
   return `apiVersion: apps/v1
@@ -93,7 +192,10 @@ metadata:
   name: ${context.appCode}
   namespace: ${context.namespace}
 spec:
-  replicas: 1
+  replicas: ${replicas}
+  strategy:
+    type: RollingUpdate
+    rollingUpdate: { maxUnavailable: 0, maxSurge: 1 }
   selector:
     matchLabels: { app.kubernetes.io/name: ${context.appCode} }
   template:
@@ -106,6 +208,13 @@ spec:
         oon.dev/release-id: ${releaseAnnotation}
     spec:
       serviceAccountName: oon-runtime
+      terminationGracePeriodSeconds: ${TERMINATION_GRACE_SECONDS}
+      topologySpreadConstraints:
+        - maxSkew: 1
+          topologyKey: kubernetes.io/hostname
+          whenUnsatisfiable: ScheduleAnyway
+          labelSelector:
+            matchLabels: { app.kubernetes.io/name: ${context.appCode} }
       imagePullSecrets: [{ name: ${infra.REGISTRY_PULL_SECRET_NAME || "ghcr-oon"} }]
       containers:
         - name: central
@@ -113,8 +222,10 @@ spec:
           imagePullPolicy: IfNotPresent
           ports: [{ name: http, containerPort: 8080 }]
           envFrom: [{ secretRef: { name: oon-runtime } }]
-${context.functionalCapabilities?.["core.secrets"]?.enabled ? `          env:
-            - name: OON_SECRETS_KEY
+          env:
+            - name: OON_DB_PERFORMANCE_MODE
+              value: "${mode}"
+${context.functionalCapabilities?.["core.secrets"]?.enabled ? `            - name: OON_SECRETS_KEY
               valueFrom:
                 secretKeyRef: { name: oon-core-secrets, key: OON_SECRETS_KEY, optional: true }
 ` : ""}
@@ -127,6 +238,20 @@ ${context.functionalCapabilities?.["core.secrets"]?.enabled ? `          env:
           readinessProbe:
             httpGet: { path: /api/health/ready, port: http }
             initialDelaySeconds: 10
+          lifecycle:
+            # Dá tempo para o ingress tirar o pod dos endpoints antes do SIGTERM.
+            preStop:
+              exec: { command: ["sleep", "${PRE_STOP_SECONDS}"] }
+---
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata: { name: ${context.appCode}, namespace: ${context.namespace} }
+spec:
+  # Drains e a autoescala de nós tiram no máximo uma réplica por vez; com uma
+  # réplica só, o PDB não bloqueia a manutenção do nó.
+  maxUnavailable: 1
+  selector:
+    matchLabels: { app.kubernetes.io/name: ${context.appCode} }
 ---
 apiVersion: v1
 kind: Service
@@ -152,7 +277,7 @@ spec:
             pathType: Prefix
             backend:
               service: { name: ${context.appCode}, port: { name: http } }
-`;
+${customDomainIngress({ context, infra })}`;
 }
 
 function copyPullSecret(namespace, infra) {
@@ -264,6 +389,8 @@ function deployRuntime({ context, infra, imageDigest, resourceProfile = "small"
   copyPullSecret(context.namespace, infra);
   const imageRef = `${context.imageRepository}@${imageDigest}`;
   applyYaml(runtimeManifest({ context, infra, imageRef, profile: resourceProfile }));
+  // F4.6: sem domínios ativos, o Ingress dos domínios personalizados sai.
+  if (!customDomains(context).length) kubectl(["-n", context.namespace, "delete", "ingress", `${context.appCode}-custom`, "--ignore-not-found"]);
   kubectl(["-n", context.namespace, "rollout", "status", `deployment/${context.appCode}`, "--timeout=10m"]);
   return { infraVersion: infra.INFRA_SCHEMA_VERSION, imageRef };
 }
@@ -306,4 +433,4 @@ async function activateMember(context) {
   return data;
 }
 
-module.exports = { supportsSecretsV1: true, RESOURCE_PROFILES, randomSecret, dnsLabel, kubernetesLabelValue, provisionMongo, validateMongoUri, baselineManifest, runtimeManifest, provisionRuntime, deployRuntime, waitHttp, activateMember };
+module.exports = { supportsSecretsV1: true, RESOURCE_PROFILES, MAX_REPLICAS, replicaCount, PERFORMANCE_MODES, performanceMode, MAX_CUSTOM_DOMAINS, customDomains, namespaceQuota, randomSecret, dnsLabel, kubernetesLabelValue, provisionMongo, validateMongoUri, baselineManifest, runtimeManifest, provisionRuntime, deployRuntime, waitHttp, activateMember };

package/src/delivery/supervisor.js

@@ -2,9 +2,19 @@
 
 // PID 1 owns both process groups. An unexpected exit (including status 0)
 // terminates the container; a live proxy cannot hide a dead backend.
+// On SIGTERM each child gets its own stop signal (nginx: SIGQUIT = graceful)
+// and `graceMs` to drain in-flight requests before SIGKILL. The Deployment's
+// terminationGracePeriodSeconds must exceed preStop + graceMs.
 const { spawn } = require("node:child_process");
 
-function supervise({ backend, proxy, graceMs = 5000 } = {}) {
+const DEFAULT_GRACE_MS = 25000;
+
+function graceFromEnv(env = process.env) {
+  const value = Number(env.OON_SHUTDOWN_GRACE_MS);
+  return Number.isSafeInteger(value) && value > 0 ? value : DEFAULT_GRACE_MS;
+}
+
+function supervise({ backend, proxy, graceMs = graceFromEnv() } = {}) {
   const children = [];
   let stopping = false;
   let exitCode = 1;
@@ -25,7 +35,7 @@ function supervise({ backend, proxy, graceMs = 5000 } = {}) {
     if (stopping) return;
     stopping = true;
     exitCode = code;
-    for (const child of children) signalGroup(child, "SIGTERM");
+    for (const child of children) signalGroup(child, child.stopSignal);
     timer = setTimeout(() => {
       for (const child of children) signalGroup(child, "SIGKILL");
     }, graceMs);
@@ -36,6 +46,7 @@ function supervise({ backend, proxy, graceMs = 5000 } = {}) {
       cwd: spec.cwd, env: { ...process.env, PORT: "4000" },
       stdio: "inherit", detached: true,
     });
+    child.stopSignal = spec.stopSignal || "SIGTERM";
     children.push(child);
     child.once("error", () => { child.failed = true; stop(1); finish(); });
     child.once("exit", () => { stop(1); finish(); });
@@ -46,7 +57,7 @@ function supervise({ backend, proxy, graceMs = 5000 } = {}) {
 
 if (require.main === module) supervise({
   backend: { command: process.execPath, args: ["/oon-delivery/launchRuntime.js"], cwd: "/app/backend" },
-  proxy: { command: "nginx", args: ["-c", "/etc/nginx/oon.conf", "-g", "daemon off;"] },
+  proxy: { command: "nginx", args: ["-c", "/etc/nginx/oon.conf", "-g", "daemon off;"], stopSignal: "SIGQUIT" },
 });
 
-module.exports = { supervise };
+module.exports = { supervise, graceFromEnv, DEFAULT_GRACE_MS };

package/src/index.js

@@ -83,5 +83,9 @@ module.exports = {
   PdfRenderingError: capabilities.PdfRenderingError,
   TransactionalEmailError: capabilities.TransactionalEmailError,
   GenericError, registry,
+  // F4.8: arquivos compartilhados entre réplicas (GridFS no MongoDB do App).
+  files: require("./core/storage/files"),
+  // F5.3/F5.5: consumo para os limites de uso do plano do App.
+  usage: require("./core/usage/reporter"),
 };
 

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 };