@neetru/db-chaos

Harness de injecao de falha / teste de caos para o Neetru Core DB. Transforma cada modo de falha conhecido do banco em um ChaosScenario executavel e repetivel.

O que e

Um banco de producao falha de formas conhecidas — o change stream morre, o oplog rola, a VM satura, uma instancia do Cloud Run e reciclada. Este pacote pega cada um desses modos de falha e o transforma num cenario de caos que uma suite de CI pode rodar de forma deterministica.

A regra de ouro: um teste de caos passa SOMENTE se a falha foi DETECTADA e NAO houve perda de dado:

passed === (observations.detected === true && observations.dataLossDetected === false)

Detectar a falha sem perder dado e o unico desfecho aceitavel. Falha nao detectada reprova; perda de dado reprova; uma excecao reprova.

E uma dev-dependency / harness de CI — um FRAMEWORK deterministico. O cenario nunca toca infraestrutura real: a falha e o sistema sob teste sao abstratos, injetados como dependencia (ChaosSystem). Roda sem nenhuma infraestrutura.

Funcoes puras, zero dependencias de runtime.

API

import {
  runScenario,
  runChaosSuite,
  changeStreamDeadScenario,
  oplogRolledScenario,
  vmSaturatedScenario,
  cloudRunRecycledScenario,
  clockSkewScenario,
  walgSilentFailScenario,
  networkPartitionScenario,
  CORE_DB_CHAOS_SCENARIOS,
} from '@neetru/db-chaos';
import type {
  ChaosScenario,
  ChaosObservations,
  ChaosResult,
  ChaosSystem,
} from '@neetru/db-chaos';

Tipos centrais

interface ChaosObservations {
  detected: boolean;          // o sistema detectou a falha?
  dataLossDetected: boolean;  // houve perda de dado?
  notes?: string[];
}

interface ChaosScenario<TSystem = unknown> {
  name: string;
  description: string;
  inject: (system: TSystem) => Promise<void> | void;     // aplica a falha
  observe: (system: TSystem) => Promise<ChaosObservations> | ChaosObservations;
}

interface ChaosResult {
  scenario: string;
  passed: boolean;            // true SOMENTE se detected && !dataLossDetected
  observations: ChaosObservations;
  error?: string;             // preenchido se inject/observe lancou
}

runScenario(scenario, system)

Roda 1 cenario: chama inject e depois observe, monta o ChaosResult. Se inject ou observe lancar, devolve passed: false com error preenchido e observacoes default seguras (detected: false, dataLossDetected: false). Nunca lanca.

runChaosSuite(scenarios, system)

Roda N cenarios via runScenario e devolve { results, allPassed }. allPassed e true somente se todos passaram — uma lista vazia produz allPassed: true.

Cenarios do Core DB

Cada fabrica devolve um ChaosScenario<ChaosSystem> para um modo de falha conhecido. Sao definicoes de FRAMEWORK — descrevem COMO injetar e COMO observar; um consumidor real liga um ChaosSystem concreto.

| Fabrica | Modo de falha | |---|---| | changeStreamDeadScenario() | O fluxo de mudancas realtime morre. | | oplogRolledScenario() | O oplog do Mongo rolou para alem do resume token. | | vmSaturatedScenario() | A VM do banco atinge saturacao de recursos. | | cloudRunRecycledScenario() | Uma instancia do Cloud Run e reciclada — o pool de conexoes cai. | | clockSkewScenario(skewMs?) | Skew de relogio entre nos. | | walgSilentFailScenario() | O arquivamento WAL-G para silenciosamente. | | networkPartitionScenario() | Particao de rede entre o Core e o banco. |

CORE_DB_CHAOS_SCENARIOS exporta as 7 fabricas em ordem estavel.

ChaosSystem — a superficie injetada

O sistema sob teste expoe os hooks minimos que os cenarios precisam — gatilhos de falha (killChangeStream, rollOplog, saturateVm, ...) e leitores de estado (getHealthSignal, getDataIntegrity). Um consumidor real implementa isto sobre infraestrutura de verdade; uma suite de teste implementa um mock.

const system: ChaosSystem = {
  killChangeStream: () => realSystem.dropChangeStream(),
  getHealthSignal: () => realSystem.health(),
  getDataIntegrity: () => realSystem.integrityReport(),
  // ... demais hooks
};

const report = await runChaosSuite(
  CORE_DB_CHAOS_SCENARIOS.map((f) => f()),
  system,
);
if (!report.allPassed) process.exit(1);

Desenvolvimento

npm run build   # tsc -> dist/
npm test        # vitest run