jerkjs 2.5.8 → 2.6.1

package/lib/queue/GlobalQueueStorage.js

@@ -0,0 +1,38 @@
+/**
+ * Almacenamiento Global de Colas para el Framework JERK
+ * Implementación del componente queue/GlobalQueueStorage.js
+ * Sistema de almacenamiento compartido globalmente para las colas
+ */
+
+// Crear espacio de almacenamiento global para las colas si no existe
+if (!global.jerkQueues) {
+  global.jerkQueues = new Map();
+}
+
+if (!global.jerkQueueSystems) {
+  global.jerkQueueSystems = new Map();
+}
+
+if (!global.jerkQueueSystem) {
+  // Importar dinámicamente para evitar dependencias circulares
+  const QueueSystem = require('./QueueSystem');
+  const HookSystem = require('../core/hooks');
+  
+  // Obtener hooks globales del framework si están disponibles
+  let globalHooks = null;
+  try {
+    const framework = require('../../index.js');
+    globalHooks = framework.hooks;
+  } catch (error) {
+    // Si no están disponibles, crear instancia local
+    globalHooks = new HookSystem();
+  }
+  
+  global.jerkQueueSystem = new QueueSystem({ hooks: globalHooks });
+}
+
+module.exports = {
+  queues: global.jerkQueues,
+  queueSystems: global.jerkQueueSystems,
+  queueSystem: global.jerkQueueSystem
+};

package/lib/queue/QueueSystem.js

@@ -0,0 +1,451 @@
+/**
+ * Sistema de Colas para el framework JERK
+ * Implementación del componente queue/QueueSystem.js
+ * Sistema de colas con soporte para N colas, hooks personalizados y manejo de fallback
+ */
+
+class QueueSystem {
+  /**
+   * Constructor del sistema de colas
+   * @param {Object} options - Opciones de configuración
+   */
+  constructor(options = {}) {
+    // Almacenar las colas
+    this.queues = new Map();
+    
+    // Almacenar tareas pendientes por cola
+    this.pendingTasks = new Map();
+    
+    // Almacenar tareas en proceso por cola
+    this.runningTasks = new Map();
+    
+    // Almacenar tareas fallidas por cola
+    this.failedTasks = new Map();
+    
+    // Almacenar hooks del sistema
+    this.globalHooks = options.hooks || null;
+    
+    // Configuración por defecto
+    this.defaultConcurrency = options.concurrency || 1;
+    this.defaultRetryAttempts = options.retryAttempts || 3;
+    this.defaultRetryDelay = options.retryDelay || 1000; // milisegundos
+    
+    // Estado del sistema
+    this.isRunning = false;
+  }
+
+  /**
+   * Obtiene o crea una cola específica
+   * @param {string} queueName - Nombre de la cola
+   * @param {Object} options - Opciones específicas para la cola
+   * @returns {Object} - Objeto de la cola
+   */
+  getOrCreateQueue(queueName, options = {}) {
+    if (!this.queues.has(queueName)) {
+      const queue = {
+        name: queueName,
+        concurrency: options.concurrency || this.defaultConcurrency,
+        retryAttempts: options.retryAttempts || this.defaultRetryAttempts,
+        retryDelay: options.retryDelay || this.defaultRetryDelay,
+        tasks: [],
+        processing: false,
+        workers: 0,
+        maxWorkers: options.concurrency || this.defaultConcurrency,
+        hooks: options.hooks || null // Hooks específicos para esta cola
+      };
+      
+      this.queues.set(queueName, queue);
+      
+      // Inicializar estructuras de datos para esta cola
+      this.pendingTasks.set(queueName, []);
+      this.runningTasks.set(queueName, new Set());
+      this.failedTasks.set(queueName, []);
+    }
+    
+    return this.queues.get(queueName);
+  }
+
+  /**
+   * Agrega una tarea a una cola
+   * @param {string} queueName - Nombre de la cola
+   * @param {Function} task - Función que representa la tarea
+   * @param {Object} data - Datos para la tarea
+   * @param {number} priority - Prioridad de la tarea (menor número = mayor prioridad)
+   * @returns {string} - ID único de la tarea
+   */
+  addTask(queueName, task, data = {}, priority = 0) {
+    const taskId = this.generateTaskId();
+    
+    const queue = this.getOrCreateQueue(queueName);
+    
+    const taskObj = {
+      id: taskId,
+      task: task,
+      data: data,
+      priority: priority,
+      createdAt: Date.now(),
+      attempts: 0,
+      maxAttempts: queue.retryAttempts
+    };
+    
+    // Agregar a la cola de tareas pendientes
+    const pendingQueue = this.pendingTasks.get(queueName);
+    pendingQueue.push(taskObj);
+    
+    // Mantener la cola ordenada por prioridad
+    pendingQueue.sort((a, b) => a.priority - b.priority);
+    
+    // Disparar hook cuando se agrega una tarea (primero global, luego específico de cola)
+    if (this.globalHooks) {
+      this.globalHooks.doAction('queue_task_added', queueName, taskObj);
+    }
+    
+    // Disparar hook específico de la cola
+    if (queue.hooks) {
+      queue.hooks.doAction('queue_task_added', queueName, taskObj);
+    }
+    
+    // Si el sistema está corriendo, intentar procesar la tarea
+    if (this.isRunning) {
+      setImmediate(() => {
+        this.processQueue(queueName);
+      });
+    }
+    
+    return taskId;
+  }
+
+  /**
+   * Genera un ID único para una tarea
+   * @returns {string} - ID único de la tarea
+   */
+  generateTaskId() {
+    return `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Inicia la ejecución de tareas en todas las colas
+   */
+  start() {
+    if (this.isRunning) {
+      return;
+    }
+    
+    this.isRunning = true;
+    
+    // Disparar hook cuando se inicia el sistema de colas (global)
+    if (this.globalHooks) {
+      this.globalHooks.doAction('queue_system_started');
+    }
+    
+    // Iniciar procesamiento para cada cola
+    for (const [queueName, queue] of this.queues.entries()) {
+      // Disparar hook cuando se inicia el sistema de colas (específico de cola)
+      if (queue.hooks) {
+        queue.hooks.doAction('queue_system_started', queueName);
+      }
+      this.processQueue(queueName);
+    }
+  }
+
+  /**
+   * Detiene la ejecución de tareas en todas las colas
+   */
+  stop() {
+    this.isRunning = false;
+    
+    // Disparar hook cuando se detiene el sistema de colas (global)
+    if (this.globalHooks) {
+      this.globalHooks.doAction('queue_system_stopped');
+    }
+    
+    // Disparar hook cuando se detiene el sistema de colas (específico de cada cola)
+    for (const [queueName, queue] of this.queues) {
+      if (queue.hooks) {
+        queue.hooks.doAction('queue_system_stopped', queueName);
+      }
+    }
+  }
+
+  /**
+   * Procesa tareas en una cola específica
+   * @param {string} queueName - Nombre de la cola
+   */
+  async processQueue(queueName) {
+    if (!this.isRunning) {
+      return;
+    }
+    
+    const queue = this.queues.get(queueName);
+    if (!queue || queue.processing || queue.paused) {
+      // Ya se está procesando esta cola o está pausada, salir para evitar condiciones de carrera
+      return;
+    }
+    
+    // Marcar la cola como en proceso para evitar condiciones de carrera
+    queue.processing = true;
+    
+    try {
+      // Procesar tareas mientras haya tareas pendientes y capacidad de trabajo
+      while (
+        this.isRunning && 
+        !queue.paused &&  // Asegurarse de que la cola no esté pausada
+        queue.workers < queue.maxWorkers && 
+        this.pendingTasks.get(queueName).length > 0
+      ) {
+        const task = this.pendingTasks.get(queueName).shift();
+        
+        if (task) {
+          // Marcar la tarea como en proceso
+          this.runningTasks.get(queueName).add(task.id);
+          
+          // Incrementar contador de workers
+          queue.workers++;
+          
+          // Procesar la tarea en segundo plano
+          this.executeTask(queueName, task).finally(() => {
+            // Decrementar contador de workers
+            queue.workers--;
+            
+            // Remover la tarea de las tareas en proceso
+            this.runningTasks.get(queueName).delete(task.id);
+            
+            // Continuar procesando si el sistema sigue corriendo
+            if (this.isRunning && !queue.paused) {
+              setImmediate(() => {
+                this.processQueue(queueName);
+              });
+            }
+          });
+        }
+      }
+    } finally {
+      // Marcar la cola como no en proceso
+      queue.processing = false;
+    }
+  }
+
+  /**
+   * Ejecuta una tarea específica
+   * @param {string} queueName - Nombre de la cola
+   * @param {Object} task - Objeto de la tarea
+   */
+  async executeTask(queueName, task) {
+    const queue = this.queues.get(queueName);
+    
+    try {
+      // Disparar hook antes de ejecutar la tarea (primero global, luego específico de cola)
+      let processedTask = task.task;
+      
+      // Aplicar filtro global si existe
+      if (this.globalHooks) {
+        processedTask = this.globalHooks.applyFilters('queue_execute_task', processedTask, queueName, task);
+      }
+      
+      // Aplicar filtro específico de la cola si existe
+      if (queue.hooks) {
+        processedTask = queue.hooks.applyFilters('queue_execute_task', processedTask, queueName, task);
+      }
+      
+      await processedTask(task.data, task);
+      
+      // Disparar hook cuando la tarea se completa exitosamente (global y específico)
+      if (this.globalHooks) {
+        this.globalHooks.doAction('queue_task_completed', queueName, task);
+      }
+      
+      if (queue.hooks) {
+        queue.hooks.doAction('queue_task_completed', queueName, task);
+      }
+    } catch (error) {
+      // Incrementar intentos
+      task.attempts++;
+      
+      // Disparar hook cuando la tarea falla (global y específico)
+      if (this.globalHooks) {
+        this.globalHooks.doAction('queue_task_failed', queueName, task, error);
+      }
+      
+      if (queue.hooks) {
+        queue.hooks.doAction('queue_task_failed', queueName, task, error);
+      }
+      
+      // Verificar si hay más intentos disponibles
+      if (task.attempts < task.maxAttempts) {
+        // Agregar de nuevo a la cola con retraso
+        setTimeout(() => {
+          const pendingQueue = this.pendingTasks.get(queueName);
+          pendingQueue.push(task);
+          pendingQueue.sort((a, b) => a.priority - b.priority);
+          
+          // Disparar hook cuando se reintenta una tarea (global y específico)
+          if (this.globalHooks) {
+            this.globalHooks.doAction('queue_task_retry', queueName, task);
+          }
+          
+          if (queue.hooks) {
+            queue.hooks.doAction('queue_task_retry', queueName, task);
+          }
+          
+          if (this.isRunning) {
+            this.processQueue(queueName);
+          }
+        }, this.queues.get(queueName).retryDelay);
+      } else {
+        // Agregar a la cola de tareas fallidas
+        const failedQueue = this.failedTasks.get(queueName);
+        failedQueue.push(task);
+        
+        // Disparar hook de fallback para tareas que han fallado definitivamente (global y específico)
+        if (this.globalHooks) {
+          // Permitir que los hooks manejen la lógica de fallback
+          this.globalHooks.doAction('queue_task_fallback', queueName, task, error);
+        }
+        
+        if (queue.hooks) {
+          // Permitir que los hooks específicos de la cola manejen la lógica de fallback
+          queue.hooks.doAction('queue_task_fallback', queueName, task, error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Obtiene el estado actual del sistema de colas
+   * @returns {Object} - Estado del sistema de colas
+   */
+  getStatus() {
+    const status = {};
+    
+    for (const [queueName, queue] of this.queues.entries()) {
+      status[queueName] = {
+        name: queueName,
+        pendingTasks: this.pendingTasks.get(queueName).length,
+        runningTasks: this.runningTasks.get(queueName).size,
+        failedTasks: this.failedTasks.get(queueName).length,
+        workers: queue.workers,
+        maxWorkers: queue.maxWorkers,
+        processing: queue.processing,
+        paused: queue.paused || false
+      };
+    }
+    
+    return status;
+  }
+
+  /**
+   * Pausa una cola específica
+   * @param {string} queueName - Nombre de la cola a pausar
+   * @returns {boolean} - True si la cola fue pausada exitosamente
+   */
+  pauseQueue(queueName) {
+    const queue = this.queues.get(queueName);
+    if (!queue) {
+      return false;
+    }
+    
+    queue.paused = true;
+    
+    // Disparar hook cuando se pausa una cola
+    if (this.globalHooks) {
+      this.globalHooks.doAction('queue_paused', queueName);
+    }
+    
+    return true;
+  }
+
+  /**
+   * Reanuda una cola específica
+   * @param {string} queueName - Nombre de la cola a reanudar
+   * @returns {boolean} - True si la cola fue reanudada exitosamente
+   */
+  resumeQueue(queueName) {
+    const queue = this.queues.get(queueName);
+    if (!queue) {
+      return false;
+    }
+    
+    queue.paused = false;
+    
+    // Disparar hook cuando se reanuda una cola
+    if (this.globalHooks) {
+      this.globalHooks.doAction('queue_resumed', queueName);
+    }
+    
+    // Si el sistema está corriendo, iniciar procesamiento
+    if (this.isRunning) {
+      setImmediate(() => {
+        this.processQueue(queueName);
+      });
+    }
+    
+    return true;
+  }
+
+  /**
+   * Limpia las tareas pendientes de una cola específica
+   * @param {string} queueName - Nombre de la cola a limpiar
+   * @returns {boolean} - True si la cola fue limpiada exitosamente
+   */
+  clearQueue(queueName) {
+    const queue = this.queues.get(queueName);
+    if (!queue) {
+      return false;
+    }
+    
+    // Limpiar tareas pendientes
+    const pendingQueue = this.pendingTasks.get(queueName);
+    if (pendingQueue) {
+      pendingQueue.length = 0;
+    }
+    
+    // Disparar hook cuando se limpia una cola
+    if (this.globalHooks) {
+      this.globalHooks.doAction('queue_cleared', queueName);
+    }
+    
+    return true;
+  }
+
+  /**
+   * Limpia las tareas fallidas de una cola específica
+   * @param {string} queueName - Nombre de la cola
+   */
+  clearFailedTasks(queueName) {
+    if (this.failedTasks.has(queueName)) {
+      this.failedTasks.get(queueName).length = 0;
+    }
+  }
+
+  /**
+   * Reintenta todas las tareas fallidas en una cola específica
+   * @param {string} queueName - Nombre de la cola
+   */
+  retryFailedTasks(queueName) {
+    if (!this.failedTasks.has(queueName)) {
+      return;
+    }
+    
+    const failedQueue = this.failedTasks.get(queueName);
+    const pendingQueue = this.pendingTasks.get(queueName);
+    
+    // Resetear intentos para todas las tareas fallidas
+    for (const task of failedQueue) {
+      task.attempts = 0;
+      pendingQueue.push(task);
+    }
+    
+    // Vaciar la cola de tareas fallidas
+    failedQueue.length = 0;
+    
+    // Reordenar la cola de pendientes
+    pendingQueue.sort((a, b) => a.priority - b.priority);
+    
+    // Procesar la cola si el sistema está corriendo
+    if (this.isRunning) {
+      this.processQueue(queueName);
+    }
+  }
+}
+
+module.exports = QueueSystem;

package/lib/queue/admin_example.js

@@ -0,0 +1,114 @@
+/**
+ * Ejemplo de uso del sistema de colas con módulo de administración
+ * Archivo de ejemplo: queue/admin_example.js
+ */
+
+const { APIServer, QueueIntegration } = require('../../index.js');
+
+// Crear servidor
+const server = new APIServer({ port: 3000 });
+
+// Crear instancia de la integración de colas
+const queueIntegration = new QueueIntegration();
+const queueSystem = queueIntegration.getQueueSystem();
+
+// Ejemplo de tarea simple
+function ejemploTarea(datos, taskObj) {
+  return new Promise((resolve, reject) => {
+    console.log(`Procesando tarea con datos:`, datos);
+    
+    // Simular un proceso que podría fallar
+    if (Math.random() < 0.3) { // 30% de probabilidad de fallo
+      console.error(`Falló la tarea con ID: ${taskObj.id}`);
+      reject(new Error(`Tarea fallida intencionalmente`));
+    } else {
+      console.log(`Tarea completada exitosamente con ID: ${taskObj.id}`);
+      resolve(`Resultado de la tarea con ID: ${taskObj.id}`);
+    }
+    
+    // Simular tiempo de procesamiento
+    setTimeout(() => {
+      if (Math.random() < 0.3) {
+        reject(new Error(`Tarea fallida después de procesamiento`));
+      } else {
+        resolve(`Tarea completada con éxito`);
+      }
+    }, 1000);
+  });
+}
+
+// Crear algunas colas de ejemplo
+queueIntegration.createQueue('imagenes', { 
+  concurrency: 3, 
+  retryAttempts: 2, 
+  retryDelay: 1000
+});
+
+queueIntegration.createQueue('correos', { 
+  concurrency: 2, 
+  retryAttempts: 3, 
+  retryDelay: 2000
+});
+
+queueIntegration.createQueue('pagos', { 
+  concurrency: 1, 
+  retryAttempts: 5, 
+  retryDelay: 3000
+});
+
+// Agregar algunas tareas a las colas
+console.log("Agregando tareas a las colas...");
+
+// Tareas para cola de imágenes
+for (let i = 0; i < 3; i++) {
+  queueIntegration.addTask('imagenes', ejemploTarea, { 
+    id: i, 
+    tipo: 'imagen',
+    nombre: `imagen_${i}.jpg`
+  }, i);
+}
+
+// Tareas para cola de correos
+for (let i = 0; i < 3; i++) {
+  queueIntegration.addTask('correos', ejemploTarea, { 
+    id: i, 
+    tipo: 'correo',
+    destinatario: `usuario${i}@ejemplo.com`
+  }, i);
+}
+
+// Tareas para cola de pagos
+for (let i = 0; i < 3; i++) {
+  queueIntegration.addTask('pagos', ejemploTarea, { 
+    id: i, 
+    tipo: 'pago',
+    monto: 100 + i * 50
+  }, i);
+}
+
+// Iniciar el sistema de colas
+console.log("Iniciando el sistema de colas...");
+queueIntegration.start();
+
+// Iniciar el servidor y la extensión de administración
+server.start();
+
+// Inicializar la extensión de administración en el puerto 9999
+server.initializeAdminExtension({
+  port: 9999,
+  host: '127.0.0.1'
+});
+
+console.log("Servidor iniciado en http://localhost:3000");
+console.log("Extensión de administración disponible en telnet localhost 9999");
+console.log("Comandos disponibles para colas: queues, queue-info, queue-pause, queue-resume, queue-clear, queue-retry-failed");
+
+// Mostrar estado periódicamente
+setInterval(() => {
+  console.log('\n--- Estado del sistema de colas ---');
+  const status = queueIntegration.getStatus();
+  for (const [queueName, queueStatus] of Object.entries(status)) {
+    console.log(`${queueName}: Pendientes=${queueStatus.pendingTasks}, En proceso=${queueStatus.runningTasks}, Fallidas=${queueStatus.failedTasks}, Pausada=${queueStatus.paused}`);
+  }
+  console.log('------------------------------------\n');
+}, 10000);