@oondemand/create-central-oon 0.7.8 → 0.7.9

package/docs/DATABASE_CONTAINMENT.md

@@ -0,0 +1,67 @@
+# Contenção de carga MongoDB
+
+A release **__OONCORE_VERSION__** aplica uma política interna no backend do Core. Não há configuração obrigatória nova, migração de dados, alteração de tenancy ou configuração de pool no manifesto do App. Atualize os pacotes coordenados, lockfiles e documentação pelo fluxo de [upgrade](CORE_UPGRADE.md) e republique o consumidor para ativá-la.
+
+## Política e precedência
+
+| Parâmetro | Padrão inicial |
+|---|---:|
+| maxPoolSize | 4 |
+| minPoolSize | 0 |
+| maxConnecting | 2 |
+| waitQueueTimeoutMS | 2000 ms |
+| maxTimeMS nos métodos cobertos | 5000 ms |
+
+São parâmetros iniciais versionados, não capacidade garantida ou calibração homologada do cluster compartilhado. Alterações operacionais exigem revisão da política da Plataforma e release do Core; não há override via env, central.config.js ou central.app.json. O módulo interno não é API de extensão do App.
+
+O Core passa opções explícitas ao driver, com precedência sobre os quatro parâmetros de pool da URI, inclusive zero. MONGO_URI continua fornecendo credenciais, banco, TLS, authSource, replica set e demais opções. Sem MONGO_URI, DB_SERVER/DB_NAME e DB_USER/DB_PASSWORD continuam suportados. O Core valida seu orçamento antes da conexão; configuração/autenticação/topologia inválida continua sujeita à validação do driver. Não reconstrói nem registra a URI.
+
+## Cobertura
+
+| Operação/caminho | Pool | maxTimeMS automático |
+|---|---|---|
+| find, findOne, countDocuments, estimatedDocumentCount, distinct | Conexão do Core | Sim |
+| findOneAndUpdate, findOneAndReplace, findOneAndDelete | Conexão do Core | Sim, sem garantia de ausência de escrita após erro |
+| updateOne, updateMany, replaceOne, deleteOne, deleteMany como queries | Conexão do Core | Sim |
+| aggregate | Conexão do Core | Sim |
+| populate | Conexão do Core | Queries dos modelos cobertos |
+| find/aggregate cursor | Conexão do Core | Comando inicial; não é deadline completo do consumo/getMore |
+| save/create/insertMany/bulkWrite, métodos de documento | Conexão do Core | Não nesta entrega |
+| Transações | Conexão do Core | Somente comandos Mongoose acima; não é limite da transação/commit |
+| collection nativa / connection.db / comandos administrativos / índices | Se usa o cliente do Core | Não |
+| Outro MongoClient/createConnection/instância Mongoose | Não garantido | Não garantido |
+
+Limite explícito positivo menor é preservado. Zero, ausente ou maior recebe o teto. Valor não inteiro, negativo ou inválido falha antes do comando nos hooks cobertos. Filtros e resultados não são modificados. Não há semáforo adicional nem novo retry automático. Retries já existentes do driver/transações não são removidos.
+
+## Ordem de inicialização
+
+A entrada pública carrega a política antes dos demais imports; todos os compiladores de modelos internos usam o mesmo adaptador Mongoose. O CLI start/activate e o autoload seguem essa ordem. O plugin é registrado uma única vez por instância; os hooks são registrados antes de compilar schemas.
+
+Carregue o Core antes de compilar modelos customizados. Modelos compilados previamente, outra cópia/instância do Mongoose e conexões independentes não têm cobertura garantida. O log de política registra a quantidade `uncoveredModels` na instância do Core sem revelar nomes. Não há retrofit de hooks de modelos já compilados. O App mantém acesso às credenciais: esta política não é fronteira de segurança contra bypass deliberado.
+
+## Erros e recuperação
+
+- `DATABASE_POOL_BUSY`, HTTP **503**: espera por conexão expirou (`MongoWaitQueueTimeoutError`).
+- `DATABASE_OPERATION_TIMEOUT`, HTTP **504**: servidor retornou `MongoServerError` código 50.
+
+Preservam o envelope e requestId do middleware. Mensagens não incluem documentos, filtros ou credenciais. Outros timeouts de rede, seleção de servidor ou write concern não são classificados indevidamente como esses erros.
+
+Não conclua que a requisição inteira não persistiu nada após um erro de admissão: etapas anteriores podem ter ocorrido. Timeout de escrita também não prova ausência de persistência. Consulte/reconcilie o estado e use a idempotência do domínio; não repita escritas automaticamente.
+
+Workers e rotas que capturam seus próprios erros continuam recebendo o erro original do driver. Um sucesso externo seguido de falha de persistência local exige homologar a recuperação existente do consumidor. A política não altera regras de emissão fiscal.
+
+## Observabilidade
+
+Eventos públicos CMAP do driver alimentam contadores em memória por processo/cliente: conexões em uso, esperando, picos, checkouts, falhas, falhas por timeout e duração total/máxima de espera. Timeouts Mongoose são contados nos hooks de erro. Timeouts nativos e de modelos não cobertos não entram nesse contador; erros assíncronos no consumo de cursores/getMore também não têm contagem garantida pelos hooks. O total de espera inclui checkouts bem-sucedidos e falhos; contagens são por checkout, não por requisição HTTP.
+
+Emissão agregada a cada 60 segundos quando há atividade e no fechamento, com appCode, APP_ENVIRONMENT (fallback NODE_ENV) e PID. Rótulos inválidos são substituídos por unknown. Sem payload, endereço do servidor, documento Mongo por operação ou rota pública de métricas. Listeners são idempotentes, sobrevivem à desconexão transitória do mesmo cliente e são removidos no fechamento/falha inicial. Health/readiness não mudam.
+
+## Limitações e calibração
+
+Pool limita paralelismo por cliente/processo/servidor, não CPU/RAM/I/O, operações por segundo ou o total do cluster. Há sockets adicionais de monitoramento. Pods, clientes e coexistência durante rollout multiplicam o orçamento. Loops sequenciais rápidos continuam possíveis; a fila de espera tem prazo, não limite de quantidade. Consultas caras, TTL e replicação ainda podem pressionar o banco. Os apps podem competir mesmo respeitando seus limites; não há prioridade/reserva para autenticação ou persistência de workers.
+
+Homologue em replica set isolado com a versão do driver instalada. Compare pools 2/4/8, latência p95/p99, vazão, falhas, espera, memória do processo e CPU/memória Mongo, com outro app simultâneo e dois processos/rollout. Inclua cursores/getMore, índices, importação/exportação e transações. Testes sintéticos não garantem capacidade mensal nem isolamento no cluster real.
+
+Rollout: candidato do SDK → consumidor piloto com integrações externas simuladas → evidências → consumidores em lotes → Central/apps globais. No Emissor, validar sucesso Omie seguido de falha local, idempotência, reconciliação e recuperação de leases antes da adoção operacional. Publicação npm sozinha não ativa apps existentes.
+
+Rollback: restaurar versões coordenadas anteriores e lockfiles, sincronizar docs e republicar a imagem anterior pelo fluxo existente. Não há migração a desfazer; o rollback retira a contenção. Não substituir rollback por aumento irrestrito do pool.

package/docs/ERRORS.md

@@ -16,3 +16,13 @@ Erros de domínio lançados com `GenericError` e `code` usam `{ message, error:
 | `LOCAL_OPERATION_NOT_SUPPORTED` | recurso exclusivo da plataforma |
 
 Não faça branching por texto de mensagem; use `code`. Logs e respostas nunca devem conter token, cookie, credencial, senha ou conteúdo sensível.
+
+
+## Contenção MongoDB
+
+| Código | HTTP | Significado |
+|---|---:|---|
+| `DATABASE_POOL_BUSY` | 503 | Expirou a espera por conexão no pool |
+| `DATABASE_OPERATION_TIMEOUT` | 504 | Servidor excedeu o tempo de execução permitido |
+
+Preservam requestId. Não repetem escritas automaticamente; erro não prova ausência de persistência. Workers/catches próprios recebem o erro original. Consulte [política, cobertura e recuperação](DATABASE_CONTAINMENT.md).

package/docs/TASK_INDEX.md

@@ -34,3 +34,8 @@ Na release __OONCORE_VERSION__, `create-central-oon example` instala o exemplo o
 ## Aplicação dos recursos nativos
 
 A página `/recursos` do exemplo demonstra fórmulas, validações, bindings, invariantes, documentos, dashboard e PDF. O serviço de e-mail é opt-in. Consulte [NATIVE_RESOURCES.md](NATIVE_RESOURCES.md) para o roteiro, helpers de escopo e limites reais de isolamento, auditoria e execução.
+
+
+## Contenção de carga do banco
+
+Para diagnosticar `DATABASE_POOL_BUSY`, `DATABASE_OPERATION_TIMEOUT`, espera no pool ou limites de consultas, leia [DATABASE_CONTAINMENT.md](DATABASE_CONTAINMENT.md). A política pertence ao Core, sem configuração livre no manifesto do App; não substitui isolamento físico ou limite global do cluster.

package/package.json

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

package/templates/_base/backend/package.json

@@ -12,6 +12,6 @@
     "deploy": "oonCore-back deploy"
   },
   "dependencies": {
-    "@oondemand/oon-core-back": "^0.7.8"
+    "@oondemand/oon-core-back": "^0.7.9"
   }
 }

package/templates/_base/frontend/package.json

@@ -11,7 +11,7 @@
     "sync:metadata": "oonCore-front sync:metadata"
   },
   "dependencies": {
-    "@oondemand/oon-core-front": "^0.7.8",
+    "@oondemand/oon-core-front": "^0.7.9",
     "@chakra-ui/react": "^3.13.0",
     "@emotion/react": "^11.14.0",
     "@tanstack/react-query": "^5.65.0",

package/templates/_base/package.json

@@ -13,6 +13,6 @@
     "dev:frontend": "npm run dev --prefix frontend"
   },
   "devDependencies": {
-    "@oondemand/create-central-oon": "0.7.8"
+    "@oondemand/create-central-oon": "0.7.9"
   }
 }