replica-failover-mongodb-ts 2.0.5 → 2.2.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2025 João Ito
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/Readme.md

@@ -1,5 +1,21 @@
 # Node Balancer
 
+[![NPM Version](https://img.shields.io/npm/v/replica-failover-mongodb-ts?style=flat-square)](https://www.npmjs.com/package/replica-failover-mongodb-ts)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Node.js](https://img.shields.io/badge/Node.js-20.x-green)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+
+## 🚀 Quick Start (Dashboard CLI)
+
+Se você quer apenas rodar o painel de controle visualmente para testar qualquer API:
+
+```bash
+npm install -g replica-failover-mongodb-ts
+node-balancer-dashboard
+```
+
+---
+
 ## Sobre o Projeto: "Node Balancer"
 
 O Node Balancer é uma API escalável construída utilizando Node.js, MongoDB com replica set para alta disponibilidade, e Nginx como balanceador de carga. O sistema foi projetado para garantir resiliência, escalabilidade e alta disponibilidade. A arquitetura permite a adição manual de instâncias backend (Node.js) e garante que, em caso de falhas, o sistema continue operando sem interrupções, com a replicação automática dos dados e balanceamento de carga eficiente.
@@ -11,11 +27,13 @@ O Node Balancer é uma API escalável construída utilizando Node.js, MongoDB co
 ## Sumário
 
 1.  [Tecnologias](#tecnologias)
-2.  [Como Rodar o Projeto](#como-rodar-o-projeto)
-3.  [Visual Dashboard (Painel de Controle)](#visual-dashboard-painel-de-controle)
-4.  [Testes e Automação (Chaos Testing)](#testes-e-automação-chaos-testing)
-5.  [Documentação Detalhada](#documentação-detalhada)
-6.  [Configuração Manual (Referência)](#configuração-manual-referência)
+2.  [Como Rodar o Projeto (Dev)](#como-rodar-o-projeto-dev)
+3.  [Uso como Biblioteca (Library)](#uso-como-biblioteca-library)
+4.  [Visual Dashboard (Painel de Controle)](#visual-dashboard-painel-de-controle)
+5.  [Uso Avançado do Dashboard (CLI)](#uso-avançado-do-dashboard-cli)
+6.  [Testes e Automação (Chaos Testing)](#testes-e-automação-chaos-testing)
+7.  [Documentação Detalhada](#documentação-detalhada)
+8.  [Configuração Manual (Referência)](#configuração-manual-referência)
 
 ---
 
@@ -31,7 +49,7 @@ O Node Balancer utiliza as seguintes tecnologias:
 
 ---
 
-## Como Rodar o Projeto
+## Como Rodar o Projeto (Dev)
 
 ### Pré-requisitos
 -   Docker e Docker Compose instalados.
@@ -61,6 +79,33 @@ O Node Balancer utiliza as seguintes tecnologias:
 
 ---
 
+## Uso como Biblioteca (Library)
+
+Você pode usar o gerenciador de conexões resiliente deste projeto em sua própria aplicação Node.js.
+
+1.  **Instale a lib:**
+    ```bash
+    npm install replica-failover-mongodb-ts
+    ```
+
+2.  **Importe e use:**
+    ```typescript
+    import { ConnectionManager } from 'replica-failover-mongodb-ts';
+
+    const db = new ConnectionManager({
+        nodes: [
+            'mongodb://mongo1:27017/mydb',
+            'mongodb://mongo2:27017/mydb'
+        ],
+        healthCheckIntervalMs: 5000
+    });
+
+    await db.init();
+    const myCollection = db.getDb().collection('users');
+    ```
+
+---
+
 ## Visual Dashboard (Painel de Controle)
 
 Para uma experiência visual e interativa, utilize o nosso Dashboard via Terminal (TUI). Ele permite monitorar a topologia do cluster, gráficos de latência e controlar os nós (Stop/Start) manualmente.
@@ -106,6 +151,35 @@ Ao realizar testes de carga ou criar usuários via dashboard, a API retornará r
 
 ---
 
+## Uso Avançado do Dashboard (CLI)
+
+O dashboard pode ser configurado para monitorar **qualquer API** e **qualquer cluster MongoDB**, não apenas o deste projeto.
+
+```bash
+node-balancer-dashboard [opções]
+```
+
+### Opções Disponíveis
+
+| Flag | Descrição | Padrão |
+| :--- | :--- | :--- |
+| `--api-url` | URL da API para testar latência/requests | `http://localhost:3000/api/users` |
+| `--nodes` | Lista de URIs do MongoDB (separados por vírgula) | `mongodb://localhost:27017...` |
+| `--no-docker` | Desabilita controles do Docker (para clusters remotos) | `false` |
+
+### Exemplo Real
+
+Testando uma API de produção sem acesso ao Docker local:
+
+```bash
+node-balancer-dashboard \
+  --api-url https://api.minhaempresa.com/health \
+  --nodes mongodb://mongo-prod-1:27017,mongodb://mongo-prod-2:27017 \
+  --no-docker
+```
+
+---
+
 ## Testes e Automação (Chaos Testing)
 
 Se preferir rodar apenas o script de teste sem o dashboard visual:
@@ -185,3 +259,18 @@ Se você está utilizando o **MongoDB replica set**, certifique-se de que o repl
     ```javascript
     rs.status();
     ```
+
+---
+
+## Autor
+
+| [<img src="https://github.com/JoaoIto.png" width="100px;" alt="João Ito"/>](https://github.com/JoaoIto) |
+| :---: |
+| **João Ito** |
+| [GitHub](https://github.com/JoaoIto) • [Email](mailto:joaovictorpfr@gmail.com) |
+
+Feito com ❤️ por João Ito. Entre em contato!
+
+## Licença
+
+Este projeto está licenciado sob a licença ISC - veja o arquivo [LICENSE](LICENSE) para detalhes.

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionManager = void 0;
+var connectionManager_1 = require("./config/connectionManager");
+Object.defineProperty(exports, "ConnectionManager", { enumerable: true, get: function () { return connectionManager_1.ConnectionManager; } });

package/dist/scripts/dashboard.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 "use strict";
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -17,13 +18,21 @@ const blessed_contrib_1 = __importDefault(require("blessed-contrib"));
 const mongodb_1 = require("mongodb");
 const http_1 = __importDefault(require("http"));
 const child_process_1 = require("child_process");
-// Configuration
-const API_URL = 'http://localhost:3000/api/users';
-const NODES = [
-    { name: 'mongo1', uri: 'mongodb://localhost:27017/node-balancer' },
-    { name: 'mongo2', uri: 'mongodb://localhost:27018/node-balancer' },
-    { name: 'mongo3', uri: 'mongodb://localhost:27019/node-balancer' }
-];
+// Parse Args
+const args = process.argv.slice(2);
+function getArg(flag, def) {
+    const idx = args.indexOf(flag);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : def;
+}
+const API_URL = getArg('--api-url', 'http://localhost:3000/api/users');
+const NODES_ARG = getArg('--nodes', 'mongodb://localhost:27017/node-balancer,mongodb://localhost:27018/node-balancer,mongodb://localhost:27019/node-balancer');
+const DOCKER_CONTAINERS_ARG = getArg('--docker-containers', 'mongo1,mongo2,mongo3');
+const NO_DOCKER = args.includes('--no-docker');
+const NODES = NODES_ARG.split(',').map((uri, i) => ({
+    name: `node${i + 1}`,
+    uri: uri.trim()
+}));
+const DOCKER_NODES = DOCKER_CONTAINERS_ARG.split(',').map(n => n.trim());
 // Screen Setup
 const screen = blessed_1.default.screen({
     smartCSR: true,
@@ -64,11 +73,11 @@ const controls = grid.set(6, 8, 6, 4, blessed_1.default.list, {
     items: [
         'RUN CHAOS DEMO (Auto)',
         'SEND BATCH (2 POST + 1 GET)',
-        'STOP PRIMARY',
-        'START MONGO1',
-        'START MONGO2',
-        'START MONGO3',
-        'START STACK',
+        ...(NO_DOCKER ? [] : [
+            'STOP PRIMARY',
+            ...DOCKER_NODES.map(n => `START ${n.toUpperCase()}`),
+            'START STACK'
+        ]),
         'EXIT'
     ]
 });
@@ -155,7 +164,7 @@ function updateTopology() {
             try {
                 const client = new mongodb_1.MongoClient(node.uri, { serverSelectionTimeoutMS: 500, directConnection: true });
                 yield client.connect();
-                const db = client.db('node-balancer');
+                const db = client.db('node-balancer'); // Assuming DB name is consistent or part of URI, but here hardcoded for now or could be arg
                 const hello = yield db.command({ hello: 1 });
                 count = (yield db.collection('users').countDocuments()).toString();
                 yield client.close();
@@ -186,34 +195,43 @@ function runChaosDemo() {
         // Phase 1
         log('Phase 1: Healthy State');
         yield runBatch();
-        // Chaos
-        const primary = yield getPrimary();
-        if (primary) {
-            log(`💥 Stopping PRIMARY: ${primary}`);
-            try {
-                (0, child_process_1.execSync)(`docker stop ${primary}`);
-            }
-            catch (e) {
-                log('Error stopping node');
-            }
+        if (NO_DOCKER) {
+            log('Skipping Chaos (No Docker Mode)');
         }
         else {
-            log('No Primary found to stop!');
-        }
-        // Phase 2
-        log('Phase 2: Failover State');
-        yield sleep(2000);
-        yield runBatch();
-        // Recovery
-        log('Waiting 5s before recovery...');
-        yield sleep(5000);
-        if (primary) {
-            log(`♻️  Restarting ${primary}`);
-            try {
-                (0, child_process_1.execSync)(`docker start ${primary}`);
+            // Chaos
+            const primaryName = yield getPrimary(); // returns node1, node2...
+            // We need to map node name to container name if they differ, but here we assume index matching or we need smarter logic
+            // For simplicity in this generic version, let's try to find the container name based on index
+            const primaryIndex = NODES.findIndex(n => n.name === primaryName);
+            const containerName = primaryIndex !== -1 ? DOCKER_NODES[primaryIndex] : null;
+            if (containerName) {
+                log(`💥 Stopping PRIMARY: ${containerName}`);
+                try {
+                    (0, child_process_1.execSync)(`docker stop ${containerName}`);
+                }
+                catch (e) {
+                    log('Error stopping node');
+                }
             }
-            catch (e) {
-                log('Error starting node');
+            else {
+                log('No Primary found to stop!');
+            }
+            // Phase 2
+            log('Phase 2: Failover State');
+            yield sleep(2000);
+            yield runBatch();
+            // Recovery
+            log('Waiting 5s before recovery...');
+            yield sleep(5000);
+            if (containerName) {
+                log(`♻️  Restarting ${containerName}`);
+                try {
+                    (0, child_process_1.execSync)(`docker start ${containerName}`);
+                }
+                catch (e) {
+                    log('Error starting node');
+                }
             }
         }
         // Phase 3
@@ -233,11 +251,15 @@ controls.on('select', (item, index) => __awaiter(void 0, void 0, void 0, functio
         runBatch();
     }
     else if (cmd.includes('STOP PRIMARY')) {
-        const p = yield getPrimary();
-        if (p) {
-            log(`Stopping ${p}...`);
+        if (NO_DOCKER)
+            return log('Docker disabled.');
+        const pName = yield getPrimary();
+        const pIdx = NODES.findIndex(n => n.name === pName);
+        const container = pIdx !== -1 ? DOCKER_NODES[pIdx] : null;
+        if (container) {
+            log(`Stopping ${container}...`);
             try {
-                (0, child_process_1.execSync)(`docker stop ${p}`);
+                (0, child_process_1.execSync)(`docker stop ${container}`);
                 log('Stopped.');
             }
             catch (e) {
@@ -248,11 +270,15 @@ controls.on('select', (item, index) => __awaiter(void 0, void 0, void 0, functio
             log('No Primary found.');
         }
     }
-    else if (cmd.includes('START MONGO')) {
-        const node = cmd.split(' ')[1].toLowerCase();
-        log(`Starting ${node}...`);
+    else if (cmd.includes('START MONGO') || cmd.includes('START NODE')) { // Generic match
+        if (NO_DOCKER)
+            return log('Docker disabled.');
+        // Extract container name from string "START MONGO1"
+        const parts = cmd.split(' ');
+        const container = parts[1].toLowerCase(); // mongo1
+        log(`Starting ${container}...`);
         try {
-            (0, child_process_1.execSync)(`docker start ${node}`);
+            (0, child_process_1.execSync)(`docker start ${container}`);
             log('Started.');
         }
         catch (e) {
@@ -260,6 +286,8 @@ controls.on('select', (item, index) => __awaiter(void 0, void 0, void 0, functio
         }
     }
     else if (cmd.includes('START STACK')) {
+        if (NO_DOCKER)
+            return log('Docker disabled.');
         log('Starting stack...');
         try {
             (0, child_process_1.execSync)('docker-compose up -d');
@@ -278,6 +306,9 @@ setInterval(updateTopology, 2000);
 // Init
 controls.focus();
 log('Control Center Ready.');
+if (NO_DOCKER)
+    log('Docker Control: DISABLED');
+log(`API: ${API_URL}`);
 updateTopology();
 screen.render();
 // Exit

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "replica-failover-mongodb-ts",
-  "version": "2.0.5",
+  "version": "2.2.0",
   "description": "O sistema replica um dos conceitos básicos da arquitetura de sistemas distribuído, na qual ele tem uma API em express.js com TypeScript, e usando o mongoDB com replicaSET e failover, consegue automáticamente garantir disponibilidade e redundância de dados das requisições.",
-  "main": "dist/server.js",
-  "types": "dist/server.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "scripts": {
     "dev": "nodemon --exec ts-node src/server.ts",
     "build": "tsc",