jerkjs 2.5.6 → 2.6.1

package/doc-2.5/QUEUE_CLI_MODULE_MANUAL.md

@@ -0,0 +1,289 @@
+# Manual del Módulo CLI de Gestión de Colas 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)
+6. [Solución de Problemas](#solución-de-problemas)
+
+## Introducción
+
+El módulo de Gestión de Colas es una extensión del sistema de administración CLI de JERK Framework que permite monitorear y gestionar las colas de tareas del sistema. Proporciona comandos para ver el estado de las colas, pausarlas, reanudarlas, limpiarlas y gestionar tareas fallidas.
+
+## Comandos Disponibles
+
+### Comandos Generales de Colas
+- `queues`: Muestra el estado de todas las colas del sistema
+- `queue-info`: Muestra información detallada de una cola específica
+- `queue-pause`: Pausa una cola específica
+- `queue-resume`: Reanuda una cola específica
+- `queue-clear`: Limpia las tareas pendientes de una cola específica
+- `queue-retry-failed`: Reintenta las tareas fallidas de una cola específica
+
+## Uso Básico
+
+### Conectar al Sistema de Administración
+
+Para acceder al módulo de gestión de colas, primero debes conectarte al sistema de administración:
+
+```bash
+telnet localhost 9999
+```
+
+O alternativamente:
+
+```bash
+nc localhost 9999
+```
+
+### Ver el estado de todas las colas
+
+Comando: `queues`
+
+Este comando muestra el estado de todas las colas registradas en el sistema:
+
+```
+> queues
+
+=== Colas del Sistema ===
+imagenes:
+  Concurrencia: 3/3
+  Tareas pendientes: 0
+  Tareas en proceso: 0
+  Tareas fallidas: 0
+  Estado: INACTIVO
+  Reintentos: 2
+  Retraso de reintento: 1000ms
+
+correos:
+  Concurrencia: 2/2
+  Tareas pendientes: 1
+  Tareas en proceso: 1
+  Tareas fallidas: 0
+  Estado: PROCESANDO
+  Reintentos: 3
+  Retraso de reintento: 2000ms
+
+pagos:
+  Concurrencia: 1/1
+  Tareas pendientes: 0
+  Tareas en proceso: 0
+  Tareas fallidas: 2
+  Estado: INACTIVO
+  Reintentos: 5
+  Retraso de reintento: 3000ms
+
+backups:
+  Concurrencia: 1/1
+  Tareas pendientes: 0
+  Tareas en proceso: 0
+  Tareas fallidas: 0
+  Estado: INACTIVO
+  Reintentos: 3
+  Retraso de reintento: 5000ms
+
+> 
+```
+
+### Ver información detallada de una cola específica
+
+Comando: `queue-info`
+
+Este comando solicita el nombre de una cola y muestra información detallada:
+
+```
+> queue-info
+
+Introduce el nombre de la cola:
+> pagos
+
+=== Información de la Cola: pagos ===
+Concurrencia: 1/1
+Tareas pendientes: 0
+Tareas en proceso: 0
+Tareas fallidas: 2
+Estado: INACTIVO
+Reintentos: 5
+Retraso de reintento: 3000ms
+Total de workers: 0
+
+> 
+```
+
+## Uso Avanzado
+
+### Pausar una cola
+
+Comando: `queue-pause`
+
+Pausa temporalmente el procesamiento de tareas en una cola específica:
+
+```
+> queue-pause
+
+Introduce el nombre de la cola:
+> correos
+
+✅ Cola 'correos' pausada exitosamente.
+
+> 
+```
+
+Cuando una cola está pausada, no procesará nuevas tareas, pero las tareas que ya estaban en proceso se completarán normalmente.
+
+### Reanudar una cola
+
+Comando: `queue-resume`
+
+Reanuda el procesamiento de tareas en una cola específica:
+
+```
+> queue-resume
+
+Introduce el nombre de la cola:
+> correos
+
+✅ Cola 'correos' reanudada exitosamente.
+
+> 
+```
+
+### Limpiar una cola
+
+Comando: `queue-clear`
+
+Elimina todas las tareas pendientes de una cola específica (no afecta a las tareas que ya están en proceso):
+
+```
+> queue-clear
+
+Introduce el nombre de la cola:
+> imagenes
+
+✅ Cola 'imagenes' limpiada exitosamente (tareas pendientes eliminadas).
+
+> 
+```
+
+### Reintentar tareas fallidas
+
+Comando: `queue-retry-failed`
+
+Reintenta todas las tareas que han fallado definitivamente en una cola específica:
+
+```
+> queue-retry-failed
+
+Introduce el nombre de la cola:
+> pagos
+
+✅ Reintento de tareas fallidas iniciado para la cola 'pagos'.
+
+> 
+```
+
+## Ejemplos de Uso
+
+### Ejemplo 1: Monitoreo de colas
+
+Para monitorear constantemente el estado de las colas, puedes usar el comando `queues` repetidamente:
+
+```
+> queues
+imagenes: Pendientes=0, En proceso=2, Fallidas=0, Pausada=false
+correos: Pendientes=5, En proceso=1, Fallidas=0, Pausada=false
+pagos: Pendientes=0, En proceso=0, Fallidas=1, Pausada=false
+backups: Pendientes=0, En proceso=0, Fallidas=0, Pausada=false
+> 
+```
+
+### Ejemplo 2: Gestión de alta carga
+
+Si una cola está recibiendo demasiadas tareas y necesitas detener temporalmente el procesamiento:
+
+```
+> queue-pause
+Introduce el nombre de la cola:
+> correos
+✅ Cola 'correos' pausada exitosamente.
+
+> queues
+correos: Pendientes=50, En proceso=0, Fallidas=0, Pausada=true
+> 
+```
+
+Luego, cuando la carga disminuya, puedes reanudar:
+
+```
+> queue-resume
+Introduce el nombre de la cola:
+> correos
+✅ Cola 'correos' reanudada exitosamente.
+```
+
+### Ejemplo 3: Manejo de tareas fallidas
+
+Si una cola tiene tareas fallidas que deseas reintentar:
+
+```
+> queues
+pagos: Pendientes=0, En proceso=0, Fallidas=3, Pausada=false
+
+> queue-retry-failed
+Introduce el nombre de la cola:
+> pagos
+✅ Reintento de tareas fallidas iniciado para la cola 'pagos'.
+
+> queues
+pagos: Pendientes=3, En proceso=0, Fallidas=0, Pausada=false
+```
+
+## Solución de Problemas
+
+### Problema: Comando no reconocido
+
+**Síntoma**: El sistema responde con "Comando desconocido para el módulo de gestión de colas"
+
+**Solución**: Verifica que estás usando uno de los comandos válidos: `queues`, `queue-info`, `queue-pause`, `queue-resume`, `queue-clear`, `queue-retry-failed`
+
+### Problema: Cola no encontrada
+
+**Síntoma**: El sistema responde con "❌ Cola 'nombre' no encontrada."
+
+**Solución**: Verifica que el nombre de la cola es correcto. Puedes usar el comando `queues` para ver la lista de colas disponibles.
+
+### Problema: Cola no responde
+
+**Síntoma**: Las tareas no se procesan aunque la cola esté activa
+
+**Solución**: 
+1. Verifica el estado con `queues`
+2. Comprueba si la cola está pausada
+3. Verifica que el sistema de colas esté iniciado en la aplicación
+4. Revisa los logs de la aplicación para posibles errores
+
+### Problema: Tareas acumulándose
+
+**Síntoma**: La cola tiene muchas tareas pendientes que no se procesan
+
+**Soluciones posibles**:
+1. Aumenta la concurrencia de la cola en la configuración de la aplicación
+2. Pausa temporalmente la cola si hay sobrecarga: `queue-pause`
+3. Verifica que las tareas no estén fallando continuamente
+
+## Compatibilidad
+
+- **Versión mínima del framework**: JERK 2.6.0
+- **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

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.