jerkjs 2.5.4 → 2.5.8

package/docs/CACHE_SYSTEM_MAP.md

@@ -0,0 +1,206 @@
+# Mapa de Procesos de Caché del Framework JERK
+
+## Introducción
+
+Este documento describe los diferentes sistemas de caché implementados en el framework JERK y cómo se integran en los flujos del sistema.
+
+## Sistemas de Caché
+
+### 1. Caché de Expresiones Regulares para Rutas (RouteMatcher)
+
+**Ubicación**: `lib/router/RouteMatcher.js`
+**Tipo**: Mapa de caché (Map)
+**Propósito**: Almacenar expresiones regulares compiladas para rutas parametrizadas
+**Clave**: Ruta con parámetros (ej. `/users/:id`)
+**Valor**: Expresión regular compilada
+**Flujo de proceso**:
+1. Al procesar una ruta parametrizada, se convierte a expresión regular
+2. Antes de compilar, se verifica si ya existe en el cache
+3. Si existe, se devuelve la expresión regular cacheada
+4. Si no existe, se compila, se almacena en cache y se devuelve
+
+**Beneficios**:
+- Evita compilación repetida de expresiones regulares
+- Mejora el rendimiento de coincidencia de rutas parametrizadas
+- Reduce el uso de CPU en operaciones repetidas
+
+### 2. Caché de Vistas (ViewEngine)
+
+**Ubicación**: `lib/mvc/viewEngine.js`
+**Tipo**: Mapa de caché (Map)
+**Propósito**: Almacenar contenido de vistas ya procesadas (sin variables)
+**Clave**: Ruta completa del archivo de vista
+**Valor**: Contenido de la vista procesado (condiciones, bucles, etc. resueltos)
+**Flujo de proceso**:
+1. Al solicitar una vista, se verifica si está en cache
+2. Si está en cache, se procesa con las variables y se devuelve
+3. Si no está en cache, se lee el archivo, se procesa (condiciones, bucles, etc.)
+4. Si el cache está habilitado, se almacena la vista procesada (sin variables)
+5. Se procesan las variables y se devuelve el resultado
+
+**Beneficios**:
+- Evita lectura repetida de archivos de vistas
+- Evita procesamiento repetido de condiciones y bucles
+- Mejora el rendimiento de renderizado de vistas
+
+### 3. Caché de Controladores (ControllerLoader)
+
+**Ubicación**: `lib/loader/controllerLoader.js`
+**Tipo**: Sistema de caché de módulos de Node.js
+**Propósito**: Evitar recarga repetida de módulos de controladores
+**Clave**: Ruta del archivo del controlador
+**Valor**: Instancia del módulo del controlador
+**Flujo de proceso**:
+1. Al cargar un controlador, se verifica si ya está en el cache de require
+2. Si no está en cache, se carga y se mantiene en require.cache
+3. En subsiguientes solicitudes, se devuelve la instancia cacheada
+
+**Beneficios**:
+- Evita recarga repetida de módulos
+- Mejora el rendimiento de carga de controladores
+- Reduce el uso de memoria
+
+### 4. Índices de Rutas (RouteMatcher)
+
+**Ubicación**: `lib/router/RouteMatcher.js`
+**Tipo**: Mapas de índices y estructuras de datos
+**Propósito**: Optimizar la búsqueda de rutas mediante pre-filtrado
+**Componentes**:
+- `exactRoutes`: Mapa de rutas exactas por método y path
+- `routeBuckets`: Estructura jerárquica por método, número de segmentos y primer segmento
+- `indexesValid`: Bandera para validar si los índices están actualizados
+
+**Flujo de proceso**:
+1. Al registrar rutas, se actualizan los índices
+2. Al buscar una ruta, se usan los índices para pre-filtrar candidatos
+3. Se buscan coincidencias exactas primero (más rápido)
+4. Se buscan rutas parametrizadas solo entre candidatos filtrados
+5. Se buscan rutas estáticas por prefijo entre candidatos filtrados
+
+**Beneficios**:
+- Reduce drásticamente el número de rutas a evaluar
+- Mejora el rendimiento de coincidencia de rutas
+- Escala mejor con un gran número de rutas
+
+## Flujos de Integración de Caché
+
+### Flujo de Procesamiento de Solicitudes
+
+```
+Solicitud HTTP
+    ↓
+Middleware de seguridad
+    ↓
+Verificación de índices de rutas (RouteMatcher)
+    ↓
+→ Búsqueda por ruta exacta (más rápida)
+    ↓
+→ Pre-filtrado por número de segmentos y primer segmento
+    ↓
+→ Búsqueda en rutas candidatas
+    ↓
+→ Coincidencia con expresiones regulares (usando cache)
+    ↓
+Ejecución del handler de la ruta
+    ↓
+Renderizado de vista (usando cache de vistas)
+    ↓
+Respuesta HTTP
+```
+
+### Flujo de Caché de Expresiones Regulares
+
+```
+Solicitud de coincidencia de ruta parametrizada
+    ↓
+→ ¿Está la expresión regular en cache?
+    ↓
+┌─────────────┬─────────────┐
+│     SÍ      │     NO      │
+│             │             │
+│ Devolver    │ Compilar    │
+│ regex       │ expresión   │
+│ cacheada    │ regular     │
+│             │             │
+└─────────────┴─────────────┘
+    ↓
+Almacenar en cache
+    ↓
+Usar para coincidencia
+```
+
+### Flujo de Caché de Vistas
+
+```
+Solicitud de renderizado de vista
+    ↓
+→ ¿Está la vista en cache?
+    ↓
+┌─────────────┬─────────────┐
+│     SÍ      │     NO      │
+│             │             │
+│ Procesar    │ Leer archivo│
+│ con vars    │ de vista    │
+│             │             │
+│ Devolver    │ Procesar    │
+│ resultado   │ condiciónes,│
+│             │ bucles, etc.│
+│             │             │
+│             │ → ¿Cache    │
+│             │   habilitado?│
+│             │      ↓      │
+│             │   ┌─────────┼─┐
+│             │   │   SÍ    │ │
+│             │   │         │ │
+│             │   │ Almacenar││
+│             │   │ vista en ││
+│             │   │ cache    ││
+│             │   └─────────┼─┘
+│             │             │
+└─────────────┴─────────────┘
+    ↓
+Devolver HTML renderizado
+```
+
+## Estrategias de Invalidación de Caché
+
+### Caché de Expresiones Regulares
+- No requiere invalidación frecuente
+- Se actualiza automáticamente al cambiar las rutas
+
+### Caché de Vistas
+- Se puede limpiar manualmente con `viewEngine.clearCache()`
+- No se invalida automáticamente (diseñado para vistas estáticas)
+
+### Caché de Controladores
+- Se mantiene durante todo el ciclo de vida del proceso
+- Se puede limpiar manualmente eliminando del `require.cache`
+
+### Índices de Rutas
+- Se actualizan automáticamente al registrar nuevas rutas
+- Se invalidan si cambia el número total de rutas
+
+## Beneficios del Sistema de Caché
+
+1. **Mejora de Rendimiento**: Reducción significativa de operaciones repetidas
+2. **Eficiencia de CPU**: Menos compilación de expresiones regulares y procesamiento de vistas
+3. **Eficiencia de I/O**: Menos lecturas de disco para archivos de vistas
+4. **Escalabilidad**: Mejor manejo de alto volumen de solicitudes
+5. **Optimización de Memoria**: Reutilización de estructuras de datos ya procesadas
+
+## Consideraciones de Seguridad
+
+- Las cachés no almacenan datos sensibles de usuarios
+- Las expresiones regulares cacheadas no contienen información de entrada del usuario
+- Las vistas cacheadas no contienen datos de sesión o variables de usuario
+- El sistema de caché no expone información interna del sistema
+
+## Conclusión
+
+El framework JERK implementa múltiples niveles de caché para optimizar el rendimiento:
+- Caché de expresiones regulares para rutas parametrizadas
+- Caché de vistas procesadas
+- Índices optimizados para búsqueda de rutas
+- Caché de módulos de controladores
+
+Estos sistemas de caché trabajan juntos para proporcionar un rendimiento óptimo al minimizar operaciones repetidas y maximizar la eficiencia del procesamiento de solicitudes.

package/docs/SERVER_OPTIMIZATION_NOTES.md

@@ -0,0 +1,87 @@
+# Optimización del Servidor APIServer
+
+## Problemas de Rendimiento Identificados
+
+### 1. Carga Repetida de Módulos
+**Problema**: Varias líneas contienen `require()` dentro de funciones que se ejecutan en cada solicitud:
+```javascript
+const hooks = require('../../index.js').hooks;
+```
+
+**Solución**: Cargar módulos en la parte superior del archivo o en el constructor para evitar cargas repetidas.
+
+### 2. Operaciones Síncronas Costosas
+**Problema**: Lectura de archivos con `fs.readFileSync()` en el constructor:
+```javascript
+key: fs.readFileSync(options.key),
+cert: fs.readFileSync(options.cert)
+```
+
+**Solución**: Usar versiones asíncronas o cargar certificados en tiempo de inicio.
+
+### 3. Normalización de Rutas Repetida
+**Problema**: Varias operaciones de `path.normalize()` y `path.resolve()` repetidas en el mismo flujo de ejecución.
+
+**Solución**: Realizar estas operaciones una sola vez y reutilizar los resultados.
+
+### 4. Callbacks Anidados
+**Problema**: Código con callbacks anidados en el manejo de autenticación que puede afectar el rendimiento.
+
+**Solución**: Convertir a promesas o usar async/await para mejor manejo del flujo.
+
+## Posibles Optimizaciones
+
+### 1. Carga de Módulos en el Constructor
+```javascript
+// En lugar de:
+const hooks = require('../../index.js').hooks;
+
+// Hacer en la parte superior del archivo o en el constructor:
+const { hooks } = require('../../index.js');
+const { Logger } = require('../utils/logger');
+const { ErrorHandler } = require('../utils/errorHandler');
+const { getMimeType } = require('../utils/mimeType');
+```
+
+### 2. Caché de Rutas
+Implementar un sistema de caché para rutas frecuentes para evitar recalcular coincidencias repetidamente.
+
+### 3. Pool de Conexiones
+Implementar un pool de conexiones para reutilizar conexiones HTTP/HTTPS.
+
+### 4. Lazy Loading de Controladores
+Cargar controladores solo cuando se necesiten, no en cada solicitud.
+
+### 5. Optimización de Middleware
+Implementar un sistema más eficiente para la ejecución de middlewares, posiblemente con un pipeline optimizado.
+
+## Código Potencialmente Problemático
+
+### En el método createStaticFileHandler:
+- Múltiples llamadas a `fs.promises.stat()` y `fs.promises.access()`
+- Posible mejora: usar `fs.promises.realpath()` para validar rutas y prevenir traversal
+
+### En el manejo de autenticación:
+- Callbacks anidados que pueden ralentizar el flujo
+- Creación de nuevas funciones en cada solicitud
+
+## Recomendaciones de Implementación
+
+1. **Memoización**: Implementar memoización para rutas y resultados de autenticación frecuentes
+2. **Buffer Pool**: Usar buffer pools para manejar grandes volúmenes de solicitudes
+3. **Event Loop Optimization**: Evitar operaciones bloqueantes en el event loop
+4. **Streaming**: Usar streams para grandes volúmenes de datos en lugar de cargar todo en memoria
+5. **Connection Pooling**: Implementar pooling de conexiones para mejorar el rendimiento concurrente
+
+## Métricas de Rendimiento
+
+Considerar implementar métricas para monitorear:
+- Tiempo de respuesta promedio
+- Uso de memoria
+- Número de solicitudes por segundo
+- Tiempo de procesamiento de rutas
+- Uso de CPU
+
+## Conclusión
+
+Optimizar el servidor APIServer puede mejorar significativamente el rendimiento de aplicaciones que usan el framework JERK, especialmente en entornos de alta concurrencia. Las optimizaciones deben enfocarse en reducir operaciones costosas, mejorar el manejo de recursos y optimizar el flujo de ejecución.

package/index.js

@@ -48,6 +48,9 @@ const ModelControllerExample = require('./lib/mvc/ModelControllerExample');
 
 // Componentes de manejo de errores
 const { ErrorHandler, ValidationError, AuthenticationError, DatabaseError } = require('./lib/utils/errorHandler');
+
+// Componentes de caché
+const CacheHooks = require('./lib/cache/CacheHooks');
 // Componentes del QueryBuilder (v2.3.0) - MODIFICADO PARA USAR QBUILDERJS
 const QueryBuilder = require('qbuilderjs');
 // No hay middleware ni hooks ya que se eliminó la implementación interna
@@ -113,7 +116,10 @@ module.exports = {
   ErrorHandler,
   ValidationError,
   AuthenticationError,
-  DatabaseError
+  DatabaseError,
+
+  // Componentes de administración (v2.5.7)
+  AdminExtension: require('./lib/admin/AdminExtension')
 };
 
 // También exportar clases individuales por conveniencia