kukuy 1.6.0 → 1.9.0

package/README.md

@@ -9,9 +9,12 @@ KUKUY es un  sistema de balanceo de carga backend desarrollado en Node.js que pe
 - **Panel de Control Web**: Interfaz gráfica para monitorear el estado del sistema
 - **Sistema de Plugins**: Arquitectura extensible mediante plugins
 - **Hooks y Filtros**: Capacidad para interceptar y modificar solicitudes/responses
+- **Sistema de Cache Robusto**: Almacenamiento en memoria con TTL configurable y política LRU
 - **Rutas Personalizadas**: Configuración flexible de rutas para diferentes grupos de servidores
 - **Monitoreo en Tiempo Real**: Métricas detalladas sobre rendimiento y estado de servidores
 - **Reintento Inteligente**: Reenvío automático de solicitudes a servidores alternativos en caso de fallo
+- **Verificación de Salud Periódica**: Sistema automatizado que verifica regularmente la salud de los servidores backend
+- **Monitoreo de Eventos de Salud**: Registro y seguimiento detallado de eventos relacionados con la verificación de salud
 
 ## Configuración
 
@@ -75,7 +78,7 @@ Define las rutas y a qué grupo de servidores deben dirigirse:
 - `SSL_KEY_PATH`: Ruta a la llave privada SSL
 - `DASHBOARD_PORT`: Puerto del panel de control web (por defecto 8082)
 - `WEBSOCKET_PORT`: Puerto del servidor WebSocket (por defecto 8083)
-- `HEALTH_CHECK_INTERVAL`: Intervalo de verificación de salud de servidores
+- `HEALTH_CHECK_INTERVAL`: Intervalo de verificación de salud de servidores (en milisegundos, por defecto 30000)
 - `LOG_LEVEL`: Nivel de logging (por defecto 'info')
 
 ## Algoritmos de Balanceo
@@ -119,6 +122,32 @@ KUKUY incluye un panel de control web accesible en `http://localhost:8082` (por
 
 La arquitectura de KUKUY permite extender su funcionalidad mediante plugins. Los plugins se colocan en el directorio `kukuy-plugins/` y deben incluir un archivo `manifest.json` con la configuración del plugin.
 
+## Plugins de Verificación de Salud
+
+KUKUY incluye dos plugins especializados para la gestión de la salud de los servidores backend:
+
+### Plugin de Verificación de Salud Periódica (`health-checker`)
+
+Este plugin implementa un sistema de verificación de salud proactivo que:
+
+- Verifica la salud de todos los servidores backend en intervalos regulares
+- Utiliza la configuración `HEALTH_CHECK_INTERVAL` para determinar la frecuencia de verificación
+- Se comunica con el endpoint `/health` de cada servidor para determinar su estado
+- Actualiza dinámicamente el estado de salud de los servidores en el pool
+- Integra con el sistema de hooks para notificar eventos de salud
+
+### Plugin de Monitoreo de Eventos de Salud (`health-monitor`)
+
+Este plugin proporciona monitoreo y registro detallado de los eventos relacionados con la salud de los servidores:
+
+- Registra eventos cuando comienza una verificación de salud
+- Muestra el resultado de las verificaciones (saludable/no saludable)
+- Captura y registra errores, timeouts y excepciones durante las verificaciones
+- Proporciona alertas cuando un servidor no está saludable
+- Muestra información detallada sobre el estado de los servidores
+
+Ambos plugins trabajan juntos para proporcionar un sistema completo de monitoreo de salud que va más allá de la verificación reactiva (solo cuando un servidor falla) hacia un enfoque proactivo que mantiene un seguimiento constante del estado de los servidores backend.
+
 ### Estructura de un Plugin
 
 Un plugin típico incluye:
@@ -147,13 +176,40 @@ Ejemplo de `manifest.json`:
 Permiten ejecutar código en puntos específicos del ciclo de vida de una solicitud:
 - `onRequestReceived`: Cuando se recibe una solicitud
 - `onServerSelected`: Después de seleccionar un servidor destino
-- `onResponseSent`: Antes de enviar la respuesta al cliente
+- `onResponseReady`: Antes de enviar la respuesta al cliente (permite interceptar la respuesta del servidor backend)
+- `onResponseSent`: Después de enviar la respuesta al cliente
 - `onServerError`: Cuando ocurre un error con un servidor backend
 
 ### Filtros
 Permiten interceptar y potencialmente modificar o bloquear solicitudes antes de que sean procesadas:
-- Se pueden aplicar filtros de solicitud (`request`)
+- Se pueden aplicar filtros de solicitud (`request_processing`)
 - Permiten implementar lógica de seguridad, autenticación, etc.
+- Soportan prioridades para controlar el orden de ejecución
+
+### Sistema de Cache Robusto
+KUKUY incluye un sistema avanzado de cache que:
+- Almacena respuestas en memoria con TTL (Time To Live) configurable
+- Implementa política LRU (Least Recently Used) para manejo de espacio
+- Permite configurar métodos HTTP cacheables (por defecto: GET)
+- Soporta códigos de estado cacheables (por defecto: 200, 201, 204)
+- Incluye limpieza automática de entradas expiradas
+- Ofrece estadísticas detalladas sobre el uso de la caché
+- Se integra completamente con el sistema de hooks y filtros
+
+Los plugins de cache pueden:
+- Interceptar solicitudes para verificar si están en caché
+- Almacenar respuestas del servidor backend en caché
+- Servir respuestas directamente desde la caché sin contactar al servidor backend
+- Configurar TTL por defecto y reglas de expiración
+- Implementar compresión opcional de contenido cacheado
+- Tienen la máxima prioridad (0) para asegurar que se ejecuten antes que otros plugins
+
+### Jerarquía de Prioridades
+- **Prioridad 0**: Plugin de cache (máxima prioridad)
+- **Prioridad 1-4**: Otros plugins críticos
+- **Prioridad 5**: Plugin de ejemplo y otros plugins estándar
+- **Prioridad 6-9**: Plugins de funcionalidad intermedia
+- **Prioridad 10+**: Manejadores de errores y eventos especiales
 
 ## Seguridad
 

package/balancer.log

@@ -1,2 +1,30 @@
 {"timestamp":"2026-01-30T19:04:05.202Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":631,"statusCode":200}}
 {"timestamp":"2026-01-30T19:04:34.272Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":56,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:23.725Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/registerSession","method":"POST","responseTime":727,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:24.900Z","level":"INFO","message":"Servidor ONLINE - ID: 2, URL: http://localhost:8765","eventType":"target_online","serverId":2,"serverUrl":"http://localhost:8765","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":525,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:38.252Z","level":"INFO","message":"Servidor ONLINE - ID: 3, URL: http://localhost:5445","eventType":"target_online","serverId":3,"serverUrl":"http://localhost:5445","request":{"url":"/track/registerSession","method":"POST","responseTime":663,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:39.346Z","level":"INFO","message":"Servidor ONLINE - ID: 4, URL: http://localhost:6666","eventType":"target_online","serverId":4,"serverUrl":"http://localhost:6666","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":524,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:47.856Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/registerSession","method":"POST","responseTime":58,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:48.459Z","level":"INFO","message":"Servidor ONLINE - ID: 2, URL: http://localhost:8765","eventType":"target_online","serverId":2,"serverUrl":"http://localhost:8765","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":55,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:51.323Z","level":"INFO","message":"Servidor ONLINE - ID: 3, URL: http://localhost:5445","eventType":"target_online","serverId":3,"serverUrl":"http://localhost:5445","request":{"url":"/track/registerSession","method":"POST","responseTime":81,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:51.938Z","level":"INFO","message":"Servidor ONLINE - ID: 4, URL: http://localhost:6666","eventType":"target_online","serverId":4,"serverUrl":"http://localhost:6666","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":39,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:57.742Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/registerSession","method":"POST","responseTime":73,"statusCode":200}}
+{"timestamp":"2026-01-30T20:17:58.347Z","level":"INFO","message":"Servidor ONLINE - ID: 2, URL: http://localhost:8765","eventType":"target_online","serverId":2,"serverUrl":"http://localhost:8765","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":52,"statusCode":200}}
+{"timestamp":"2026-01-30T20:18:16.831Z","level":"INFO","message":"Servidor ONLINE - ID: 3, URL: http://localhost:5445","eventType":"target_online","serverId":3,"serverUrl":"http://localhost:5445","request":{"url":"/track/registerSession","method":"POST","responseTime":98,"statusCode":200}}
+{"timestamp":"2026-01-30T20:18:17.792Z","level":"INFO","message":"Servidor ONLINE - ID: 4, URL: http://localhost:6666","eventType":"target_online","serverId":4,"serverUrl":"http://localhost:6666","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":400,"statusCode":200}}
+{"timestamp":"2026-01-30T20:21:10.507Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/registerSession","method":"POST","responseTime":135,"statusCode":200}}
+{"timestamp":"2026-01-30T20:21:11.101Z","level":"INFO","message":"Servidor ONLINE - ID: 2, URL: http://localhost:8765","eventType":"target_online","serverId":2,"serverUrl":"http://localhost:8765","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":47,"statusCode":200}}
+{"timestamp":"2026-01-30T20:21:27.474Z","level":"INFO","message":"Servidor ONLINE - ID: 3, URL: http://localhost:5445","eventType":"target_online","serverId":3,"serverUrl":"http://localhost:5445","request":{"url":"/track/registerSession","method":"POST","responseTime":35,"statusCode":200}}
+{"timestamp":"2026-01-30T20:21:28.076Z","level":"INFO","message":"Servidor ONLINE - ID: 4, URL: http://localhost:6666","eventType":"target_online","serverId":4,"serverUrl":"http://localhost:6666","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":53,"statusCode":200}}
+{"timestamp":"2026-01-30T20:22:15.368Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/registerSession","method":"POST","responseTime":121,"statusCode":200}}
+{"timestamp":"2026-01-30T20:22:16.014Z","level":"INFO","message":"Servidor ONLINE - ID: 2, URL: http://localhost:8765","eventType":"target_online","serverId":2,"serverUrl":"http://localhost:8765","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":58,"statusCode":200}}
+{"timestamp":"2026-01-30T20:22:29.162Z","level":"INFO","message":"Servidor ONLINE - ID: 3, URL: http://localhost:5445","eventType":"target_online","serverId":3,"serverUrl":"http://localhost:5445","request":{"url":"/track/registerSession","method":"POST","responseTime":48,"statusCode":200}}
+{"timestamp":"2026-01-30T20:22:29.742Z","level":"INFO","message":"Servidor ONLINE - ID: 4, URL: http://localhost:6666","eventType":"target_online","serverId":4,"serverUrl":"http://localhost:6666","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":37,"statusCode":200}}
+{"timestamp":"2026-01-30T20:23:10.703Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/registerSession","method":"POST","responseTime":123,"statusCode":200}}
+{"timestamp":"2026-01-30T20:23:11.347Z","level":"INFO","message":"Servidor ONLINE - ID: 2, URL: http://localhost:8765","eventType":"target_online","serverId":2,"serverUrl":"http://localhost:8765","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":82,"statusCode":200}}
+{"timestamp":"2026-01-30T20:23:25.118Z","level":"INFO","message":"Servidor ONLINE - ID: 3, URL: http://localhost:5445","eventType":"target_online","serverId":3,"serverUrl":"http://localhost:5445","request":{"url":"/track/registerSession","method":"POST","responseTime":32,"statusCode":200}}
+{"timestamp":"2026-01-30T20:23:25.726Z","level":"INFO","message":"Servidor ONLINE - ID: 4, URL: http://localhost:6666","eventType":"target_online","serverId":4,"serverUrl":"http://localhost:6666","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":29,"statusCode":200}}
+{"timestamp":"2026-01-30T20:26:32.857Z","level":"INFO","message":"Servidor ONLINE - ID: 1, URL: http://localhost:3434","eventType":"target_online","serverId":1,"serverUrl":"http://localhost:3434","request":{"url":"/track/registerSession","method":"POST","responseTime":145,"statusCode":200}}
+{"timestamp":"2026-01-30T20:26:33.445Z","level":"INFO","message":"Servidor ONLINE - ID: 2, URL: http://localhost:8765","eventType":"target_online","serverId":2,"serverUrl":"http://localhost:8765","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":27,"statusCode":200}}
+{"timestamp":"2026-01-30T20:26:36.917Z","level":"INFO","message":"Servidor ONLINE - ID: 3, URL: http://localhost:5445","eventType":"target_online","serverId":3,"serverUrl":"http://localhost:5445","request":{"url":"/track/registerSession","method":"POST","responseTime":73,"statusCode":200}}
+{"timestamp":"2026-01-30T20:26:37.556Z","level":"INFO","message":"Servidor ONLINE - ID: 4, URL: http://localhost:6666","eventType":"target_online","serverId":4,"serverUrl":"http://localhost:6666","request":{"url":"/track/insertSiteFlow","method":"POST","responseTime":28,"statusCode":200}}

package/kukuy-plugins/README.md

@@ -1,12 +1,67 @@
-# Sistema de Plugins para Kukuy
+# Plugins de Kukuy
 
-## Introducción
+Este directorio contiene plugins para extender la funcionalidad del balanceador Kukuy.
 
-Kukuy incluye un sistema de plugins que permite extender su funcionalidad sin modificar el código base. Los plugins se almacenan en el directorio `kukuy-plugins/` y se cargan automáticamente al iniciar Kukuy.
+## Plugins Disponibles
 
-## Estructura de un Plugin
+### 1. Plugin de Cache Robusto (`cache-plugin`)
 
-Cada plugin debe tener la siguiente estructura:
+Este plugin implementa un sistema de cache robusto que permite almacenar en caché las respuestas del servidor backend para mejorar el rendimiento.
+
+#### Características:
+- Soporta diferentes métodos HTTP cacheables (por defecto: GET)
+- Configurable mediante variables de entorno
+- Implementa LRU (Least Recently Used) para manejar el tamaño máximo de caché
+- Soporta TTL (Time To Live) configurable
+- Limpieza automática de entradas expiradas
+
+#### Variables de entorno:
+- `CACHE_MAX_SIZE`: Número máximo de entradas en la caché (por defecto: 100)
+- `CACHE_DEFAULT_TTL`: Tiempo de vida por defecto en milisegundos (por defecto: 300000 - 5 minutos)
+- `CACHE_ENABLE_COMPRESSION`: Habilitar compresión (por defecto: false)
+- `CACHEABLE_METHODS`: Métodos HTTP cacheables separados por coma (por defecto: GET)
+- `CACHEABLE_STATUS_CODES`: Códigos de estado cacheables separados por coma (por defecto: 200,201,204)
+
+#### Uso:
+El plugin se activa automáticamente si está habilitado en el manifest.json.
+
+### 2. Plugin de Redirección (`redirect-plugin`)
+
+Este plugin permite implementar reglas de redirección personalizadas.
+
+#### Características:
+- Soporta patrones de URL con expresiones regulares
+- Tipos de redirección: temporal (302) y permanente (301)
+- Configurable mediante variables de entorno
+
+#### Variables de entorno:
+- `REDIRECT_RULES`: Reglas de redirección en formato JSON
+
+#### Ejemplo de regla de redirección:
+```json
+[
+  {
+    "pattern": "/old-page",
+    "target": "/new-page",
+    "type": "permanent"
+  },
+  {
+    "pattern": "^/api/v1/(.*)$",
+    "target": "/api/v2/$1",
+    "type": "temporary"
+  }
+]
+```
+
+## Cómo Crear un Nuevo Plugin
+
+Para crear un nuevo plugin, sigue estos pasos:
+
+1. Crea un directorio con el nombre de tu plugin en `kukuy-plugins/`
+2. Crea un archivo `manifest.json` con la información del plugin
+3. Crea un archivo `index.js` con la lógica del plugin
+
+### Estructura de un Plugin
 
 ```
 kukuy-plugins/
@@ -15,16 +70,14 @@ kukuy-plugins/
     └── index.js
 ```
 
-## Manifest
-
-El archivo `manifest.json` debe contener:
+### Ejemplo de `manifest.json`:
 
 ```json
 {
-  "name": "Nombre del Plugin",
+  "name": "Mi Plugin",
   "version": "1.0.0",
-  "description": "Descripción del plugin",
-  "author": "Autor del plugin",
+  "description": "Descripción de mi plugin",
+  "author": "Autor",
   "main": "index.js",
   "kukuyVersion": "^1.6.0",
   "hooks": ["onRequestReceived", "onResponseSent"],
@@ -33,59 +86,40 @@ El archivo `manifest.json` debe contener:
 }
 ```
 
-Campos obligatorios:
-- `name`: Nombre del plugin
-- `version`: Versión del plugin
-- `description`: Descripción del plugin
-- `main`: Archivo principal del plugin
-- `enabled`: Si el plugin está habilitado o no
-
-Campos opcionales:
-- `author`: Autor del plugin
-- `kukuyVersion`: Versión de Kukuy requerida
-- `hooks`: Lista de hooks que el plugin usa
-- `filters`: Lista de filtros que el plugin usa
-- `dependencies`: Dependencias del plugin
-
-## Archivo Principal
-
-El archivo principal (por defecto `index.js`) debe exportar las funciones:
-
-- `init(balancer)`: Se llama cuando se carga el plugin
-- `deinit(balancer)`: Se llama cuando se descarga el plugin (opcional)
-
-## API de Extensión
-
-Dentro del plugin, puedes usar la API de extensión para registrar filtros y hooks:
+### Ejemplo de `index.js`:
 
 ```javascript
 async function init(balancer) {
+  console.log('Inicializando mi plugin...');
+  
   const extension = balancer.getPostStartupExtension();
   
-  // Registrar un filtro
+  // Registrar filtros y hooks
   extension.registerFilter('request_processing', async (data) => {
     // Lógica del filtro
     return { allowed: true };
   });
   
-  // Registrar un hook
   extension.registerHook('onRequestReceived', async ({ req, res }) => {
     // Lógica del hook
   });
 }
+
+async function deinit(balancer) {
+  console.log('Desactivando mi plugin...');
+}
+
+module.exports = { init, deinit };
 ```
 
 ## Hooks Disponibles
 
 - `onRequestReceived`: Se ejecuta cuando se recibe una solicitud
 - `onServerSelected`: Se ejecuta después de seleccionar el servidor
-- `onResponseSent`: Se ejecuta antes de enviar la respuesta
+- `onResponseReady`: Se ejecuta cuando la respuesta del servidor backend está lista
+- `onResponseSent`: Se ejecuta antes de enviar la respuesta al cliente
 - `onServerError`: Se ejecuta cuando ocurre un error
 
 ## Filtros Disponibles
 
-- `request_processing`: Se aplica al procesamiento de solicitudes
-
-## Variables de Entorno
-
-- `PLUGINS_DIR`: Directorio donde buscar plugins (por defecto: `./kukuy-plugins`)
+- `request_processing`: Se aplica al procesamiento de solicitudes