kukuy 1.5.0 → 1.6.0

package/README.md

@@ -1,65 +1,26 @@
-# KUKUY
+# KUKUY - Balanceador de Carga
 
-![Kukuy Logo](kukuu1.webp)
+KUKUY es un  sistema de balanceo de carga backend desarrollado en Node.js que permite distribuir solicitudes entre múltiples servidores backend utilizando diferentes algoritmos de balanceo. El sistema incluye características avanzadas como soporte para hooks, filtros, rutas personalizadas y un panel de control web.
 
-Un balanceador de carga desarrollado en Node.js que distribuye solicitudes entre múltiples servidores backend usando el algoritmo RoundRobin.
+## Características Principales
 
-## Información del Proyecto
-
-- **Página Oficial**: [https://bsanchez.unaux.com/](https://bsanchez.unaux.com/)
-- **Repositorio Oficial**: [https://gitlab.com/bytedogssyndicate1/kukuy](https://gitlab.com/bytedogssyndicate1/kukuy)
-
-## Instalación
-
-Para instalar Kukuy globalmente en tu sistema:
-
-```bash
-npm install -g kukuy
-```
-
-O para instalarlo localmente en tu proyecto:
-
-```bash
-npm install kukuy
-```
-
-## 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
-```
+- **Algoritmos de Balanceo**: Soporta algoritmos como Round Robin e IP Hash
+- **Soporte para HTTPS/SSL**: Capacidad de manejar conexiones seguras
+- **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
+- **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
 
 ## 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
 
-## Archivos de Configuración
+El sistema utiliza varios archivos de configuración:
 
-### servers.json
-Define los servidores backend:
+#### `servers.json`
+Define los servidores backend a los que se distribuirán las solicitudes:
 
 ```json
 {
@@ -67,21 +28,24 @@ Define los servidores backend:
     {
       "url": "http://localhost:3001",
       "weight": 1,
-      "tags": ["api"],
-      "active": true
+      "tags": ["api"]
     },
     {
       "url": "http://localhost:3002",
       "weight": 1,
-      "tags": ["api"],
-      "active": true
+      "tags": ["api"]
+    },
+    {
+      "url": "http://localhost:3003",
+      "weight": 1,
+      "tags": ["web"]
     }
   ]
 }
 ```
 
-### routes.json
-Define las reglas de enrutamiento para dirigir solicitudes específicas a grupos particulares de servidores backend basados en patrones de URL:
+#### `routes.json`
+Define las rutas y a qué grupo de servidores deben dirigirse:
 
 ```json
 {
@@ -100,173 +64,124 @@ Define las reglas de enrutamiento para dirigir solicitudes específicas a grupos
 }
 ```
 
-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
+### Variables de Entorno
 
-## Uso
+- `LOAD_BALANCING_ALGORITHM`: Algoritmo de balanceo ('roundrobin' o 'iphash')
+- `BALANCER_HTTP_PORT`: Puerto HTTP del balanceador (por defecto 8080)
+- `BALANCER_HTTPS_PORT`: Puerto HTTPS del balanceador
+- `CONFIG_FILE_PATH`: Ruta al archivo de configuración de servidores
+- `ROUTES_FILE_PATH`: Ruta al archivo de configuración de rutas
+- `SSL_CERT_PATH`: Ruta al certificado SSL
+- `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
+- `LOG_LEVEL`: Nivel de logging (por defecto 'info')
 
-### Iniciar en modo producción:
-```bash
-npm start
-```
+## Algoritmos de Balanceo
 
-### Iniciar en modo desarrollo:
-```bash
-npm run dev
-```
+### Round Robin
+Distribuye las solicitudes de forma equitativa entre todos los servidores disponibles, ciclando secuencialmente.
 
-### 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
+### IP Hash
+Utiliza la dirección IP del cliente para determinar a qué servidor se enviará la solicitud, asegurando que las solicitudes del mismo cliente siempre vayan al mismo servidor.
 
-# Usar algoritmo IPHash
-LOAD_BALANCING_ALGORITHM=iphash npm start
-```
+## Scripts de Inicio
 
-### Scripts de inicio predefinidos:
+El proyecto incluye scripts preconfigurados para iniciar el balanceador:
 
-#### Iniciar con algoritmo RoundRobin:
+### `start-roundrobin.sh`
+Inicia el balanceador con el algoritmo Round Robin:
 ```bash
 ./start-roundrobin.sh
 ```
 
-#### Iniciar con algoritmo IPHash:
+### `start-iphash.sh`
+Inicia el balanceador con el algoritmo IP Hash:
 ```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
+### `start-ssl.sh` y `start-ssl-config.sh`
+Scripts para iniciar el balanceador con soporte SSL/TLS.
 
-El balanceador incluye una API REST para monitoreo en tiempo real:
+## Panel de Control Web
 
-#### 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]
-    }
-  }
-}
-```
+KUKUY incluye un panel de control web accesible en `http://localhost:8082` (por defecto) que muestra:
 
-## Hooks Disponibles
+- Estado general del sistema
+- Métricas de rendimiento (RPS, tiempo de respuesta promedio)
+- Estado de los servidores backend
+- Información sobre el algoritmo de balanceo actual
+- Gráficos de uso reciente
 
-- `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
+## Sistema de Plugins
 
-## Filtros Disponibles
+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.
 
-- `AuthenticationFilter`: Verificación de autenticación
-- `RateLimitFilter`: Control de límite de peticiones
-- `LoggingFilter`: Registro de solicitudes
-- `CachingFilter`: Caché de respuestas
+### Estructura de un Plugin
 
-## Componentes Implementados
+Un plugin típico incluye:
 
-### 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)
+- `manifest.json`: Metadatos del plugin
+- `index.js`: Código principal del plugin con funciones `init()` y `deinit()`
 
-### 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)
+Ejemplo de `manifest.json`:
+```json
+{
+  "name": "Nombre del Plugin",
+  "version": "1.0.0",
+  "description": "Descripción del plugin",
+  "author": "Autor",
+  "main": "index.js",
+  "kukuyVersion": "^1.6.0",
+  "hooks": ["onRequestReceived", "onResponseSent"],
+  "filters": ["request_processing"],
+  "enabled": true
+}
+```
 
-### 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
+## Hooks y Filtros
 
-### 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
+### Hooks
+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
+- `onServerError`: Cuando ocurre un error con un servidor backend
 
-## Pruebas
+### Filtros
+Permiten interceptar y potencialmente modificar o bloquear solicitudes antes de que sean procesadas:
+- Se pueden aplicar filtros de solicitud (`request`)
+- Permiten implementar lógica de seguridad, autenticación, etc.
 
-### 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
-```
+## Seguridad
 
-## Issues Conocidos
+- El sistema incluye mecanismos para marcar servidores como fallidos temporalmente
+- Implementa reintento inteligente hacia servidores alternativos
+- Permite configurar límites de intentos fallidos antes de excluir un servidor
 
-### 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.
+## Monitoreo y Métricas
 
-Para más detalles, véase el archivo [ISSUES.md](./ISSUES.md).
+KUKUY proporciona métricas detalladas sobre:
+- Solicitudes totales procesadas
+- RPS (Solicitudes por segundo) acumulado e instantáneo
+- Tiempo de respuesta promedio
+- Tasa de éxito
+- Estado de salud de los servidores
+- Uso de recursos del sistema (CPU, memoria)
 
 ## Licencia
 
-Este proyecto está licenciado bajo la Licencia Pública General GNU (GPL) versión 3 o posterior.
+Este proyecto está licenciado bajo la Licencia GPL-3.0 o posterior.
 
-Copyright (C) 2026 Desarrollador
+## Autor
 
-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.
+Benjamín Sánchez Cárdenas
+Email de contacto: bytedogssyndicate@gmail.com
+Página web oficial: https://bsanchez.unaux.com/
+Repositorio oficial: https://gitlab.com/bytedogssyndicate1/kukuy
 
-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.
+## Contribuciones
 
-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/>.
+Las contribuciones son bienvenidas. Por favor, abre un issue o pull request para discutir cambios propuestos.

package/balancer.log

@@ -0,0 +1,2 @@
+{"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}}

package/certs/auto/certificate.crt

@@ -0,0 +1,22 @@
+-----BEGIN CERTIFICATE-----
+MIIDtzCCAp+gAwIBAgIUFTU+RfyHp2GmFigOSZ9AiN8SGLcwDQYJKoZIhvcNAQEL
+BQAwazELMAkGA1UEBhMCRVMxDzANBgNVBAgMBk1hZHJpZDEPMA0GA1UEBwwGTWFk
+cmlkMQ4wDAYDVQQKDAVLdWt1eTEWMBQGA1UECwwNSVQgRGVwYXJ0bWVudDESMBAG
+A1UEAwwJbG9jYWxob3N0MB4XDTI2MDEyNjAxNTU1NFoXDTI3MDEyNjAxNTU1NFow
+azELMAkGA1UEBhMCRVMxDzANBgNVBAgMBk1hZHJpZDEPMA0GA1UEBwwGTWFkcmlk
+MQ4wDAYDVQQKDAVLdWt1eTEWMBQGA1UECwwNSVQgRGVwYXJ0bWVudDESMBAGA1UE
+AwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlN3F
+rAiKzKOIybQsmGIF+sBmfgkqsC/jq3EBsOnIDXG2Kz0AVLNCD1nxTmYB06x7TN7V
+xCSXiaGJEAW2v2+CLOpiFtO9S9hnxsoENN3DI/ZNYVBD5QbPFdkyTUw31iq8Vdhp
+tkrxwnY7q7S/Ss1BEKxL/y0f4bSD9bXAYbTJRFlx5bv8KE0+Opr3EywGmyd9Fwwq
+Zf4+z19kc4/ILmguzrMTZ9MblzKN5VAxoQ+h5SzKY/pgIPTX9Y25ciKwlN8nPrYs
+32CfFVqyH1sWY+hz8nhPIqJ++R12cofTyjBkfUoo7hE87wsIITmttxA9gJfd9k2j
+jy6ebm40SGaHXjU7twIDAQABo1MwUTAdBgNVHQ4EFgQUYK1YQGMWkT9TpbPspqtu
+tWzX3EMwHwYDVR0jBBgwFoAUYK1YQGMWkT9TpbPspqtutWzX3EMwDwYDVR0TAQH/
+BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEADQWlR94ZUUSv+nYzpvhyonnxDoy+
+YU4MATcisHc6HnbLUdwX95dSzIFLg/aurqcadWTL6q2RQusUpfpNdVPJXvXUXz/W
+ebk1Q97qcz8jFp9hbZxb93mrmJE0JccMU36WZPVM8J9K8p11JABn+sJRQFIAOauU
+C7ETVs84+b3JNLGH9Y3cJpB6Jm7DntFXZmp6Ehe8On4SwqIRfN11CKQs7SqcHXts
+X6tgXisc7HskSbXXG5oSHKz+uwngH2V85RH/pKgly80IRT3FbPzFRBdSCDk6B4PM
+Bqow/h9NX65Vd5aRFpsmje4eqrO2g0YQsPmpVAndIstn+HlW5YyLAb5dmA==
+-----END CERTIFICATE-----

package/certs/auto/private.key

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCU3cWsCIrMo4jJ
+tCyYYgX6wGZ+CSqwL+OrcQGw6cgNcbYrPQBUs0IPWfFOZgHTrHtM3tXEJJeJoYkQ
+Bba/b4Is6mIW071L2GfGygQ03cMj9k1hUEPlBs8V2TJNTDfWKrxV2Gm2SvHCdjur
+tL9KzUEQrEv/LR/htIP1tcBhtMlEWXHlu/woTT46mvcTLAabJ30XDCpl/j7PX2Rz
+j8guaC7OsxNn0xuXMo3lUDGhD6HlLMpj+mAg9Nf1jblyIrCU3yc+tizfYJ8VWrIf
+WxZj6HPyeE8ion75HXZyh9PKMGR9SijuETzvCwghOa23ED2Al932TaOPLp5ubjRI
+ZodeNTu3AgMBAAECggEAIXLhNwHmWgvGsPeca5Le4BQ6E0ixAEyKXduy8xLcYfTy
+Zy26NM3gYn2lpCV0dKDVRZTuODe2mvSiTOjTwpjmCXySlKl356JU0wxSPKS1c4+k
+nGCCGORaRID8dfTRuPv6PFm3iv+06apSRwcCUmbjH0FvhAMaHkdGvT9c3jdWX9ZX
+YpHtnQQzWQSdNByT6ELqUCD2lw9AtzRSdvMDEZ/H7WfepcJ8jNNAzLkNQIuezDR1
+ciFA5dDhT8vOkEBV1LiQz0uUscsyefhDG1rUmFJxUng9IW2qNFEKxBfiWdZIGEK3
+PInBm4QpOLHh1q6+XK2yeRSnw8uMfgPlDQgr5cGDYQKBgQDKLD01Letd0URs0INL
+LRLox/k8GrCKEDXl+y7EvbWnLriDck4I+fkuQKenxQdVCBCOKGRgm92j3Y8vB+9I
+QU8lIzohgAUt5GAm+7ZNdwbTX3hYmUmIFXdZEvIBZ61Xw+ghwSWh44Af5S8w4xoi
+C5ewa4iBvSApOHzs6Q6/Tf8WYQKBgQC8gEATZNmiXH3ITYdGVmEY5uzqRyJIXt3y
+BbfFooZc31daUx4HDnjgzdY8I5cr3JfNy1HvpXcLMWH79nRbEcwvaiKkqkvaGxHW
+e6NTTkU46P4lAwtzsfM7eQrtRnfJGLUF7ZQzc/W05BkdyLq2Fmrox8Mt01rZs9Yo
+R+4tv5LZFwKBgQCJ9uSSDNMIg81RAH4IaCr2Rbj0ZjZBEUzms6G3yspS21Q5B2Dv
+ST7dbGu81nzpbwZ1LGVLdDItJ/4VFzIYOdE7w61gvQ9LwQRItg8zD93NkuH6fCis
+wBFg7MfPY6PsN5mKp1b6AdkmauzoTKJBx21tjARsnNZ8qrq9pVFWBXDlIQKBgQC1
+bOa/A9DoEQdLEzuAukCn/BLIhgB8ETqi51fyEzQpDRkBKYB8IDS9gb+RkFu+bol5
+HBjXg7UpA7WgEZv5zw5sEEYZoIJzAJzRh5wx4OKFHNMHAoAyMXK+qgiXSLyfw3Tv
+qLN8Nj6lhOibnwf9m2P4edPkNkl5wTn8+QZH59vJrwKBgDi7kLHz+fLxM6BYQ92F
+mRgxHoY1Cj0jpPEGx+9A7e8f2zQUSb9nUU0et0NHmiGmgkUTqVwy7lWGFSXjvoaz
+Vm1UrDskAbngwmSHpPDeBZTOHHR9PRyPWdJqUzJjk7boQK9gK65BeYLkY9klJFIN
+bWZG2VQiV6rOcc/8WWgZtlrG
+-----END PRIVATE KEY-----

package/kukuy-plugins/README.md

@@ -0,0 +1,91 @@
+# Sistema de Plugins para Kukuy
+
+## Introducción
+
+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.
+
+## Estructura de un Plugin
+
+Cada plugin debe tener la siguiente estructura:
+
+```
+kukuy-plugins/
+└── nombre-del-plugin/
+    ├── manifest.json
+    └── index.js
+```
+
+## Manifest
+
+El archivo `manifest.json` debe contener:
+
+```json
+{
+  "name": "Nombre del Plugin",
+  "version": "1.0.0",
+  "description": "Descripción del plugin",
+  "author": "Autor del plugin",
+  "main": "index.js",
+  "kukuyVersion": "^1.6.0",
+  "hooks": ["onRequestReceived", "onResponseSent"],
+  "filters": ["request_processing"],
+  "enabled": true
+}
+```
+
+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:
+
+```javascript
+async function init(balancer) {
+  const extension = balancer.getPostStartupExtension();
+  
+  // Registrar un filtro
+  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
+  });
+}
+```
+
+## 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
+- `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`)

package/kukuy-plugins/ejemplo-plugin/index.js

@@ -0,0 +1,39 @@
+/**
+ * Plugin de ejemplo para Kukuy
+ * Demuestra cómo crear un plugin que se carga automáticamente
+ */
+
+async function init(balancer) {
+  console.log('Inicializando plugin de ejemplo...');
+  
+  const extension = balancer.getPostStartupExtension();
+  
+  // Registrar un filtro de ejemplo
+  extension.registerFilter('request_processing', async (data) => {
+    const { req, res } = data;
+    console.log(`Plugin: Procesando solicitud ${req.method} ${req.url}`);
+    
+    // Agregar un header personalizado
+    req.headers['x-plugin-example'] = 'activated';
+    
+    return { allowed: true };
+  }, 5);
+  
+  // Registrar un hook para cuando se recibe una solicitud
+  extension.registerHook('onRequestReceived', async ({ req, res }) => {
+    console.log(`Plugin: Solicitud recibida - ${req.method} ${req.url}`);
+  }, 5);
+  
+  // Registrar un hook para cuando se envía la respuesta
+  extension.registerHook('onResponseSent', async ({ req, res, serverRes, responseTime }) => {
+    console.log(`Plugin: Respuesta enviada para ${req.url} en ${responseTime}ms`);
+  }, 5);
+  
+  console.log('Plugin de ejemplo inicializado correctamente');
+}
+
+async function deinit(balancer) {
+  console.log('Desactivando plugin de ejemplo...');
+}
+
+module.exports = { init, deinit };

package/kukuy-plugins/ejemplo-plugin/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "Plugin de Ejemplo",
+  "version": "1.0.0",
+  "description": "Plugin de ejemplo para demostrar la arquitectura de plugins",
+  "author": "Desarrollador",
+  "main": "index.js",
+  "kukuyVersion": "^1.6.0",
+  "hooks": ["onRequestReceived", "onResponseSent"],
+  "filters": ["request_processing"],
+  "enabled": true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kukuy",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Balanceador de carga Backend",
   "main": "kukuy.js",
   "scripts": {
@@ -9,6 +9,7 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [
+    "backend",
     "load-balancer",
     "round-robin",
     "ip-hash",

package/servers_real.json

@@ -14,6 +14,11 @@
       "url": "http://localhost:5445",
       "weight": 1,
       "tags": ["backend"]
+    },
+    {
+      "url": "http://localhost:6666",
+      "weight": 1,
+      "tags": ["backend"]
     }
   ]
 }