@oondemand/oon-core-back 0.7.8 → 0.7.9

package/README.md

@@ -128,3 +128,8 @@ provedor de aplicativos.
 Publicar primeiro o suporte da Central (consulta e prova de identidade), depois
 lançar front/back do SDK juntos e atualizar consumidores. O bloqueio de integração
 comercial permanece até C3a/C3b; C2 não executa cutover nem reenvia convites.
+
+
+## Contenção MongoDB
+
+O backend governa o pool e os timeouts dos métodos Mongoose cobertos. Veja a [política distribuída](../create-central-oon/docs/DATABASE_CONTAINMENT.md) e as [evidências/gates de adoção](../../docs/database-containment-validation.md). A release precisa ser adotada e republicada por cada consumidor; não fornece isolamento físico nem limite global do cluster.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/oon-core-back",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/src/api/status.routes.js

@@ -1,7 +1,7 @@
 "use strict";
 
 const express = require("express");
-const mongoose = require("mongoose");
+const mongoose = require("../core/database/mongoose");
 const ctx = require("../core/context");
 const { runtimeSummary } = require("./core.routes");
 const { isLocalRuntime, localRuntimeSummary } = require("../core/runtime/localDevelopment");
@@ -79,3 +79,4 @@ module.exports = router;
 module.exports.databaseState = databaseState;
 module.exports.readinessSummary = readinessSummary;
 module.exports.versionSummary = versionSummary;
+

package/src/boot/database.js

@@ -1,5 +1,8 @@
-const mongoose = require("mongoose");
+const mongoose = require("../core/database/mongoose");
 const registry = require("../core/registry");
+const ctx = require("../core/context");
+const { DEFAULTS, poolOptions } = require("../core/database/policy");
+const { attachPoolMetrics } = require("../core/database/metrics");
 
 function buildMongoUri() {
   const cfg = {
@@ -20,7 +23,8 @@ function buildMongoUri() {
 }
 
 function connectionOptions() {
-  if (process.env.MONGO_URI) return {};
+  const pool = poolOptions();
+  if (process.env.MONGO_URI) return pool;
 
   const hasUser = Boolean(process.env.DB_USER);
   const hasPassword = Boolean(process.env.DB_PASSWORD);
@@ -30,8 +34,8 @@ function connectionOptions() {
   }
 
   return hasUser
-    ? { user: process.env.DB_USER, pass: process.env.DB_PASSWORD }
-    : {};
+    ? { ...pool, user: process.env.DB_USER, pass: process.env.DB_PASSWORD }
+    : pool;
 }
 
 function databaseLabel(uri) {
@@ -71,7 +75,21 @@ async function syncDeclaredIndexes(entries = registry.listModels()) {
 
 async function connectDB() {
   const uri = buildMongoUri();
-  await mongoose.connect(uri, connectionOptions());
+  const options = connectionOptions();
+  // Explicit driver options override conflicting URI pool options; tested with the real driver.
+  const connecting = mongoose.connect(uri, options);
+  const client = mongoose.connection.getClient();
+  const metrics = client && attachPoolMetrics(client, mongoose.connection, {
+    app: ctx.config.appCode || ctx.config.slug || process.env.APP_CODE,
+    environment: process.env.APP_ENVIRONMENT || process.env.NODE_ENV,
+  });
+  try {
+    await connecting;
+  } catch (error) {
+    metrics?.dispose();
+    throw error;
+  }
+  console.log("[OonCore] database policy", JSON.stringify({ ...DEFAULTS, uncoveredModels: Object.values(mongoose.models).filter(model => !model.schema[Symbol.for("oon.database.policy.schema.v1")]).length }));
   await syncDeclaredIndexes();
   console.log(`Conectado ao MongoDB (${databaseLabel(uri)})`);
   return mongoose.connection;
@@ -85,3 +103,4 @@ module.exports = {
   shouldSyncDeclaredIndexes,
   syncDeclaredIndexes,
 };
+

package/src/capabilities/secrets/index.js

@@ -1,6 +1,6 @@
 "use strict";
 const crypto = require("node:crypto");
-const mongoose = require("mongoose");
+const mongoose = require("../../core/database/mongoose");
 const ctx = require("../../core/context");
 const GenericError = require("../../core/errors/GenericError");
 const MAX_BYTES = 16384;
@@ -111,3 +111,4 @@ async function remove({ name, context, correlationId } = {}) {
   return safe(async () => { const s = resolveScope(context, name); await audit("remove", s, context, correlationId); await models().Secret.deleteOne({ _id: id(s) }); return { state: "absent" }; });
 }
 module.exports = Object.freeze({ put, status, use, remove });
+

package/src/capabilities/transactionalEmail/models.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const mongoose = require("mongoose");
+const mongoose = require("../../core/database/mongoose");
 
 const envelope = { keyId: String, version: Number, algorithm: String, iv: String, authTag: String, ciphertext: String };
 const common = { scopeKey: { type: String, required: true, index: true } };
@@ -19,3 +19,4 @@ function getModels() {
 }
 async function syncIndexes() { const models = getModels(); return Promise.all(Object.values(models).map((entry) => entry.syncIndexes())); }
 module.exports = { getModels, syncIndexes };
+

package/src/core/database/errors.js

@@ -0,0 +1,15 @@
+"use strict";
+
+function databaseError(error) {
+  if (error?.name === "MongoWaitQueueTimeoutError") return {
+    code: "DATABASE_POOL_BUSY", statusCode: 503,
+    message: "O banco está ocupado. Aguarde antes de tentar novamente.",
+  };
+  if (error?.code === 50 && error?.name === "MongoServerError") return {
+    code: "DATABASE_OPERATION_TIMEOUT", statusCode: 504,
+    message: "A operação excedeu o tempo permitido. Consulte o estado antes de repetir uma alteração.",
+  };
+  return null;
+}
+
+module.exports = { databaseError };

package/src/core/database/metrics.js

@@ -0,0 +1,66 @@
+"use strict";
+
+const monitors = new WeakMap();
+const connections = new WeakMap();
+
+function observeOperationError(connection, error) {
+  if (error?.name === "MongoServerError" && error.code === 50) {
+    const monitor = connections.get(connection);
+    if (monitor) monitor.operationTimeout();
+  }
+}
+
+function safeLabel(value) {
+  return typeof value === "string" && /^[a-zA-Z0-9_.-]{1,80}$/.test(value) ? value : "unknown";
+}
+
+function attachPoolMetrics(client, connection, { app, environment, emit = record => console.log("[OonCore] database", JSON.stringify(record)), intervalMS = 60000 } = {}) {
+  if (monitors.has(client)) return monitors.get(client);
+  const inUse = new Set();
+  let waiting = 0;
+  let counters;
+  const reset = () => { counters = { checkouts: 0, checkoutFailures: 0, checkoutTimeouts: 0, mongooseOperationTimeouts: 0, waitTotalMS: 0, waitMaxMS: 0, peakWaiting: waiting, peakInUse: inUse.size }; };
+  reset();
+  const key = event => `${event.address}/${event.connectionId}`;
+  const duration = event => {
+    const ms = Number.isFinite(event.durationMS) && event.durationMS >= 0 ? event.durationMS : 0;
+    counters.waitTotalMS += ms;
+    counters.waitMaxMS = Math.max(counters.waitMaxMS, ms);
+  };
+  const listeners = {
+    connectionCheckOutStarted() { waiting++; counters.peakWaiting = Math.max(counters.peakWaiting, waiting); },
+    connectionCheckedOut(event) { waiting = Math.max(0, waiting - 1); inUse.add(key(event)); counters.checkouts++; counters.peakInUse = Math.max(counters.peakInUse, inUse.size); duration(event); },
+    connectionCheckOutFailed(event) { waiting = Math.max(0, waiting - 1); counters.checkoutFailures++; if (event.reason === "timeout") counters.checkoutTimeouts++; duration(event); },
+    connectionCheckedIn(event) { inUse.delete(key(event)); },
+    connectionClosed(event) { inUse.delete(key(event)); },
+  };
+  for (const [event, listener] of Object.entries(listeners)) client.on(event, listener);
+  const snapshot = () => ({ app: safeLabel(app), environment: safeLabel(environment), pid: process.pid, intervalMS, inUse: inUse.size, waiting, ...counters });
+  const flush = () => {
+    if (counters.checkouts || counters.checkoutFailures || counters.mongooseOperationTimeouts || inUse.size || waiting) {
+      try { emit(snapshot()); } catch { /* Telemetry must never fail a database operation. */ }
+    }
+    reset();
+  };
+  const timer = setInterval(flush, intervalMS);
+  timer.unref();
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    clearInterval(timer);
+    flush();
+    for (const [event, listener] of Object.entries(listeners)) client.removeListener(event, listener);
+    connection.removeListener("close", dispose);
+    monitors.delete(client);
+    if (connections.get(connection) === monitor) connections.delete(connection);
+    inUse.clear(); waiting = 0;
+  };
+  const monitor = { snapshot, flush, dispose, operationTimeout() { counters.mongooseOperationTimeouts++; } };
+  monitors.set(client, monitor);
+  connections.set(connection, monitor);
+  connection.once("close", dispose);
+  return monitor;
+}
+
+module.exports = { attachPoolMetrics, observeOperationError };

package/src/core/database/mongoose.js

@@ -0,0 +1,40 @@
+"use strict";
+
+const mongoose = require("mongoose");
+const { boundedMaxTimeMS } = require("./policy");
+const { observeOperationError } = require("./metrics");
+const INSTALLED = Symbol.for("oon.database.policy.installed.v1");
+const COVERED = Symbol.for("oon.database.policy.schema.v1");
+const QUERY_METHODS = Object.freeze([
+  "find", "findOne", "countDocuments", "estimatedDocumentCount", "distinct",
+  "findOneAndUpdate", "findOneAndReplace", "findOneAndDelete",
+  "updateOne", "updateMany", "replaceOne", "deleteOne", "deleteMany",
+]);
+
+function install(instance) {
+  if (instance[INSTALLED]) return;
+  instance[INSTALLED] = true;
+  instance.plugin(function databasePolicy(schema) {
+    if (schema[COVERED]) return;
+    schema[COVERED] = true;
+    for (const method of QUERY_METHODS) {
+      schema.pre(method, { query: true, document: false }, function applyQueryBudget() {
+        if (this.model.db === instance.connection) this.setOptions({ maxTimeMS: boundedMaxTimeMS(this.getOptions().maxTimeMS) });
+      });
+      schema.post(method, { query: true, document: false }, function observeQueryError(error, result, next) {
+        observeOperationError(this.model.db, error);
+        next(error);
+      });
+    }
+    schema.pre("aggregate", function applyAggregateBudget() {
+      if (this.model().db === instance.connection) this.option({ maxTimeMS: boundedMaxTimeMS(this.options.maxTimeMS) });
+    });
+    schema.post("aggregate", function observeAggregateError(error, result, next) {
+      observeOperationError(this.model().db, error);
+      next(error);
+    });
+  });
+}
+
+install(mongoose);
+module.exports = mongoose;

package/src/core/database/policy.js

@@ -0,0 +1,41 @@
+"use strict";
+
+// Versioned Core policy, deliberately not an app manifest/env extension point.
+// Initial calibration profile: not a claim of safe shared-cluster capacity.
+const DEFAULTS = Object.freeze({
+  maxPoolSize: 4,
+  minPoolSize: 0,
+  maxConnecting: 2,
+  waitQueueTimeoutMS: 2000,
+  maxTimeMS: 5000,
+});
+
+function configurationError() {
+  const error = new Error("Política de contenção MongoDB inválida.");
+  error.code = "DATABASE_POLICY_INVALID";
+  return error;
+}
+
+function validatePolicy(input = DEFAULTS) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw configurationError();
+  const policy = { ...DEFAULTS, ...input };
+  if (Object.keys(policy).some(key => !Object.hasOwn(DEFAULTS, key))) throw configurationError();
+  for (const [key, value] of Object.entries(policy)) {
+    if (!Number.isSafeInteger(value) || value < (key === "minPoolSize" ? 0 : 1)) throw configurationError();
+  }
+  if (policy.minPoolSize > policy.maxPoolSize || policy.maxConnecting > policy.maxPoolSize) throw configurationError();
+  return Object.freeze(policy);
+}
+
+function poolOptions(policy = DEFAULTS) {
+  const { maxTimeMS, ...pool } = validatePolicy(policy);
+  return pool;
+}
+
+function boundedMaxTimeMS(value, ceiling = DEFAULTS.maxTimeMS) {
+  if (value === undefined || value === 0) return ceiling;
+  if (!Number.isSafeInteger(value) || value < 0) throw configurationError();
+  return Math.min(value, ceiling);
+}
+
+module.exports = { DEFAULTS, validatePolicy, poolOptions, boundedMaxTimeMS };

package/src/core/define.js

@@ -1,4 +1,4 @@
-const mongoose = require("mongoose");
+const mongoose = require("./database/mongoose");
 const express = require("express");
 const registry = require("./registry");
 const ctx = require("./context");
@@ -212,3 +212,4 @@ module.exports = {
   definePipeline,
   defineRoutes,
 };
+

package/src/core/fields.js

@@ -5,7 +5,7 @@
  * `__meta` é consumido pelo registry para gerar metadata/OpenAPI para o
  * front, sem vazar para o schema Mongoose final.
  */
-const mongoose = require("mongoose");
+const mongoose = require("./database/mongoose");
 
 const withMeta = (mongooseDef, meta) => ({
   ...mongooseDef,
@@ -93,3 +93,4 @@ module.exports = {
   currencyCode,
   currencyConverted,
 };
+

package/src/core/middlewares/error.js

@@ -1,3 +1,4 @@
+const { databaseError } = require("../database/errors");
 const helpers = require("../utils/helpers");
 const GenericError = require("../errors/GenericError");
 
@@ -74,6 +75,16 @@ const errorMiddleware = (error, req, res, next) => {
     });
   }
 
+  const databaseFailure = databaseError(error);
+  if (databaseFailure) {
+    const { statusCode, ...details } = databaseFailure;
+    return helpers.sendErrorResponse({
+      res, statusCode,
+      error: { ...details, ...(requestId ? { requestId } : {}) },
+      message: details.message,
+    });
+  }
+
   if (error?.code === 11000 || error?.name === "MongoServerError" && error?.code === 11000) {
     const details = duplicateKeyDetails(error, requestId);
     return helpers.sendErrorResponse({
@@ -135,3 +146,4 @@ const errorMiddleware = (error, req, res, next) => {
 module.exports = errorMiddleware;
 module.exports.firstDuplicateField = firstDuplicateField;
 module.exports.duplicateKeyDetails = duplicateKeyDetails;
+

package/src/core/models/ControleAlteracao.js

@@ -1,4 +1,4 @@
-const mongoose = require("mongoose");
+const mongoose = require("../database/mongoose");
 
 /**
  * Trilha de auditoria de mutações. Diferente da versão do CST, no Core
@@ -26,3 +26,4 @@ const ControleAlteracao =
 module.exports = ControleAlteracao;
 module.exports.ACOES_PADRAO = ACOES_PADRAO;
 module.exports.ORIGENS_PADRAO = ORIGENS_PADRAO;
+

package/src/core/models/InstanciaEcossistema.js

@@ -1,4 +1,4 @@
-const mongoose = require("mongoose");
+const mongoose = require("../database/mongoose");
 
 const statuses = ["nao_ativada", "validando", "configurando", "ativa", "suspensa", "revogada", "erro"];
 const roles = ["root", "member"];
@@ -65,3 +65,4 @@ schema.index({ singletonKey: 1 }, { unique: true });
 module.exports = mongoose.models.InstanciaEcossistema || mongoose.model("InstanciaEcossistema", schema);
 module.exports.STATUSES = statuses;
 module.exports.ROLES = roles;
+

package/src/core/models/Log.js

@@ -1,4 +1,4 @@
-const mongoose = require("mongoose");
+const mongoose = require("../database/mongoose");
 
 /**
  * Log de requisições mutantes. Model interna do Core — registrada
@@ -20,3 +20,4 @@ const logSchema = new mongoose.Schema(
 
 module.exports =
   mongoose.models.Log || mongoose.model("Log", logSchema);
+

package/src/core/models/Sistema.js

@@ -1,4 +1,4 @@
-const mongoose = require("mongoose");
+const mongoose = require("../database/mongoose");
 
 /**
  * Configuração singleton da Central. Credenciais funcionais pertencem às
@@ -17,3 +17,4 @@ const sistemaSchema = new mongoose.Schema(
 
 module.exports =
   mongoose.models.Sistema || mongoose.model("Sistema", sistemaSchema);
+

package/src/core/rbac/storage.js

@@ -1,7 +1,7 @@
 "use strict";
 
 const crypto = require("node:crypto");
-const mongoose = require("mongoose");
+const mongoose = require("../database/mongoose");
 const ctx = require("../context");
 const GenericError = require("../errors/GenericError");
 const { encrypt, decrypt } = require("../utils/instanceActivation");
@@ -405,3 +405,4 @@ module.exports = {
   activeAdminCount,
   assertNotLastAdmin,
 };
+

package/src/core/runtime/localDevelopment.js

@@ -1,7 +1,7 @@
 "use strict";
 
 const crypto = require("node:crypto");
-const mongoose = require("mongoose");
+const mongoose = require("../database/mongoose");
 const ctx = require("../context");
 const GenericError = require("../errors/GenericError");
 const { policy, roleByCode, rolePermissions } = require("../rbac/policy");
@@ -338,3 +338,4 @@ module.exports = {
   clearCookie, assertLocalRequest, localRequestBoundary, localRuntimeSummary,
   resetLocalDevelopmentForTests,
 };
+

package/src/core/utils/instanceActivation.js

@@ -1,5 +1,5 @@
 const crypto = require("node:crypto");
-const mongoose = require("mongoose");
+const mongoose = require("../database/mongoose");
 const axios = require("axios");
 const ctx = require("../context");
 const GenericError = require("../errors/GenericError");
@@ -641,3 +641,4 @@ module.exports = {
   event,
 };
 
+

package/src/index.js

@@ -1,4 +1,5 @@
 require("dotenv").config();
+require("./core/database/mongoose"); // Before any Core or consumer model compilation.
 
 const { start } = require("./boot/startServer");
 const { createApp } = require("./boot/createApp");
@@ -82,3 +83,4 @@ module.exports = {
   TransactionalEmailError: capabilities.TransactionalEmailError,
   GenericError, registry,
 };
+

package/src/manifest/processRuntime.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const mongoose = require("mongoose");
+const mongoose = require("../core/database/mongoose");
 const registry = require("../core/registry");
 const {
   DomainRuleError,
@@ -588,4 +588,4 @@ module.exports = {
   recalculateTarget,
   drainProcessJobs,
   toPlainRecord,
-};
+};

package/src/modules/assistants/index.js

@@ -1,4 +1,4 @@
-const mongoose = require("mongoose");
+const mongoose = require("../../core/database/mongoose");
 
 /**
  * Módulo Assistentes IA (Seção 13) — catálogo de assistentes, prompts e
@@ -31,3 +31,4 @@ function mascarar(texto, segredos = []) {
 }
 
 module.exports = { Assistente, mascarar };
+

package/src/modules/currencies/index.js

@@ -1,4 +1,4 @@
-const mongoose = require("mongoose");
+const mongoose = require("../../core/database/mongoose");
 
 /**
  * Módulo Multi-moedas (Seção 14) — cadastro/cotação/conversão. As models
@@ -29,3 +29,4 @@ async function converter({ valor, de = "BRL", para = "BRL" }) {
 }
 
 module.exports = { Moeda, converter };
+