KUKUY - Balanceador de Carga

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.

Características Principales

• 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
• 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

Archivos de Configuración

El sistema utiliza varios archivos de configuración:

servers.json

Define los servidores backend a los que se distribuirán las solicitudes:

{
  "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"]
    }
  ]
}

routes.json

Define las rutas y a qué grupo de servidores deben dirigirse:

{
  "routes": [
    {
      "path": "/api/*",
      "methods": ["GET", "POST", "PUT", "DELETE"],
      "target": "api"
    },
    {
      "path": "/*",
      "methods": ["*"],
      "target": "web"
    }
  ]
}

Variables de Entorno

• 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 (en milisegundos, por defecto 30000)
• LOG_LEVEL: Nivel de logging (por defecto 'info')

Algoritmos de Balanceo

Round Robin

Distribuye las solicitudes de forma equitativa entre todos los servidores disponibles, ciclando secuencialmente.

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.

Scripts de Inicio

El proyecto incluye scripts preconfigurados para iniciar el balanceador:

start-roundrobin.sh

Inicia el balanceador con el algoritmo Round Robin:

./start-roundrobin.sh

start-iphash.sh

Inicia el balanceador con el algoritmo IP Hash:

./start-iphash.sh

start-ssl.sh y start-ssl-config.sh

Scripts para iniciar el balanceador con soporte SSL/TLS.

Panel de Control Web

KUKUY incluye un panel de control web accesible en http://localhost:8082 (por defecto) que muestra:

• 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

Sistema de Plugins

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:

• manifest.json: Metadatos del plugin
• index.js: Código principal del plugin con funciones init() y deinit()

Ejemplo de manifest.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
}

Hooks y Filtros

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
• 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_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

• 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

Monitoreo y Métricas

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 GPL-3.0 o posterior.

Autor

Benjamín Sánchez Cárdenas Email de contacto: [email protected] Página web oficial: https://bsanchez.unaux.com/ Repositorio oficial: https://gitlab.com/bytedogssyndicate1/kukuy

Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request para discutir cambios propuestos.