blackcoffee2 2.1.0

package/manuales/CREACION_DE_CONTROLADORES_INSITU.md

@@ -0,0 +1,383 @@
+# Guía para Crear Controladores en el Framework Insitu
+
+## Introducción
+
+Los controladores en el framework Insitu son componentes fundamentales que forman parte del patrón MVC (Modelo-Vista-Controlador). Son responsables de manejar las solicitudes HTTP, interactuar con los modelos para obtener o manipular datos, y devolver respuestas apropiadas al cliente.
+
+## Estructura Básica de un Controlador
+
+Un controlador en Insitu debe extender la clase `ControllerBase` que proporciona funcionalidades comunes como:
+
+- Manejo de vistas y motores de plantillas
+- Acceso a datos de solicitud (query, body, params)
+- Métodos para respuesta (JSON, vistas, redirecciones)
+- Carga y manejo de modelos
+
+### Ejemplo Básico de Controlador
+
+```javascript
+const { ControllerBase } = require('insitu');
+
+class EjemploController extends ControllerBase {
+  constructor() {
+    super();
+  }
+
+  // Método para manejar una solicitud GET
+  async index(req, res) {
+    // Establecer variables para la vista
+    this.set('titulo', 'Página de Inicio');
+    this.set('mensaje', '¡Bienvenido al framework Insitu!');
+
+    // Renderizar una vista
+    this.render(res, 'inicio', {
+      usuario: 'Desarrollador',
+      fecha: new Date().toISOString()
+    });
+  }
+
+  // Método para manejar una solicitud POST
+  async crear(req, res) {
+    const datos = req.body;
+    
+    // Aquí iría la lógica para crear un recurso
+    // Por ejemplo, usando un modelo
+    
+    this.json(res, {
+      success: true,
+      message: 'Recurso creado exitosamente',
+      data: datos
+    });
+  }
+}
+
+module.exports = EjemploController;
+```
+
+## Componentes Importantes
+
+### ControllerBase
+
+La clase base `ControllerBase` proporciona varios métodos útiles:
+
+- `set(key, value)` - Establece variables para la vista
+- `view(viewName, data, options)` - Renderiza una vista sin enviarla como respuesta
+- `render(res, viewName, data, options)` - Renderiza una vista y la envía como respuesta HTTP
+- `partial(viewName, data)` - Renderiza una vista parcial (sin layout)
+- `redirect(res, url)` - Redirecciona a otra URL
+- `json(res, data, statusCode)` - Envía una respuesta JSON
+- `input(key, defaultValue)` - Obtiene un valor de la solicitud (query, body o params)
+- `loadModel(modelName, options)` - Carga un modelo para su uso en el controlador
+
+### Interacción con Modelos
+
+Los controladores pueden interactuar con modelos para gestionar datos:
+
+```javascript
+const { ControllerBase } = require('insitu');
+
+class UsuarioController extends ControllerBase {
+  constructor() {
+    super();
+  }
+
+  async listar(req, res) {
+    try {
+      // Cargar el modelo de usuario
+      const userModel = this.loadModel('User');
+      
+      // Obtener todos los usuarios
+      const usuarios = await userModel.find({});
+      
+      // Pasar los usuarios a la vista
+      this.set('usuarios', usuarios);
+      this.render(res, 'usuarios/lista');
+    } catch (error) {
+      this.json(res, { error: error.message }, 500);
+    }
+  }
+
+  async crear(req, res) {
+    try {
+      const userData = req.body;
+      
+      // Cargar el modelo de usuario
+      const userModel = this.loadModel('User');
+      
+      // Crear un nuevo usuario
+      const nuevoUsuario = await userModel.create(userData);
+      
+      this.json(res, {
+        success: true,
+        data: nuevoUsuario
+      }, 201);
+    } catch (error) {
+      this.json(res, { error: error.message }, 500);
+    }
+  }
+}
+
+module.exports = UsuarioController;
+```
+
+## Definición de Rutas
+
+Para conectar tus controladores con rutas, puedes usar el sistema de enrutamiento de Insitu:
+
+### En un archivo de rutas (por ejemplo, routes.json):
+
+```json
+{
+  "routes": [
+    {
+      "method": "GET",
+      "path": "/usuarios",
+      "handler": "./controllers/UsuarioController.listar"
+    },
+    {
+      "method": "POST",
+      "path": "/usuarios",
+      "handler": "./controllers/UsuarioController.crear"
+    },
+    {
+      "method": "GET",
+      "path": "/usuarios/:id",
+      "handler": "./controllers/UsuarioController.obtenerPorId"
+    }
+  ]
+}
+```
+
+### O directamente en tu código de inicialización:
+
+```javascript
+const { Insitu, Router } = require('insitu');
+const UsuarioController = require('./controllers/UsuarioController');
+
+const app = new Insitu();
+const router = new Router();
+
+const usuarioController = new UsuarioController();
+
+router.get('/usuarios', (req, res) => {
+  usuarioController.listar(req, res);
+});
+
+router.post('/usuarios', (req, res) => {
+  usuarioController.crear(req, res);
+});
+
+app.use(router);
+
+app.listen(3000, () => {
+  console.log('Servidor corriendo en puerto 3000');
+});
+```
+
+### Importante: Manejo de Contexto de los Métodos
+
+Cuando se exportan métodos de un controlador para ser usados como handlers de rutas, es crítico mantener el contexto `this` correcto. Si no se hace correctamente, métodos como `this.json()`, `this.set()`, `this.input()`, etc., no funcionarán.
+
+**Forma Incorrecta:**
+```javascript
+// Esto causará un error "Cannot read property 'json' of undefined"
+module.exports = new UsuarioController();
+```
+
+**Forma Correcta:**
+```javascript
+// Crear una instancia del controlador
+const usuarioController = new UsuarioController();
+
+// Asegurar que todos los métodos tengan el contexto correcto
+module.exports = {
+  listar: usuarioController.listar.bind(usuarioController),
+  crear: usuarioController.crear.bind(usuarioController),
+  obtenerPorId: usuarioController.obtenerPorId.bind(usuarioController)
+};
+```
+
+Esto es necesario porque cuando el cargador de rutas obtiene una función específica de un objeto y la llama directamente, pierde el contexto `this`. Usando `.bind()`, nos aseguramos de que `this` siempre se refiera a la instancia correcta del controlador.
+```
+
+## Buenas Prácticas
+
+### 1. Organización de Archivos
+
+Organiza tus controladores en una estructura de directorios clara:
+
+```
+proyecto/
+├── controllers/
+│   ├── UsuarioController.js
+│   ├── ProductoController.js
+│   └── HomeController.js
+├── models/
+│   ├── User.js
+│   └── Product.js
+├── views/
+│   ├── home/
+│   │   └── index.html
+│   └── usuarios/
+│       ├── lista.html
+│       └── detalle.html
+└── routes/
+    └── routes.json
+```
+
+### 2. Manejo de Errores
+
+Siempre implementa manejo de errores adecuado:
+
+```javascript
+async listar(req, res) {
+  try {
+    const modelo = this.loadModel('MiModelo');
+    const datos = await modelo.find({});
+    this.json(res, { success: true, data: datos });
+  } catch (error) {
+    console.error('Error en listar:', error);
+    this.json(res, { 
+      success: false, 
+      error: 'Ocurrió un error al procesar la solicitud' 
+    }, 500);
+  }
+}
+```
+
+### 3. Validación de Datos
+
+Utiliza el middleware de validación de Insitu para validar entradas:
+
+```javascript
+const { Validator } = require('insitu');
+
+// En tu archivo de rutas
+router.post('/usuarios', 
+  Validator.validate({
+    body: {
+      nombre: { type: 'string', required: true, minLength: 2 },
+      email: { type: 'string', required: true, format: 'email' },
+      edad: { type: 'number', min: 0, max: 120 }
+    }
+  }),
+  (req, res) => {
+    usuarioController.crear(req, res);
+  }
+);
+```
+
+### 4. Uso de Métodos HTTP Apropiados
+
+Sigue las convenciones REST para el uso de métodos HTTP:
+
+- `GET` - Obtener recursos
+- `POST` - Crear nuevos recursos
+- `PUT/PATCH` - Actualizar recursos existentes
+- `DELETE` - Eliminar recursos
+
+## Ejemplo Completo
+
+Aquí tienes un ejemplo completo de un controlador para gestionar productos:
+
+```javascript
+const { ControllerBase } = require('insitu');
+
+class ProductoController extends ControllerBase {
+  constructor() {
+    super();
+  }
+
+  // Obtener todos los productos
+  async listar(req, res) {
+    try {
+      const productoModel = this.loadModel('Producto');
+      const productos = await productoModel.find({});
+      
+      this.set('productos', productos);
+      this.set('titulo', 'Lista de Productos');
+      this.render(res, 'productos/lista');
+    } catch (error) {
+      this.json(res, { error: error.message }, 500);
+    }
+  }
+
+  // Obtener un producto por ID
+  async obtenerPorId(req, res) {
+    try {
+      const id = this.input('id');
+      const productoModel = this.loadModel('Producto');
+      const producto = await productoModel.findOne({ id: parseInt(id) });
+      
+      if (!producto) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Producto no encontrado' }));
+        return;
+      }
+      
+      this.json(res, { success: true, data: producto });
+    } catch (error) {
+      this.json(res, { error: error.message }, 500);
+    }
+  }
+
+  // Crear un nuevo producto
+  async crear(req, res) {
+    try {
+      const productoData = this.allInput();
+      const productoModel = this.loadModel('Producto');
+      const nuevoProducto = await productoModel.create(productoData);
+      
+      this.json(res, { 
+        success: true, 
+        data: nuevoProducto 
+      }, 201);
+    } catch (error) {
+      this.json(res, { error: error.message }, 500);
+    }
+  }
+
+  // Actualizar un producto
+  async actualizar(req, res) {
+    try {
+      const id = this.input('id');
+      const productoData = this.allInput();
+      const productoModel = this.loadModel('Producto');
+      
+      const resultado = await productoModel.update({ id: parseInt(id) }, productoData);
+      
+      this.json(res, { 
+        success: true, 
+        message: 'Producto actualizado',
+        affectedRows: resultado
+      });
+    } catch (error) {
+      this.json(res, { error: error.message }, 500);
+    }
+  }
+
+  // Eliminar un producto
+  async eliminar(req, res) {
+    try {
+      const id = this.input('id');
+      const productoModel = this.loadModel('Producto');
+      
+      const resultado = await productoModel.delete({ id: parseInt(id) });
+      
+      this.json(res, { 
+        success: true, 
+        message: 'Producto eliminado',
+        deletedRows: resultado
+      });
+    } catch (error) {
+      this.json(res, { error: error.message }, 500);
+    }
+  }
+}
+
+module.exports = ProductoController;
+```
+
+## Conclusión
+
+Crear controladores en el framework Insitu es sencillo gracias a la clase `ControllerBase` que proporciona funcionalidades comunes. Recuerda seguir las buenas prácticas para mantener tu código limpio, seguro y mantenible. La arquitectura MVC del framework te permite separar claramente la lógica de negocio (modelos), la presentación (vistas) y el flujo de control (controladores).

package/manuales/QUEUE_CLI_MODULE_MANUAL.md

@@ -0,0 +1,289 @@
+# Manual del Módulo CLI de Gestión de Colas para Insitu 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 Insitu 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**: Insitu 1.0.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
+
+Insitu Framework Team
+
+## Versión
+
+v1.0.0