insitu-js 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,68 @@ El versionado sigue SemVer (MAJOR.MINOR.PATCH).
 
 ---
 
+## [1.0.1] - 2026-02-13
+
+### Refactorización DRY y Mejoras en el WAF - Insitu Framework
+
+#### Archivo Nuevo: `lib/utils/executeMiddleware.js`
+- Creación del módulo centralizado `executeMiddleware` para la ejecución de middlewares
+- Implementación del método reutilizable `executeMiddleware(middleware, req, res, nextFn = null)` con manejo de promesas
+
+#### Archivos Modificados:
+- `lib/core/server.js`
+- `lib/loader/routeLoader.js`
+- `lib/core/router.js`
+- `lib/security/globalWAFStats.js`
+- `lib/security/firewall.js`
+- `lib/admin/modules/WAFModule.js`
+
+#### Implementación de Método Centralizado executeMiddleware
+- Eliminación de múltiples instancias de código repetido para ejecución de middlewares
+- Reemplazo de lógica local con importación y uso del módulo centralizado
+- Actualización del método `use` en el router para usar el método centralizado
+- Implementación de definición dinámica de métodos HTTP en el router
+
+#### Implementación de Funcionalidades de Log y Monitor en el WAF
+- Añadida propiedad `monitoredRequests` al objeto global de estadísticas del WAF
+- Implementación completa de la acción "monitor" en el middleware de firewall
+- Almacenamiento de solicitudes monitoreadas en el mapa global `monitoredRequests`
+- Añadido comando `waf-monitored` al módulo de administración WAF
+- Implementación del método `showMonitoredRequests()` para mostrar solicitudes monitoreadas
+- Actualización del comando `waf-logs` para mostrar solicitudes registradas con acción "log"
+
+#### Aplicación del Principio DRY (Don't Repeat Yourself)
+- Creación del método `createAuthenticatedHandler()` para manejar lógica de autenticación
+- Implementación de métodos para respuestas HTTP comunes (`sendJsonResponse()`, `sendForbiddenResponse()`, `sendNotFoundResponse()`, `sendRequestTooLargeResponse()`)
+- Uso del método reutilizable `handleError()` en lugar de llamar directamente a ErrorHandler.handle()
+
+#### Mejoras en el Manejo de Errores y Configuración
+- Centralización del manejo de errores con el método `handleError()`
+- Creación del método `isJsonRequest()` para verificar tipo de contenido
+- Implementación del método `setStaticFileHeaders()` para configurar headers de archivos estáticos
+
+#### Optimizaciones de Estadísticas y Hooks
+- Método `setupResponseCapture()` para capturar datos de respuesta para estadísticas
+- Método `updateRequestProcessingStats()` para actualizar estadísticas de procesamiento
+- Método `registerRouteAndEndpointStats()` para registrar estadísticas de acceso
+- Métodos para manejar eventos de hooks de solicitud (`handleRouteMatched()`, `handleMiddlewareResponseFinished()`)
+
+#### Mejoras en Verificaciones y Validaciones
+- Método `isMiddlewareFunction()` para verificar si un middleware es una función
+- Método `isAsyncFunction()` para verificar si una función es asíncrona
+
+#### Beneficios Obtenidos
+- Eliminación significativa de código duplicado
+- Mejor mantenibilidad: cambios en lógica común solo se realizan en un lugar
+- Mayor consistencia en el manejo de operaciones repetitivas
+- Funcionalidad completa de las acciones "log" y "monitor" en el WAF
+- Almacenamiento eficiente de solicitudes registradas y monitoreadas
+- Visibilidad mejorada a través de comandos específicos (`waf-logs`, `waf-monitored`)
+- Reducción de posibles errores por inconsistencias
+- Claridad mejorada del código
+
+---
+
 ## [1.0.0] - 2026-02-12
 
 ### Consolidated Release - Insitu Framework

package/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/changelogs/1.0.1/CENTRALIZED_EXECUTE_MIDDLEWARE_IMPLEMENTATION.md

@@ -0,0 +1,88 @@
+# Implementación de Método Centralizado executeMiddleware
+
+## Descripción
+Este documento resume la implementación del principio DRY (Don't Repeat Yourself) mediante la creación de un módulo centralizado para la ejecución de middlewares en el framework Insitu.
+
+## Motivación
+Se identificaron múltiples instancias de código repetido para la ejecución de middlewares en diferentes archivos del framework, lo cual violaba el principio DRY y dificultaba la mantenibilidad.
+
+## Solución Implementada
+
+### 1. Creación del módulo centralizado
+Se creó el archivo `lib/utils/executeMiddleware.js` que contiene la lógica reutilizable para ejecutar middlewares:
+
+```javascript
+/**
+ * Módulo centralizado para la ejecución de middlewares
+ * Implementación del componente utils/executeMiddleware.js
+ * Insitu Framework - Funcionalidad de ejecución de middleware reutilizable
+ */
+
+/**
+ * Método para ejecutar un middleware con manejo de promesas
+ * @param {Function} middleware - Middleware a ejecutar
+ * @param {Object} req - Objeto de solicitud
+ * @param {Object} res - Objeto de respuesta
+ * @param {Function} nextFn - Función next opcional
+ * @returns {Promise} - Promesa que se resuelve cuando el middleware termina
+ */
+function executeMiddleware(middleware, req, res, nextFn = null) {
+  return new Promise((resolve, reject) => {
+    // Si no se proporciona una función next personalizada, usar una por defecto
+    const next = nextFn || ((err) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve();
+      }
+    });
+
+    const result = middleware(req, res, next);
+
+    // Si el middleware devuelve una promesa, esperarla
+    if (result && typeof result.then === 'function') {
+      result.then(resolve).catch(reject);
+    }
+  });
+}
+
+module.exports = { executeMiddleware };
+```
+
+### 2. Actualización de archivos existentes
+
+#### a) Actualización de `lib/core/server.js`
+- Se agregó la importación del módulo centralizado
+- Se reemplazó la definición local del método `executeMiddleware` con una referencia al método centralizado
+
+#### b) Actualización de `lib/loader/routeLoader.js`
+- Se agregó la importación del módulo centralizado
+- Se reemplazaron las dos instancias de lógica repetida de middleware con llamadas al método centralizado
+
+#### c) Actualización de `lib/core/router.js`
+- Se agregó la importación del módulo centralizado
+- Se actualizó el método `use` para usar el método centralizado
+
+#### d) Optimización adicional en `lib/core/router.js`
+- Se implementó la definición dinámica de métodos HTTP para evitar repetición de código
+
+## Beneficios Obtenidos
+
+1. **Eliminación de código duplicado**: Se eliminaron múltiples instancias de la misma lógica de ejecución de middleware
+2. **Mejor mantenibilidad**: Cualquier cambio en la lógica de ejecución de middleware solo necesita hacerse en un lugar
+3. **Consistencia**: Todos los puntos donde se ejecutan middlewares utilizan exactamente la misma lógica
+4. **Reducción de errores**: Menos código duplicado significa menos posibilidades de introducir inconsistencias o errores
+5. **Claridad del código**: La intención de las funciones es más clara y el código es más legible
+
+## Pruebas Realizadas
+
+Se realizaron pruebas completas para asegurar que la funcionalidad del sistema permanece intacta:
+- El servidor responde correctamente a solicitudes HTTP
+- La consola de administración funciona correctamente
+- Las operaciones CRUD (como crear usuarios) funcionan como se esperaba
+- Las estadísticas y el sistema de caché operan correctamente
+- Todos los comandos de administración están disponibles y funcionan
+
+## Estado Funcional
+
+El comportamiento funcional del sistema permanece exactamente igual después de las refactorizaciones. Todos los casos de uso originales siguen funcionando como se esperaba, demostrando que la implementación centralizada es completamente compatible con la funcionalidad existente.