jerkjs 2.5.4 → 2.5.6

package/README.md

@@ -1,217 +1,38 @@
-# JERK Framework v2.5.4
-
-![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
+![JERK Framework](jerk2.5.webp)
+##### JERK Framework v2.5.6
+
+**JERK Framework** es un framework de desarrollo web completo para Node.js que implementa una arquitectura MVC (Modelo-Vista-Controlador) con soporte para APIs REST, seguridad avanzada, y sistemas de plantillas.
+
+## Características Principales
+
+### 🚀 Rendimiento Optimizado
+- Servidor HTTP/HTTPS de alto rendimiento
+- Optimizaciones de rendimiento en el manejo de solicitudes
+- Carga anticipada de módulos comunes para evitar operaciones redundantes
+- Manejo eficiente de rutas estáticas y dinámicas
+
+### 🔐 Seguridad Avanzada
+- Sistema de sesiones con cookies seguras personalizables
+- Filtros para personalizar flags de seguridad de cookies (`Secure`, `SameSite`, etc.)
+- Web Application Firewall (WAF) con detección de patrones de ataque
+- Sistema de autenticación con múltiples estrategias (JWT, API Keys, Basic Auth, OAuth2, OpenID Connect)
+- Protección contra SQL Injection, XSS y otros ataques comunes
+
+### 🏗️ Arquitectura Modular
+- Componentes independientes para mayor flexibilidad
+- Sistema de hooks y filtros similar al de WordPress
+- Soporte para middlewares personalizados
+- Arquitectura MVC completa con modelos, vistas y controladores
+
+### 📊 Soporte para Bases de Datos
+- Adaptadores para diferentes motores de base de datos (Memory, MariaDB/MySQL, SQLite)
+- Integración con QueryBuilder externo (qbuilderjs) para construir consultas SQL seguras
+- Sistema de modelos con operaciones CRUD completas
+
+### 🎨 Motores de Plantillas
+- Motor de plantillas con soporte para variables, condiciones, bucles e inclusiones
+- Filtros y helpers personalizables
+- Soporte para layouts y vistas dinámicas
 
 ## Instalación
 
@@ -222,80 +43,94 @@ npm install jerkjs
 ## Uso Básico
 
 ```javascript
-const { APIServer, Router, Logger } = require('jerkjs');
+const { APIServer, RouteDirectoryLoader, ViewEngine, ModelManager, MemoryAdapter } = require('jerkjs');
 
 // Crear instancia del servidor
 const server = new APIServer({
-  port: 3000,
-  host: 'localhost'
+    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!' }));
+// Configurar motor de vistas
+const viewEngine = new ViewEngine({
+    viewsDir: './views',
+    defaultLayout: 'layout.html'
 });
 
-// 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.
+// Configurar sistema de modelos
+const modelManager = new ModelManager();
+const memoryAdapter = new MemoryAdapter();
+modelManager.registerAdapter('memory', memoryAdapter);
 
-### Authenticator
-Middleware de autenticación con soporte para múltiples métodos (JWT, API Keys, Basic Auth, OAuth2, OpenID Connect).
+// Asociar componentes al servidor
+server.viewEngine = viewEngine;
+server.modelManager = modelManager;
 
-### SecurityEnhancedServer
-Servidor con funcionalidades de seguridad avanzada (WAF) integradas.
+// Cargar rutas desde directorio
+const routeDirectoryLoader = new RouteDirectoryLoader();
+routeDirectoryLoader.loadRoutesFromDirectory(server, './routes');
 
-### RouteLoader
-Carga de rutas desde archivos JSON con soporte para autenticación, controladores y especificación de content-type.
+// Iniciar el servidor
+server.start();
+```
 
-### TokenManager
-Gestión de tokens JWT con diferentes tipos de almacenamiento (memoria, JSON, SQLite, MariaDB).
+## Seguridad de Sesiones
 
-### Firewall
-Middleware de firewall con detección de patrones de ataque y listas blancas/negras.
+JERK Framework incluye un sistema de sesiones con soporte para personalización de flags de seguridad a través de filtros:
 
-### Hooks System
-Sistema de hooks y filters similar al de WordPress para extensibilidad.
+```javascript
+const { hooks } = require('jerkjs');
 
-### SessionManager
-Sistema completo de gestión de sesiones con soporte para autenticación basada en sesiones.
+// Personalizar flags de cookies de sesión
+hooks.addFilter('session_cookie_flags', (defaultFlags, req, res, sessionId) => {
+    // Detectar si la solicitud es HTTPS
+    const isHttps = (req && req.connection && req.connection.encrypted) || 
+                   (req && req.headers && req.headers['x-forwarded-proto'] === 'https');
+    
+    let flags = defaultFlags;
+    
+    // Agregar la flag Secure si es HTTPS
+    if (isHttps) {
+        flags += '; Secure';
+    }
+    
+    // Agregar SameSite según el contexto
+    flags += '; SameSite=Lax';
+    
+    return flags;
+});
+```
 
-### ViewEngine
-Motor de plantillas profesional con soporte para filtros, helpers, condiciones, bucles y hooks.
+## Componentes Principales
 
-### ControllerBase
-Controlador base que facilita el desarrollo de controladores MVC con soporte para vistas.
+### Servidor (APIServer)
+- Servidor HTTP/HTTPS básico con soporte para rutas parametrizadas
+- Manejo de archivos estáticos con soporte para índices y control de caché
+- Sistema de hooks para extensibilidad
+- Soporte para middlewares y manejo de cuerpos de solicitud con límites de tamaño
 
-## Seguridad
+### Sistema de Enrutamiento
+- Router con soporte para rutas anidadas
+- RouteMatcher para coincidencia de rutas parametrizadas con cacheo de expresiones regulares
+- Soporte para rutas estáticas y dinámicas con prioridad adecuada
 
-El framework incluye múltiples capas de seguridad:
+### Middleware
+- CORS, Autenticación, Sesiones, Validación, Rate Limiting
+- Compresión (gzip/deflate) con sistema de hooks
+- Firewall (WAF) con detección de patrones de ataque
+- Audit Logger para eventos 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
+### Componentes MVC
+- ControllerBase con soporte para vistas, layouts y variables
+- ModelBase con operaciones CRUD
+- ViewEngine con soporte para filtros, helpers, condiciones, bucles e inclusiones
+- ModelManager con soporte para múltiples adaptadores
 
-## Sistema de Hooks
+## Sistema de Hooks y Filtros
 
-El framework incluye un sistema de hooks y filters similar al de WordPress:
+El framework incluye un sistema completo de hooks y filtros 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}`);
@@ -311,203 +146,22 @@ hooks.addFilter('session_create_data', (userData, req) => {
 });
 ```
 
-## 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.
+Las contribuciones son bienvenidas. Por favor, abre un issue o envía un pull request para sugerir cambios o mejoras.
 
 ## 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'
-};
+Este proyecto está licenciado bajo la Apache License 2.0 - ver el archivo LICENSE para más detalles.
 
-const mariaDBAdapter = new MariaDBAdapter(dbConfig);
+## Autor
 
-// 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);
-  }
-}
-```
+JERK Framework Team / Benjamin Sanhez Cardenas
 
-### Uso de Modelos en Controladores con loadModel
+## Repositorio
 
-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();
-```
+GitLab: https://gitlab.com/bytedogssyndicate1/jerk
 
-## Documentación del Framework
+## Soporte
 
-Para una descripción detallada de la arquitectura y componentes del framework, consulta el archivo [JERK_FRAMEWORK_DOCUMENTATION.md](JERK_FRAMEWORK_DOCUMENTATION.md).
+Para soporte, por favor abre un issue en el repositorio o visita nuestra página web: https://jerk.page.gd/