jerkjs 2.5.4 → 2.5.8

package/README_LEGACY.md

@@ -0,0 +1,513 @@
+# JERK Framework v2.5.6
+
+![JERK Framework Logo](jerk.webp)
+
+**¿Nuevo en JERK? Comienza tu proyecto rápidamente con nuestro Starter Kit**
+
+Nuestro Starter Kit en `standard/server.js` es la forma más rápida de comenzar con JERK. Viene con todas las funcionalidades del framework ya configuradas, permitiéndote concentrarte en desarrollar tu aplicación en lugar de configurar infraestructura.
+
+**Características del Starter Kit:**
+- Configuración lista para usar con todos los componentes principales
+- Carga de rutas desde archivo JSON (`routes.json`)
+- Sistema de controladores preconfigurado
+- Middlewares esenciales ya integrados (autenticación, CORS, compresión, firewall, etc.)
+- Sistema de logging y manejo de errores implementado
+- **NUEVO: Arquitectura completa MVC con modelos y soporte para bases de datos**
+- **NUEVO: Compatible con qbuilderjs para consultas SQL seguras y eficientes**
+
+**Cómo comenzar:**
+1. Edita el archivo `routes.json` para definir tus rutas y asociarlas a tus controladores
+
+Ejemplo básico de `routes.json`:
+```json
+[
+  {
+    "path": "/",
+    "method": "GET",
+    "controller": "HomeController",
+    "handler": "index",
+    "contentType": "text/html"
+  },
+  {
+    "path": "/api/users",
+    "method": "GET",
+    "controller": "UserController",
+    "handler": "getAllUsers",
+    "contentType": "application/json"
+  }
+]
+```
+
+2. Crea tus controladores según las rutas definidas
+
+Por ejemplo, para la ruta principal "/", crea un archivo `HomeController.js`:
+```javascript
+class HomeController {
+  index(req, res) {
+    res.render('index.html', { data: 'Hola' });
+  }
+}
+
+module.exports = new HomeController();
+```
+
+3. ¡Tu aplicación estará listo para usar!
+
+El Starter Kit incluye controladores de ejemplo para que puedas ver cómo funciona el sistema.
+
+## Ejemplo de Rutas Estáticas
+
+Desde la versión 2.1.8, JERK Framework soporta rutas estáticas para servir archivos desde directorios locales:
+
+### En routes.json:
+```json
+[
+  {
+    "path": "/static",
+    "method": "GET",
+    "static": {
+      "dir": "./public",
+      "index": ["index.html", "index.htm"],
+      "cacheControl": "public, max-age=3600"
+    }
+  },
+  {
+    "path": "/assets",
+    "method": "GET",
+    "static": {
+      "dir": "./public",
+      "index": [],
+      "cacheControl": "public, max-age=86400"
+    }
+  }
+]
+```
+
+### Usando addRoute():
+```javascript
+// Ruta estática para servir archivos desde ./public
+server.addRoute({
+  method: 'GET',
+  path: '/static',
+  static: {
+    dir: './public',
+    index: ['index.html'],
+    cacheControl: 'public, max-age=3600'
+  }
+});
+
+// Ruta estática para servir archivos JS, CSS e imágenes
+server.addRoute('GET', '/assets', {
+  static: {
+    dir: './public/assets',
+    index: [],
+    cacheControl: 'public, max-age=86400'
+  }
+});
+```
+
+## Novedades en v2.5.1
+
+### Corrección de rutas estáticas
+- **Solución de error crítico con directorios**: Se corrigió un error donde el sistema de rutas estáticas intentaba leer directorios como si fueran archivos, causando el error `EISDIR: illegal operation on a directory, read`. Ahora el sistema verifica explícitamente si una ruta es un directorio y en tal caso busca el archivo índice correspondiente.
+
+## Carga de Rutas desde Múltiples Archivos (v2.5.0)
+
+Desde la versión 2.5.0, JERK Framework incluye el componente `RouteDirectoryLoader` que permite cargar rutas desde múltiples archivos JSON ubicados en un directorio específico. Esta funcionalidad mejora la organización y mantenibilidad de aplicaciones grandes al permitir dividir las rutas en varios archivos en lugar de tener un único archivo `routes.json`.
+
+### Ventajas del RouteDirectoryLoader:
+- Organización por funcionalidad (usuarios, autenticación, API, etc.)
+- Mayor mantenibilidad en proyectos grandes
+- Detección automática de rutas duplicadas
+- Mensajes de advertencia coloreados para rutas sobreescritas
+- Recarga automática de rutas en desarrollo
+
+### Uso del RouteDirectoryLoader:
+
+```javascript
+const { APIServer, RouteDirectoryLoader } = require('jerkjs');
+
+const server = new APIServer({ port: 3000 });
+const routeDirectoryLoader = new RouteDirectoryLoader();
+
+// Cargar rutas desde un directorio que contiene múltiples archivos JSON
+routeDirectoryLoader.loadRoutesFromDirectory(server, './routes')
+  .then(routes => {
+    console.log(`${routes.length} rutas cargadas exitosamente`);
+    server.start();
+  })
+  .catch(error => {
+    console.error('Error cargando rutas desde directorio:', error.message);
+  });
+```
+
+### Estructura de directorio recomendada:
+```
+routes/
+├── api-routes.json
+├── auth-routes.json
+├── static-routes.json
+└── user-routes.json
+```
+
+### Ejemplo de archivo api-routes.json:
+```json
+[
+  {
+    "path": "/api/users",
+    "method": "GET",
+    "controller": "./controllers/userController.js",
+    "handler": "getAllUsers",
+    "contentType": "application/json"
+  },
+  {
+    "path": "/api/users/:id",
+    "method": "GET",
+    "controller": "./controllers/userController.js",
+    "handler": "getUserById",
+    "contentType": "application/json"
+  }
+]
+```
+
+### Detección de rutas duplicadas:
+Cuando el sistema detecta que una ruta ya ha sido definida previamente, muestra mensajes de advertencia:
+
+```
+[RUTA SOBREESCRITA] Archivo: ./routes/api-routes.json, Ruta: GET /users
+[RUTA ACTUAL] Archivo: ./routes/other-routes.json, Ruta: GET /users
+```
+
+- El mensaje en **rojo** indica la ruta que será sobreescrita
+- El mensaje en **amarillo** indica la ruta que prevalece
+
+### Recarga automática de rutas:
+Durante el desarrollo, puedes habilitar la recarga automática cuando se modifican los archivos de rutas:
+
+```javascript
+// Observar cambios en el directorio de rutas
+routeDirectoryLoader.watchRoutesDirectory(server, './routes', 1000); // 1000ms debounce
+```
+
+Visita nuestra página web: https://jerk.page.gd/
+Repositorio oficial: https://gitlab.com/bytedogssyndicate1/jerk/
+
+## Características
+
+- **Arquitectura Modular**: Componentes independientes para mayor flexibilidad
+- **Seguridad Avanzada**: Firewall integrado (WAF) con detección de ataques
+- **Sistema de Hooks**: Similar al sistema de WordPress para extensibility
+- **Autenticación Flexible**: Soporte para JWT, API Keys, Basic Auth, OAuth2, OpenID Connect
+- **Almacenamiento de Tokens**: Soporte para memoria, JSON, SQLite y MariaDB
+- **Enrutamiento Avanzado**: Soporte para rutas parametrizadas, anidadas y estáticas
+- **Soporte para Frontend**: Capacidad de servir contenido HTML y otros tipos de contenido
+- **Configuración de Content-Type**: Especificación de headers Content-Type en routes.json
+- **Middlewares Integrados**: CORS, rate limiting, compresión, firewall, etc.
+- **Gestión de Controladores**: Carga dinámica de controladores desde archivos
+- **Carga de Rutas**: Definición de rutas desde archivos JSON
+- **Sistema de Sesiones**: Gestión completa de sesiones con soporte para autenticación
+- **Motor de Plantillas MVC**: Sistema profesional de vistas con soporte para filtros, helpers y hooks
+- **Arquitectura de Modelos Completa (MVC)**: Capa de modelos para la lógica de negocio y acceso a datos
+- **Sistema de Adaptadores de Base de Datos**: Soporte para múltiples motores de base de datos (MariaDB, MySQL, etc.)
+- **Compatible con qbuilderjs**: Soporte para integrar el QueryBuilder externo qbuilderjs para construir consultas SQL complejas de manera segura y eficiente
+- **Servicio de Archivos Estáticos**: Soporte para servir archivos desde directorios locales con configuración flexible
+- **Extensibilidad**: Sistema de hooks y filters para personalización
+
+## Instalación
+
+```bash
+npm install jerkjs
+```
+
+## Uso Básico
+
+```javascript
+const { APIServer, Router, Logger } = require('jerkjs');
+
+// Crear instancia del servidor
+const server = new APIServer({
+  port: 3000,
+  host: 'localhost'
+});
+
+// Crear instancia del logger
+const logger = new Logger({ level: 'info' });
+
+// Definir rutas
+server.addRoute('GET', '/', (req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ message: '¡Hola Mundo!' }));
+});
+
+// Iniciar el servidor
+server.start();
+```
+
+## Componentes Principales
+
+### APIServer
+Servidor HTTP/HTTPS básico con soporte para rutas parametrizadas, middlewares y configuración avanzada.
+
+### Router
+Sistema de enrutamiento avanzado con soporte para rutas anidadas y prefijos.
+
+### Authenticator
+Middleware de autenticación con soporte para múltiples métodos (JWT, API Keys, Basic Auth, OAuth2, OpenID Connect).
+
+### SecurityEnhancedServer
+Servidor con funcionalidades de seguridad avanzada (WAF) integradas.
+
+### RouteLoader
+Carga de rutas desde archivos JSON con soporte para autenticación, controladores y especificación de content-type.
+
+### TokenManager
+Gestión de tokens JWT con diferentes tipos de almacenamiento (memoria, JSON, SQLite, MariaDB).
+
+### Firewall
+Middleware de firewall con detección de patrones de ataque y listas blancas/negras.
+
+### Hooks System
+Sistema de hooks y filters similar al de WordPress para extensibilidad.
+
+### SessionManager
+Sistema completo de gestión de sesiones con soporte para autenticación basada en sesiones.
+
+### ViewEngine
+Motor de plantillas profesional con soporte para filtros, helpers, condiciones, bucles y hooks.
+
+### ControllerBase
+Controlador base que facilita el desarrollo de controladores MVC con soporte para vistas.
+
+## Seguridad
+
+El framework incluye múltiples capas de seguridad:
+
+- **Web Application Firewall (WAF)**: Detección de SQL injection, XSS, path traversal, etc.
+- **Rate Limiting**: Limitación de peticiones por IP o usuario
+- **Firewall**: Bloqueo automático por intentos fallidos
+- **Listas Blancas/Negras**: Control de acceso por IP
+- **Auditoría de Seguridad**: Registro de eventos de seguridad
+- **Autenticación Robusta**: Soporte para múltiples métodos de autenticación
+
+## Sistema de Hooks
+
+El framework incluye un sistema de hooks y filters similar al de WordPress:
+
+```javascript
+const { hooks } = require('jerkjs');
+
+// Registrar una acción
+hooks.addAction('firewall_request_blocked', (rule, clientIP, req, res) => {
+  console.log(`Solicitud bloqueada: ${rule.name} para IP: ${clientIP}`);
+});
+
+// Registrar un filtro
+hooks.addFilter('session_create_data', (userData, req) => {
+  return {
+    ...userData,
+    ipAddress: req.headers['x-forwarded-for'] || req.connection.remoteAddress,
+    createdAt: new Date().toISOString()
+  };
+});
+```
+
+## Motor de Plantillas MVC
+
+El framework incluye un motor de plantillas profesional con soporte para:
+
+- Variables: `{{variable}}`
+- Condiciones: `{{if variable}}contenido{{endif}}`
+- Bucles: `{{foreach:array}}contenido{{endforeach}}`
+- Inclusiones: `{{include:header}}`
+- Filtros: `{{variable|upper}}`
+- Helpers personalizados
+
+## Gestión de Sesiones
+
+El framework incluye un sistema completo de gestión de sesiones:
+
+```javascript
+const { SessionManager } = require('jerkjs');
+
+const sessionManager = new SessionManager({
+  secret: 'your-session-secret',
+  timeout: 3600000 // 1 hora
+});
+
+// Usar como middleware
+server.use(sessionManager.middleware());
+```
+
+## Ejemplos
+
+El proyecto incluye varios ejemplos completos:
+
+- **v2_json_auth**: Autenticación JWT con tokens almacenados en JSON
+- **v2_mariadb_auth**: Autenticación JWT con tokens almacenados en MariaDB
+- **v2_sqlite_auth**: Autenticación JWT con tokens almacenados en SQLite
+- **public**: API pública de ejemplo con CORS y rate limiting
+- **frontend**: Ejemplo de servidor que combina API y frontend con diferentes content-types
+- **hooks**: Ejemplo avanzado de uso del sistema de hooks con logging y seguimiento de solicitudes
+
+Para ver los ejemplos completos, visita los directorios `v2examplle/` y `examples/`.
+
+
+## Documentación
+
+Además de la documentación en el README, el proyecto incluye documentación adicional:
+
+- **Guía de inicio rápido**: `docs/guia_inicio_rapido_jerkjs.md` - Una guía completa para empezar rápidamente con JERKJS, incluyendo formatos de archivos, estructura de controladores, motor de plantillas y sistema de hooks.
+
+## Contribuciones
+
+Las contribuciones son bienvenidas. Por favor, abre un issue o envía un pull request en GitLab.
+
+## Licencia
+
+Apache 2.0
+
+## Arquitectura de Modelos (MVC)
+
+JERK Framework v2.2.0 introduce una arquitectura completa de modelos que completa el patrón MVC. Los modelos permiten encapsular la lógica de negocio y el acceso a datos en componentes reutilizables.
+
+### Ejemplo de Modelo Simple con MariaDB
+
+```javascript
+const { ModelBase, MariaDBAdapter } = require('jerkjs');
+
+// Definir un modelo para usuarios
+class UserModel extends ModelBase {
+  constructor(options = {}) {
+    super({
+      ...options,
+      tableName: options.tableName || 'users'
+    });
+
+    // Definir campos del modelo
+    this.fields = {
+      id: { type: 'integer', primaryKey: true, autoIncrement: true },
+      username: { type: 'string', required: true },
+      email: { type: 'string', required: true },
+      password: { type: 'string', required: true },
+      createdAt: { type: 'datetime', default: 'CURRENT_TIMESTAMP' }
+    };
+  }
+
+  // Método personalizado para encontrar usuario por email
+  async findByEmail(email) {
+    return await this.findOne({ email });
+  }
+
+  // Método personalizado para crear usuario con validación
+  async createUser(userData) {
+    // Validar datos antes de crear
+    const validation = this.validate('create', userData);
+    if (!validation.isValid) {
+      throw new Error(`Validación fallida: ${validation.errors.join(', ')}`);
+    }
+
+    return await this.create(userData);
+  }
+}
+
+// Configurar el adaptador de MariaDB
+const dbConfig = {
+  host: 'localhost',
+  user: 'tu_usuario',
+  password: 'tu_contraseña',
+  database: 'tu_base_de_datos'
+};
+
+const mariaDBAdapter = new MariaDBAdapter(dbConfig);
+
+// Crear instancia del modelo con el adaptador
+const userModel = new UserModel({
+  adapter: mariaDBAdapter,
+  tableName: 'users'
+});
+
+// Uso del modelo
+async function ejemploUsoModelo() {
+  try {
+    // Crear un nuevo usuario
+    const nuevoUsuario = await userModel.createUser({
+      username: 'juan.perez',
+      email: 'juan@example.com',
+      password: 'contraseña_segura'
+    });
+
+    console.log('Usuario creado:', nuevoUsuario);
+
+    // Buscar usuario por email
+    const usuario = await userModel.findByEmail('juan@example.com');
+    console.log('Usuario encontrado:', usuario);
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+### Uso de Modelos en Controladores con loadModel
+
+JERK Framework proporciona un helper `loadModel` en el ControllerBase para facilitar la carga y uso de modelos en los controladores:
+
+```javascript
+const ControllerBase = require('jerkjs').ControllerBase;
+
+class UserController extends ControllerBase {
+  constructor() {
+    super();
+
+    // Cargar el modelo de usuario
+    this.userModel = this.loadModel('UserModel', {
+      // Opciones del modelo
+    });
+  }
+
+  async getAllUsers(req, res) {
+    try {
+      // Usar el modelo para obtener usuarios
+      const users = await this.userModel.find({});
+
+      this.json(res, { success: true, data: users });
+    } catch (error) {
+      this.json(res, { success: false, error: error.message }, 500);
+    }
+  }
+
+  async getUserById(req, res) {
+    try {
+      const userId = req.params.id;
+
+      // Usar el modelo para encontrar un usuario específico
+      const user = await this.userModel.findOne({ id: userId });
+
+      if (!user) {
+        this.json(res, { success: false, error: 'Usuario no encontrado' }, 404);
+        return;
+      }
+
+      this.json(res, { success: true, data: user });
+    } catch (error) {
+      this.json(res, { success: false, error: error.message }, 500);
+    }
+  }
+
+  async createUser(req, res) {
+    try {
+      // Usar el modelo para crear un nuevo usuario
+      const newUser = await this.userModel.createUser(req.body);
+
+      this.json(res, { success: true, data: newUser }, 201);
+    } catch (error) {
+      this.json(res, { success: false, error: error.message }, 400);
+    }
+  }
+}
+
+module.exports = new UserController();
+```
+
+## Documentación del Framework
+
+Para una descripción detallada de la arquitectura y componentes del framework, consulta el archivo [JERK_FRAMEWORK_DOCUMENTATION.md](JERK_FRAMEWORK_DOCUMENTATION.md).

package/debug_hook.js

@@ -0,0 +1,11 @@
+// Modificar temporalmente el archivo de hooks para mostrar la estructura completa del objeto
+const { hooks } = require('../index.js');
+
+// Hook para registrar cada ruta encontrada - versión de depuración
+hooks.addAction('route_matched', (matchedRoute, req, res) => {
+    console.log(`[${new Date().toISOString()}] DEBUG route_matched:`);
+    console.log(`  matchedRoute:`, JSON.stringify(matchedRoute, null, 2));
+    console.log(`  req.method:`, req ? req.method : 'undefined');
+    console.log(`  req.url:`, req ? req.url : 'undefined');
+    console.log('---');
+});