jerkjs 2.5.8 → 2.6.1

package/doc-2.5/QUEUE_SYSTEM_MANUAL.md

@@ -0,0 +1,320 @@
+# Manual de Uso del Sistema de Colas para el Framework JERK
+
+## Tabla de Contenidos
+1. [Introducción](#introducción)
+2. [Características del Sistema de Colas](#características-del-sistema-de-colas)
+3. [Instalación y Configuración](#instalación-y-configuración)
+4. [Conceptos Básicos](#conceptos-básicos)
+5. [Uso Básico](#uso-básico)
+6. [Uso Avanzado](#uso-avanzado)
+7. [Hooks Personalizados](#hooks-personalizados)
+8. [Gestión de Errores y Reintentos](#gestión-de-errores-y-reintentos)
+9. [Ejemplos de Uso](#ejemplos-de-uso)
+
+## Introducción
+
+El Sistema de Colas es una extensión del Framework JERK que permite la ejecución asíncrona de tareas en múltiples colas concurrentes. Este sistema es ideal para operaciones que consumen tiempo como procesamiento de imágenes, envío de correos electrónicos, procesamiento de pagos, y otras operaciones que no deben bloquear la respuesta inmediata a las solicitudes del usuario.
+
+## Características del Sistema de Colas
+
+- **Soporte para N colas**: Puedes crear tantas colas como necesites, cada una con su propia configuración.
+- **Concurrencia configurable**: Controla cuántas tareas se ejecutan simultáneamente por cola.
+- **Hooks personalizados**: Personaliza la lógica de procesamiento y fallback para cada cola.
+- **Sistema de reintentos**: Manejo automático de fallos con reintentos configurables.
+- **Gestión de prioridades**: Asigna prioridades a las tareas para determinar su orden de ejecución.
+- **Sistema de fallback**: Manejo de tareas que fallan definitivamente.
+- **Totalmente asíncrono**: No bloquea el hilo principal de ejecución.
+
+## Instalación y Configuración
+
+El Sistema de Colas ya está incluido en el Framework JERK a partir de la versión 2.6.0. Para usarlo:
+
+```javascript
+const { QueueIntegration } = require('jerkjs');
+```
+
+## Conceptos Básicos
+
+### Cola
+Una cola es una unidad lógica que agrupa tareas similares. Cada cola puede tener su propia configuración de concurrencia, reintentos y hooks personalizados.
+
+### Tarea
+Una tarea es una función que encapsula la lógica que se va a ejecutar en segundo plano. Las tareas pueden ser asíncronas y devolver Promises.
+
+### Hook
+Un hook es un punto de extensión que permite personalizar el comportamiento del sistema de colas, como la lógica de procesamiento de tareas o la lógica de fallback.
+
+## Uso Básico
+
+### 1. Crear una instancia del sistema de colas
+
+```javascript
+const { QueueIntegration } = require('jerkjs');
+
+// Crear una instancia de la integración de colas
+const queueIntegration = new QueueIntegration();
+```
+
+### 2. Crear una cola simple
+
+```javascript
+// Crear una cola con configuración por defecto
+queueIntegration.createQueue('procesamiento-general', {
+  concurrency: 2,      // Máximo 2 tareas ejecutándose simultáneamente
+  retryAttempts: 3,    // Reintentar hasta 3 veces si falla
+  retryDelay: 1000     // Esperar 1 segundo entre reintentos
+});
+```
+
+### 3. Agregar tareas a la cola
+
+```javascript
+// Función que representa una tarea
+function procesarDatos(datos, taskObj) {
+  return new Promise((resolve, reject) => {
+    // Simular procesamiento
+    setTimeout(() => {
+      console.log(`Procesando datos:`, datos);
+      resolve('Procesamiento completado');
+    }, 2000);
+  });
+}
+
+// Agregar una tarea a la cola
+const taskId = queueIntegration.addTask(
+  'procesamiento-general',  // Nombre de la cola
+  procesarDatos,            // Función de la tarea
+  { id: 1, nombre: 'dato1' }, // Datos para la tarea
+  0                         // Prioridad (0 es la más alta)
+);
+```
+
+### 4. Iniciar el sistema de colas
+
+```javascript
+// Iniciar la ejecución de tareas
+queueIntegration.start();
+```
+
+## Uso Avanzado
+
+### Crear colas con hooks personalizados
+
+```javascript
+const { HookSystem } = require('jerkjs');
+
+// Crear un sistema de hooks específico para esta cola
+const procesamientoImagenesHooks = new HookSystem();
+
+// Hook para personalizar la lógica de procesamiento
+procesamientoImagenesHooks.addAction('queue_execute_task', (task, queueName, taskObj) => {
+  console.log(`Preparando para procesar imagen: ${taskObj.id}`);
+  
+  // Envolver la tarea original con lógica adicional
+  const wrappedTask = async (datos, taskObj) => {
+    console.log(`Iniciando procesamiento de imagen: ${taskObj.id}`);
+    try {
+      const result = await task(datos, taskObj);
+      console.log(`Imagen procesada exitosamente: ${taskObj.id}`);
+      return result;
+    } catch (error) {
+      console.log(`Error procesando imagen: ${taskObj.id} - ${error.message}`);
+      throw error;
+    }
+  };
+  
+  return wrappedTask;
+});
+
+// Hook para manejar la lógica de fallback
+procesamientoImagenesHooks.addAction('queue_task_fallback', (queueName, task, error) => {
+  console.log(`Ejecutando fallback para imagen:`, error.message);
+  // Lógica personalizada para manejar tareas que fallan definitivamente
+});
+
+// Crear la cola con hooks personalizados
+queueIntegration.createQueue('imagenes', {
+  concurrency: 3,
+  retryAttempts: 2,
+  retryDelay: 1000
+}, procesamientoImagenesHooks);
+```
+
+### Prioridades de tareas
+
+Las tareas se pueden agregar con diferentes niveles de prioridad. Un valor más bajo indica una prioridad más alta:
+
+```javascript
+// Tarea de alta prioridad (prioridad 0)
+queueIntegration.addTask('imagenes', procesarImagen, { archivo: 'importante.jpg' }, 0);
+
+// Tarea de prioridad media (prioridad 5)
+queueIntegration.addTask('imagenes', procesarImagen, { archivo: 'normal.jpg' }, 5);
+
+// Tarea de baja prioridad (prioridad 10)
+queueIntegration.addTask('imagenes', procesarImagen, { archivo: 'opcional.jpg' }, 10);
+```
+
+## Hooks Personalizados
+
+El sistema de colas proporciona varios puntos de extensión a través de hooks:
+
+### Hooks Disponibles
+
+- `queue_execute_task`: Se ejecuta antes de procesar una tarea. Permite modificar la lógica de la tarea.
+- `queue_task_completed`: Se ejecuta cuando una tarea se completa exitosamente.
+- `queue_task_failed`: Se ejecuta cuando una tarea falla.
+- `queue_task_retry`: Se ejecuta cuando una tarea se reintenta.
+- `queue_task_fallback`: Se ejecuta cuando una tarea falla definitivamente después de todos los reintentos.
+- `queue_task_added`: Se ejecuta cuando se agrega una tarea a la cola.
+- `queue_system_started`: Se ejecuta cuando se inicia el sistema de colas.
+- `queue_system_stopped`: Se ejecuta cuando se detiene el sistema de colas.
+
+### Ejemplo de hook personalizado
+
+```javascript
+const misHooks = new HookSystem();
+
+// Hook para registrar todas las tareas completadas
+misHooks.addAction('queue_task_completed', (queueName, task) => {
+  console.log(`Tarea completada en cola ${queueName}:`, task.id);
+});
+
+// Hook para registrar errores
+misHooks.addAction('queue_task_failed', (queueName, task, error) => {
+  console.log(`Tarea fallida en cola ${queueName}:`, task.id, error.message);
+});
+```
+
+## Gestión de Errores y Reintentos
+
+El sistema de colas incluye un mecanismo robusto para manejar errores:
+
+### Configuración de reintentos
+
+```javascript
+queueIntegration.createQueue('procesamiento-confiable', {
+  retryAttempts: 5,    // Número máximo de reintentos
+  retryDelay: 2000     // Milisegundos de espera entre reintentos
+});
+```
+
+### Lógica de fallback
+
+Cuando una tarea falla después de todos los reintentos, se ejecuta la lógica de fallback:
+
+```javascript
+const hooks = new HookSystem();
+
+hooks.addAction('queue_task_fallback', (queueName, task, error) => {
+  // Aquí puedes implementar lógica personalizada para manejar tareas fallidas
+  console.log(`Tarea fallida definitivamente:`, task.id);
+  console.log(`Error:`, error.message);
+  
+  // Por ejemplo, guardar en una base de datos para procesamiento manual
+  // o enviar una alerta al equipo de soporte
+});
+```
+
+## Ejemplos de Uso
+
+### Ejemplo completo: Procesamiento de imágenes
+
+```javascript
+const { QueueIntegration, HookSystem } = require('jerkjs');
+
+// Crear instancia del sistema de colas
+const queueIntegration = new QueueIntegration();
+
+// Configurar cola de imágenes con hooks personalizados
+const imagenHooks = new HookSystem();
+
+imagenHooks.addAction('queue_execute_task', (task, queueName, taskObj) => {
+  console.log(`[IMAGEN] Preparando para procesar: ${taskObj.id}`);
+  return task;
+});
+
+imagenHooks.addAction('queue_task_fallback', (queueName, task, error) => {
+  console.log(`[IMAGEN] Error definitivo:`, error.message);
+});
+
+queueIntegration.createQueue('imagenes', {
+  concurrency: 3,
+  retryAttempts: 2,
+  retryDelay: 1000
+}, imagenHooks);
+
+// Función de tarea para procesamiento de imágenes
+function procesarImagen(datos, taskObj) {
+  return new Promise((resolve, reject) => {
+    console.log(`[IMAGEN] Procesando: ${datos.nombreArchivo}`);
+    
+    // Simular procesamiento
+    setTimeout(() => {
+      if (Math.random() < 0.2) { // 20% de fallos
+        reject(new Error(`Error procesando ${datos.nombreArchivo}`));
+      } else {
+        console.log(`[IMAGEN] Completado: ${datos.nombreArchivo}`);
+        resolve(`Imagen ${datos.nombreArchivo} procesada`);
+      }
+    }, 2000);
+  });
+}
+
+// Agregar tareas
+for (let i = 0; i < 5; i++) {
+  queueIntegration.addTask('imagenes', procesarImagen, {
+    id: i,
+    nombreArchivo: `imagen_${i}.jpg`
+  }, i);
+}
+
+// Iniciar el sistema
+queueIntegration.start();
+
+// Verificar estado periódicamente
+setInterval(() => {
+  console.log('Estado:', queueIntegration.getStatus());
+}, 5000);
+```
+
+### Ejemplo: Envío de correos electrónicos
+
+```javascript
+// Cola para envío de correos
+queueIntegration.createQueue('correos', {
+  concurrency: 2,      // Máximo 2 envíos simultáneos
+  retryAttempts: 3,    // Reintentar hasta 3 veces
+  retryDelay: 2000     // Esperar 2 segundos entre reintentos
+});
+
+function enviarCorreo(datos, taskObj) {
+  return new Promise((resolve, reject) => {
+    console.log(`Enviando correo a: ${datos.destinatario}`);
+    
+    // Simular envío de correo
+    setTimeout(() => {
+      if (Math.random() < 0.15) { // 15% de fallos
+        reject(new Error(`Fallo al enviar correo a ${datos.destinatario}`));
+      } else {
+        console.log(`Correo enviado a: ${datos.destinatario}`);
+        resolve(`Correo enviado a ${datos.destinatario}`);
+      }
+    }, 1500);
+  });
+}
+
+// Agregar tareas de correo
+const destinatarios = ['usuario1@example.com', 'usuario2@example.com', 'usuario3@example.com'];
+destinatarios.forEach((destinatario, index) => {
+  queueIntegration.addTask('correos', enviarCorreo, {
+    destinatario: destinatario,
+    asunto: 'Correo de prueba',
+    contenido: 'Contenido del correo'
+  }, index);
+});
+```
+
+## Conclusión
+
+El Sistema de Colas del Framework JERK proporciona una solución robusta y flexible para la ejecución asíncrona de tareas. Con soporte para múltiples colas, configuración de concurrencia, hooks personalizados y manejo de errores, es ideal para aplicaciones que requieren procesamiento en segundo plano sin bloquear la respuesta a las solicitudes del usuario.

package/doc-2.5/ROUTE_CACHE_MODULE_MANUAL.md

@@ -0,0 +1,205 @@
+# Manual del Módulo de Cache de Rutas para JERK Framework
+
+## Tabla de Contenidos
+1. [Introducción](#introducción)
+2. [Comandos Disponibles](#comandos-disponibles)
+3. [Uso Básico](#uso-básico)
+4. [Uso Avanzado](#uso-avanzado)
+5. [Ejemplos de Uso](#ejemplos-de-uso)
+
+## Introducción
+
+El módulo de Cache de Rutas es una extensión del sistema de administración CLI de JERK Framework que permite monitorear y gestionar el cache de rutas del sistema. Proporciona comandos para ver el estado del cache, visualizar su contenido, y limpiarlo cuando sea necesario.
+
+## Comandos Disponibles
+
+### Comandos Generales de Cache de Rutas
+- `route-cache` o `cache-stats`: Muestra estadísticas del cache de rutas
+- `cache-view`: Muestra el contenido completo del cache de rutas
+- `cache-dynamic`: Muestra solo el cache de rutas dinámicas (parametrizadas)
+- `cache-static`: Muestra solo el cache de rutas estáticas (exactas)
+- `cache-clear`: Limpia todo el cache de rutas
+
+## Uso Básico
+
+### Conectar al Sistema de Administración
+
+Para acceder al módulo de cache de rutas, primero debes conectarte al sistema de administración:
+
+```bash
+telnet localhost 9999
+```
+
+O alternativamente:
+
+```bash
+nc localhost 9999
+```
+
+### Ver estadísticas del cache de rutas
+
+Comando: `route-cache` o `cache-stats`
+
+Este comando muestra estadísticas generales del cache de rutas:
+
+```
+> route-cache
+
+=== Estadísticas del Cache de Rutas ===
+Rutas dinámicas (parametrizadas) en cache: 5
+Rutas estáticas exactas en cache: 10
+Tamaño total de índices: 15
+Índices válidos: Sí
+
+>
+```
+
+### Ver contenido del cache de rutas
+
+Comando: `cache-view`
+
+Este comando muestra el contenido completo del cache de rutas:
+
+```
+> cache-view
+
+=== Contenido del Cache de Rutas ===
+
+--- Rutas Dinámicas (Parametrizadas) en Cache ---
+1. /users/:id -> /^\/users\/([^\/]+?)$/
+2. /posts/:slug -> /^\/posts\/([^\/]+?)$/
+
+--- Rutas Estáticas Exactas en Cache ---
+1. GET /api/users -> anonymous
+2. POST /api/users -> anonymous
+
+>
+```
+
+## Uso Avanzado
+
+### Ver solo cache de rutas dinámicas
+
+Comando: `cache-dynamic`
+
+Muestra únicamente las rutas dinámicas (parametrizadas) en el cache:
+
+```
+> cache-dynamic
+
+=== Cache de Rutas Dinámicas (Parametrizadas) ===
+1. Ruta: /users/:id
+   Regex: /^\/users\/([^\/]+?)$/
+
+2. Ruta: /posts/:slug  
+   Regex: /^\/posts\/([^\/]+?)$/
+
+Total: 2 rutas dinámicas en cache.
+
+>
+```
+
+### Ver solo cache de rutas estáticas
+
+Comando: `cache-static`
+
+Muestra únicamente las rutas estáticas (exactas) en el cache:
+
+```
+> cache-static
+
+=== Cache de Rutas Estáticas (Exactas) ===
+1. GET /api/users
+   Handler: anonymous
+   Static: true
+
+2. POST /api/users
+   Handler: anonymous
+   Static: true
+
+Total: 2 rutas estáticas en cache.
+
+>
+```
+
+### Limpiar el cache de rutas
+
+Comando: `cache-clear`
+
+Elimina todas las entradas del cache de rutas:
+
+```
+> cache-clear
+
+=== Limpieza del Cache de Rutas ===
+Rutas dinámicas eliminadas: 5
+Rutas estáticas eliminadas: 10
+Cache de rutas limpiado exitosamente.
+
+>
+```
+
+## Ejemplos de Uso
+
+### Ejemplo 1: Diagnóstico de rendimiento
+
+Para diagnosticar problemas de rendimiento relacionados con el cache de rutas:
+
+```
+> route-cache
+Rutas dinámicas (parametrizadas) en cache: 50
+Rutas estáticas exactas en cache: 100
+Tamaño total de índices: 150
+Índices válidos: Sí
+
+> cache-dynamic
+[Detalles de las 50 rutas dinámicas en cache]
+>
+```
+
+### Ejemplo 2: Verificación de rutas parametrizadas
+
+Para verificar específicamente las rutas parametrizadas en el cache:
+
+```
+> cache-dynamic
+=== Cache de Rutas Dinámicas (Parametrizadas) ===
+1. Ruta: /users/:id
+   Regex: /^\/users\/([^\/]+?)$/
+   
+2. Ruta: /products/:category/:id
+   Regex: /^\/products\/([^\/]+?)\/([^\/]+?)$/
+   
+Total: 2 rutas dinámicas en cache.
+
+>
+```
+
+## Solución de Problemas
+
+### Problema: Comando no reconocido
+
+**Síntoma**: El sistema responde con "Comando desconocido para el módulo de cache de rutas"
+
+**Solución**: Verifica que estás usando uno de los comandos válidos: `route-cache`, `cache-stats`, `cache-view`, `cache-dynamic`, `cache-static`, `cache-clear`
+
+### Problema: No se encuentra el componente RouteMatcher
+
+**Síntoma**: El sistema responde con "No se encontró el componente RouteMatcher"
+
+**Solución**: Asegúrate de que el servidor esté completamente iniciado y que el componente RouteMatcher haya sido correctamente instanciado.
+
+## Compatibilidad
+
+- **Versión mínima del framework**: JERK 2.5.8
+- **Puerto de administración**: Por defecto 9999 (configurable)
+- **Acceso**: Solo desde localhost por razones de seguridad
+- **Protocolo**: Conexión TCP con interfaz de línea de comandos
+
+## Autor
+
+JERK Framework Team
+
+## Versión
+
+v2.6.0