kukuy 1.4.0

package/README.md

@@ -0,0 +1,251 @@
+# KUKUY
+
+Un balanceador de carga desarrollado en Node.js que distribuye solicitudes entre múltiples servidores backend usando el algoritmo RoundRobin.
+
+## Características
+
+- Distribución de carga usando algoritmo RoundRobin
+- Soporte para HTTP y HTTPS
+- Configuración mediante variables de entorno
+- Arquitectura modular con soporte para hooks y filtros
+- Verificación de salud de servidores backend
+- Enrutamiento basado en patrones
+- Sistema de logging detallado para servidores online/offline
+- Caching de respuestas para mejorar el rendimiento
+- Panel de control web para monitoreo
+
+## Instalación
+
+```bash
+npm install
+```
+
+## Configuración
+
+El balanceador se configura mediante variables de entorno:
+
+- `BALANCER_HTTP_PORT`: Puerto para conexiones HTTP (por defecto: 8080)
+- `BALANCER_HTTPS_PORT`: Puerto para conexiones HTTPS (opcional)
+- `CONFIG_FILE_PATH`: Ruta al archivo de configuración de servidores (por defecto: ./servers.json)
+- `ROUTES_FILE_PATH`: Ruta al archivo de configuración de rutas (por defecto: ./routes.json)
+- `LOAD_BALANCING_ALGORITHM`: Algoritmo de balanceo a usar ('roundrobin' o 'iphash') (por defecto: 'roundrobin')
+- `SSL_CERT_PATH`: Ruta al certificado SSL (requerido para HTTPS)
+- `SSL_KEY_PATH`: Ruta a la llave privada SSL (requerido para HTTPS)
+- `HEALTH_CHECK_INTERVAL`: Intervalo para verificación de salud en ms (por defecto: 30000)
+- `LOG_LEVEL`: Nivel de logging (info, warn, error, debug) (por defecto: info)
+- `LOG_FILE_PATH`: Ruta al archivo de logs (por defecto: ./balancer.log)
+
+## Archivos de Configuración
+
+### servers.json
+Define los servidores backend:
+
+```json
+{
+  "servers": [
+    {
+      "url": "http://localhost:3001",
+      "weight": 1,
+      "tags": ["api"],
+      "active": true
+    },
+    {
+      "url": "http://localhost:3002",
+      "weight": 1,
+      "tags": ["api"],
+      "active": true
+    }
+  ]
+}
+```
+
+### routes.json
+Define las reglas de enrutamiento para dirigir solicitudes específicas a grupos particulares de servidores backend basados en patrones de URL:
+
+```json
+{
+  "routes": [
+    {
+      "path": "/api/*",
+      "methods": ["GET", "POST", "PUT", "DELETE"],
+      "target": "api"
+    },
+    {
+      "path": "/*",
+      "methods": ["*"],
+      "target": "web"
+    }
+  ]
+}
+```
+
+Las rutas permiten una distribución selectiva del tráfico:
+- Las rutas definen patrones de URL (usando comodín `*`) y métodos HTTP permitidos
+- El campo `target` especifica la etiqueta de servidores backend a los que se dirigirá la solicitud
+- Por ejemplo, todas las solicitudes que empiezan con `/api/` se enviarán solo a servidores que tengan la etiqueta "api"
+- Las solicitudes que no coincidan con ninguna ruta específica se distribuirán entre todos los servidores disponibles
+
+## Uso
+
+### Iniciar en modo producción:
+```bash
+npm start
+```
+
+### Iniciar en modo desarrollo:
+```bash
+npm run dev
+```
+
+### Con variables de entorno personalizadas:
+```bash
+BALANCER_HTTP_PORT=9090 BALANCER_HTTPS_PORT=9443 CONFIG_FILE_PATH=./my-servers.json npm start
+```
+
+### Con algoritmo de balanceo específico:
+```bash
+# Usar algoritmo RoundRobin (predeterminado)
+LOAD_BALANCING_ALGORITHM=roundrobin npm start
+
+# Usar algoritmo IPHash
+LOAD_BALANCING_ALGORITHM=iphash npm start
+```
+
+### Scripts de inicio predefinidos:
+
+#### Iniciar con algoritmo RoundRobin:
+```bash
+./start-roundrobin.sh
+```
+
+#### Iniciar con algoritmo IPHash:
+```bash
+./start-iphash.sh
+```
+
+Los scripts utilizan la configuración por defecto y el puerto 8080. Puedes modificarlos según tus necesidades.
+
+### API del Panel Web
+
+El balanceador incluye una API REST para monitoreo en tiempo real:
+
+#### Endpoints disponibles:
+- `GET /api/status` - Estado general del balanceador
+- `GET /api/metrics` - Métricas generales de rendimiento
+- `GET /api/servers` - Estado de los servidores backend
+- `GET /api/server-stats` - Estadísticas detalladas por servidor
+
+#### Ejemplo de respuesta de estadísticas por servidor:
+```json
+{
+  "serverStats": {
+    "1": {
+      "id": 1,
+      "totalRequests": 10,
+      "successfulRequests": 10,
+      "failedRequests": 0,
+      "totalResponseTime": 1250,
+      "minResponseTime": 5,
+      "maxResponseTime": 346,
+      "avgResponseTime": 125,
+      "responseCodes": {"200": 10},
+      "lastActive": 1769298297602,
+      "responseTimes": [346, 7, 7, 12, 45, 67, 89, 102, 115, 120]
+    }
+  }
+}
+```
+
+## Hooks Disponibles
+
+- `onRequestReceived`: Se ejecuta cuando se recibe una solicitud
+- `onServerSelected`: Se ejecuta después de seleccionar un servidor backend
+- `onResponseSent`: Se ejecuta cuando se envía la respuesta al cliente
+- `onServerError`: Se ejecuta cuando ocurre un error con un servidor backend
+
+## Filtros Disponibles
+
+- `AuthenticationFilter`: Verificación de autenticación
+- `RateLimitFilter`: Control de límite de peticiones
+- `LoggingFilter`: Registro de solicitudes
+- `CachingFilter`: Caché de respuestas
+
+## Componentes Implementados
+
+### Core
+- `Balancer.js`: Punto de entrada principal del sistema
+- `ServerPool.js`: Gestión del conjunto de servidores backend
+- `RequestHandler.js`: Manejo de solicitudes entrantes (integrado en Balancer.js)
+
+### Algoritmos
+- `LoadBalancingAlgorithm.js`: Interfaz base para algoritmos de balanceo
+- `RoundRobinAlgorithm.js`: Implementación del algoritmo RoundRobin como plugin
+- `IPHashAlgorithm.js`: Implementación del algoritmo IPHash como plugin con asociación persistente IP-servidor
+- `AlgorithmManager.js`: Gestor de algoritmos de balanceo con selección dinámica
+
+### Configuración
+- `ConfigManager.js`: Lee y procesa variables de entorno
+- `RouteLoader.js`: Carga rutas y paths desde archivos de configuración
+
+### Protocolos
+- `HttpBalancer.js`: Manejo de conexiones HTTP
+- `HttpsBalancer.js`: Manejo de conexiones HTTPS
+
+### Extensibilidad
+- `HookManager.js`: Integración con `jerk-hooked-lib`
+- `FilterChain.js`: Aplicación de filters a las solicitudes
+
+### Utilidades
+- `Logger.js`: Sistema de logging
+- `BalancerLogger.js`: Sistema de logging detallado para servidores online/offline
+- `HealthChecker.js`: Verificación de estado de servidores backend
+- `MetricsCollector.js`: Recolección de métricas de rendimiento
+
+## Componentes No Implementados (Mejoras Futuras)
+
+### Funcionalidades Avanzadas
+- **Hot Reload de Configuración**: Actualización de configuración sin reinicio (requiere implementación de listeners de cambio de archivos)
+- **API REST para Gestión de Servidores**: Endpoint para añadir/eliminar servidores dinámicamente
+- **Sistema de Alertas**: Notificaciones cuando servidores caen o se recuperan
+- **Soporte para WebSocket**: Balanceo de conexiones WebSocket
+- **Compresión de Respuestas**: Soporte para Gzip/Brotli
+- **Persistencia de Sesión**: Sticky sessions basadas en cookies o IP
+
+### Algoritmos de Balanceo Adicionales
+- **Weighted Round Robin**: Balanceo con pesos por servidor
+- **Least Connections**: Enviar a servidor con menos conexiones
+- **IP Hash**: Distribución basada en dirección IP del cliente
+
+## Pruebas
+
+### Prueba de Estrés
+El proyecto incluye un script de prueba de estrés:
+```bash
+DURATION_SECONDS=30 CONCURRENT_REQUESTS=20 node stress-test.js
+```
+
+## Issues Conocidos
+
+### Actualización de Estado de Servidores
+El dashboard no refleja en tiempo real cuando servidores se vuelven offline o se levantan después de iniciar el balanceador. La información de estado de los servidores puede no actualizar inmediatamente cuando un servidor backend cambia de estado.
+
+Para más detalles, véase el archivo [ISSUES.md](./ISSUES.md).
+
+## Licencia
+
+Este proyecto está licenciado bajo la Licencia Pública General GNU (GPL) versión 3 o posterior.
+
+Copyright (C) 2026 Desarrollador
+
+Este programa es software libre: usted puede redistribuirlo y/o modificarlo
+bajo los términos de la Licencia Pública General GNU publicada por la
+Free Software Foundation, ya sea la versión 3 de la Licencia, o
+(a su elección) cualquier versión posterior.
+
+Este programa se distribuye con la esperanza de que sea útil, pero
+SIN NINGUNA GARANTÍA; ni siquiera la garantía implícita de
+COMERCIABILIDAD o IDONEIDAD PARA UN PROPÓSITO PARTICULAR.
+Consulte la Licencia Pública General GNU para obtener más detalles.
+
+Debería haber recibido una copia de la Licencia Pública General GNU
+junto con este programa. Si no, consulte <https://www.gnu.org/licenses/>.

package/kukuy.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+const { Balancer } = require('./src/core/Balancer');
+
+// Iniciar el balanceador
+const balancer = new Balancer();
+balancer.start();
+
+console.log('Balanceador RoundRobin iniciado');
+console.log(`Panel web disponible en: http://localhost:${process.env.DASHBOARD_PORT || 8082}`);
+
+// Manejar señales de interrupción
+process.on('SIGINT', () => {
+  console.log('\nCerrando balanceador...');
+  balancer.stop();
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  console.log('Recibida señal SIGTERM, cerrando...');
+  balancer.stop();
+  process.exit(0);
+});

package/kukuy.workspace

@@ -0,0 +1,11 @@
+{
+ "NodeJS": {
+  "metadata": {
+   "version": "1.0",
+   "ide": "CodeLite",
+   "type": "NodeJS"
+  },
+  "folders": ["."],
+  "m_showHiddenFiles": false
+ }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "kukuy",
+  "version": "1.4.0",
+  "description": "Balanceador de carga Backend",
+  "main": "kukuy.js",
+  "scripts": {
+    "start": "node kukuy.js",
+    "dev": "BALANCER_HTTP_PORT=8080 node kukuy.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "load-balancer",
+    "round-robin",
+    "ip-hash",
+    "proxy",
+    "http",
+    "https"
+  ],
+  "author": "Benjamín Sánchez Cárdenas",
+  "license": "GPL-3.0-or-later",
+  "dependencies": {
+    "jerk-hooked-lib": "^2.0.0",
+    "ws": "^8.19.0"
+  },
+  "type": "commonjs"
+}

package/restart-balancer.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Script para matar e iniciar KUKUY con estadísticas por servidor y WebSocket
+
+echo "Matando procesos existentes de KUKUY..."
+pkill -f "node kukuy.js" 2>/dev/null || true
+
+sleep 2
+
+echo "Iniciando KUKUY con estadísticas por servidor y WebSocket..."
+LOAD_BALANCING_ALGORITHM=roundrobin CONFIG_FILE_PATH=./servers_real.json BALANCER_HTTP_PORT=8088 DASHBOARD_PORT=8082 WEBSOCKET_PORT=8084 node kukuy.js

package/routes.json

@@ -0,0 +1,14 @@
+{
+  "routes": [
+    {
+      "path": "/api/*",
+      "methods": ["GET", "POST", "PUT", "DELETE"],
+      "target": "api"
+    },
+    {
+      "path": "/*",
+      "methods": ["*"],
+      "target": "web"
+    }
+  ]
+}

package/scripts/load_test.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+Script de prueba de carga concurrente para el balanceador
+"""
+
+import threading
+import time
+import requests
+import sys
+from datetime import datetime
+
+# Configuración
+BASE_URL = "http://localhost:8081"
+ENDPOINT = "/api/endpoints"
+NUM_THREADS = 100  # Número de hilos concurrentes para alta carga
+REQUESTS_PER_THREAD = 6000  # Solicitudes por hilo (100 hilos * 60 solicitudes = 6000 solicitudes totales por segundo)
+DURATION_SECONDS = 120  # Duración de la prueba en segundos (2 minutos)
+TARGET_RPS = 5000  # Objetivo de solicitudes por segundo
+
+# Variables globales para métricas
+total_requests = 0
+successful_requests = 0
+failed_requests = 0
+lock = threading.Lock()
+
+def make_requests_continuous(thread_id, end_time_target):
+    """Función que realiza solicitudes HTTP continuas hasta alcanzar la duración objetivo"""
+    global total_requests, successful_requests, failed_requests
+
+    thread_start_time = time.time()
+    thread_successful = 0
+    thread_failed = 0
+
+    # Calcular el intervalo entre solicitudes para alcanzar el objetivo RPS
+    interval = 1.0 / (TARGET_RPS / NUM_THREADS) if NUM_THREADS > 0 else 0.001  # Evitar división por cero
+
+    while time.time() < end_time_target:
+        try:
+            response = requests.get(f"{BASE_URL}{ENDPOINT}", timeout=10)
+            with lock:
+                total_requests += 1
+                if response.status_code == 200:
+                    successful_requests += 1
+                    thread_successful += 1
+                else:
+                    failed_requests += 1
+                    thread_failed += 1
+        except requests.exceptions.RequestException as e:
+            with lock:
+                total_requests += 1
+                failed_requests += 1
+                thread_failed += 1
+            if thread_id == 0:  # Solo imprimir errores para el primer hilo
+                print(f"[Thread-{thread_id}] Error en solicitud: {e}")
+
+        # Esperar el intervalo calculado para alcanzar el objetivo RPS
+        time.sleep(interval)
+
+    thread_end_time = time.time()
+    thread_duration = thread_end_time - thread_start_time
+
+    print(f"[Thread-{thread_id}] Completado: {thread_successful} exitosas, {thread_failed} fallidas en {thread_duration:.2f}s")
+
+
+def make_requests(thread_id):
+    """Función original que realiza solicitudes HTTP en un hilo (mantenida por compatibilidad)"""
+    global total_requests, successful_requests, failed_requests
+
+    thread_start_time = time.time()
+    thread_successful = 0
+    thread_failed = 0
+
+    for i in range(REQUESTS_PER_THREAD):
+        try:
+            response = requests.get(f"{BASE_URL}{ENDPOINT}", timeout=10)
+            with lock:
+                total_requests += 1
+                if response.status_code == 200:
+                    successful_requests += 1
+                    thread_successful += 1
+                else:
+                    failed_requests += 1
+                    thread_failed += 1
+        except requests.exceptions.RequestException as e:
+            with lock:
+                total_requests += 1
+                failed_requests += 1
+                thread_failed += 1
+            if thread_id == 0:  # Solo imprimir errores para el primer hilo
+                print(f"[Thread-{thread_id}] Error en solicitud {i+1}: {e}")
+
+    thread_end_time = time.time()
+    thread_duration = thread_end_time - thread_start_time
+
+    print(f"[Thread-{thread_id}] Completado: {thread_successful} exitosas, {thread_failed} fallidas en {thread_duration:.2f}s")
+
+def run_load_test():
+    """Función principal que ejecuta la prueba de carga"""
+    global total_requests, successful_requests, failed_requests
+
+    print(f"Iniciando prueba de carga...")
+    print(f"- URL base: {BASE_URL}")
+    print(f"- Endpoint: {ENDPOINT}")
+    print(f"- Hilos concurrentes: {NUM_THREADS}")
+    print(f"- Solicitudes por hilo: {REQUESTS_PER_THREAD}")
+    print(f"- Duración: {DURATION_SECONDS} segundos")
+    print(f"- Objetivo RPS: {TARGET_RPS}")
+    print("-" * 50)
+
+    start_time = time.time()
+    end_time_target = start_time + DURATION_SECONDS
+
+    # Crear y arrancar hilos
+    threads = []
+    for i in range(NUM_THREADS):
+        thread = threading.Thread(target=make_requests_continuous, args=(i, end_time_target))
+        threads.append(thread)
+        thread.start()
+
+        # Pequeño retraso entre la creación de hilos para evitar congestión
+        time.sleep(0.001)
+
+    # Esperar a que todos los hilos terminen
+    for thread in threads:
+        thread.join()
+
+    actual_duration = time.time() - start_time
+
+    # Mostrar resultados
+    print("-" * 50)
+    print("RESULTADOS DE LA PRUEBA DE CARGA:")
+    print(f"Tiempo total: {actual_duration:.2f} segundos")
+    print(f"Solicitudes totales: {total_requests}")
+    print(f"Solicitudes exitosas: {successful_requests}")
+    print(f"Solicitudes fallidas: {failed_requests}")
+    print(f"Tasa de éxito: {(successful_requests/total_requests*100) if total_requests > 0 else 0:.2f}%")
+    print(f"RPS Real (Solicitudes por segundo): {total_requests/actual_duration if actual_duration > 0 else 0:.2f}")
+    print(f"RPS Objetivo: {TARGET_RPS}")
+
+    if successful_requests > 0:
+        print(f"RPS Exitoso (Solicitudes exitosas por segundo): {successful_requests/actual_duration if actual_duration > 0 else 0:.2f}")
+
+if __name__ == "__main__":
+    try:
+        run_load_test()
+    except KeyboardInterrupt:
+        print("\nPrueba interrumpida por el usuario.")
+        print(f"Resultados parciales:")
+        print(f"- Solicitudes totales: {total_requests}")
+        print(f"- Solicitudes exitosas: {successful_requests}")
+        print(f"- Solicitudes fallidas: {failed_requests}")

package/servers.json

@@ -0,0 +1,19 @@
+{
+  "servers": [
+    {
+      "url": "http://localhost:3001",
+      "weight": 1,
+      "tags": ["api"]
+    },
+    {
+      "url": "http://localhost:3002",
+      "weight": 1,
+      "tags": ["api"]
+    },
+    {
+      "url": "http://localhost:3003",
+      "weight": 1,
+      "tags": ["web"]
+    }
+  ]
+}

package/servers_real.json

@@ -0,0 +1,19 @@
+{
+  "servers": [
+    {
+      "url": "http://localhost:3434",
+      "weight": 1,
+      "tags": ["backend"]
+    },
+    {
+      "url": "http://localhost:8765",
+      "weight": 1,
+      "tags": ["backend"]
+    },
+    {
+      "url": "http://localhost:5445",
+      "weight": 1,
+      "tags": ["backend"]
+    }
+  ]
+}

package/src/algorithms/AlgorithmManager.js

@@ -0,0 +1,85 @@
+const { RoundRobinAlgorithm } = require('./RoundRobinAlgorithm');
+const { IPHashAlgorithm } = require('./IPHashAlgorithm');
+
+/**
+ * Gestor de algoritmos de balanceo de carga
+ */
+class AlgorithmManager {
+  constructor() {
+    this.algorithms = new Map();
+    this.currentAlgorithm = null;
+    this.defaultAlgorithm = 'roundrobin';
+    
+    // Registrar algoritmos por defecto
+    this.registerAlgorithm(new RoundRobinAlgorithm());
+    this.registerAlgorithm(new IPHashAlgorithm());
+  }
+
+  /**
+   * Registra un nuevo algoritmo
+   * @param {LoadBalancingAlgorithm} algorithm - Instancia del algoritmo
+   */
+  registerAlgorithm(algorithm) {
+    this.algorithms.set(algorithm.getName(), algorithm);
+  }
+
+  /**
+   * Obtiene un algoritmo por su nombre
+   * @param {string} name - Nombre del algoritmo
+   * @returns {LoadBalancingAlgorithm|null} Algoritmo o null si no existe
+   */
+  getAlgorithm(name) {
+    return this.algorithms.get(name) || null;
+  }
+
+  /**
+   * Establece el algoritmo actual a usar
+   * @param {string} name - Nombre del algoritmo
+   * @returns {boolean} True si el algoritmo existe y se estableció
+   */
+  setCurrentAlgorithm(name) {
+    const algorithm = this.getAlgorithm(name);
+    if (algorithm) {
+      this.currentAlgorithm = algorithm;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Obtiene el algoritmo actual
+   * @returns {LoadBalancingAlgorithm|null} Algoritmo actual o null si no está establecido
+   */
+  getCurrentAlgorithm() {
+    return this.currentAlgorithm;
+  }
+
+  /**
+   * Selecciona un servidor usando el algoritmo actual
+   * @param {Array} servers - Lista de servidores disponibles
+   * @param {Object} requestContext - Contexto de la solicitud
+   * @returns {Object|null} Servidor seleccionado o null si no hay disponibles
+   */
+  selectServer(servers, requestContext = {}) {
+    if (!this.currentAlgorithm) {
+      // Si no hay algoritmo actual, usar el predeterminado
+      this.setCurrentAlgorithm(this.defaultAlgorithm);
+    }
+    
+    if (this.currentAlgorithm) {
+      return this.currentAlgorithm.selectServer(servers, requestContext);
+    }
+    
+    return null;
+  }
+
+  /**
+   * Obtiene la lista de nombres de algoritmos disponibles
+   * @returns {Array<string>} Lista de nombres de algoritmos
+   */
+  getAvailableAlgorithms() {
+    return Array.from(this.algorithms.keys());
+  }
+}
+
+module.exports = { AlgorithmManager };