blackcoffee2 2.1.0

package/manuales/CACHE_REGEX_COMMANDS.md

@@ -0,0 +1,136 @@
+# Comandos de Estadísticas de Caché de Expresiones Regulares - Insitu Framework
+
+## Descripción General
+
+El framework Insitu incluye un sistema avanzado de caché para expresiones regulares utilizadas en el enrutamiento de rutas parametrizadas. Este sistema mejora significativamente el rendimiento al evitar la compilación repetida de expresiones regulares.
+
+## Comandos Disponibles
+
+### 1. `cache-stats`
+**Descripción:** Muestra estadísticas generales del sistema de caché, incluyendo información sobre el caché de expresiones regulares.
+
+**Uso:**
+```
+cache-stats
+```
+
+**Salida típica:**
+```
+=== Estadísticas del Caché ===
+- Total de rutas cacheadas: 24
+- Hits de caché: 1,245
+- Misses de caché: 12
+- Ratio de éxito: 99.04%
+- Tamaño del caché: 2.4 KB
+- Rutas dinámicas (con regex): 8
+- Rutas estáticas: 16
+```
+
+### 2. `route-cache`
+**Descripción:** Muestra información específica sobre el caché de rutas, incluyendo las expresiones regulares compiladas y sus patrones.
+
+**Uso:**
+```
+route-cache
+```
+
+**Salida típica:**
+```
+=== Caché de Rutas ===
+Rutas dinámicas cacheadas:
+- GET /users/{id} -> /^\/users\/([^\/]+?)\/?$/ (hits: 45)
+- GET /products/{category}/{id} -> /^\/products\/([^\/]+?)\/([^\/]+?)\/?$/ (hits: 23)
+- POST /api/v{version}/data -> /^\/api\/v([^\/]+?)\/data\/?$/ (hits: 12)
+
+Rutas estáticas cacheadas:
+- GET /static/css/style.css
+- GET /static/js/app.js
+- GET /api/users/list
+```
+
+### 3. `cache-view`
+**Descripción:** Muestra el contenido actual del caché de rutas, incluyendo las expresiones regulares cacheadas.
+
+**Uso:**
+```
+cache-view
+```
+
+**Salida típica:**
+```
+=== Contenido del Caché de Rutas ===
+[EXACT MATCHES]
+GET:/static/css/style.css -> File handler
+GET:/api/users/list -> Controller handler
+
+[RPARAMETRIZED MATCHES]
+GET:/users/{id} -> {
+  regex: /^\/users\/([^\/]+?)\/?$/,
+  params: ["id"],
+  handler: UserController.getById
+}
+GET:/products/{category}/{id} -> {
+  regex: /^\/products\/([^\/]+?)\/([^\/]+?)\/?$/,
+  params: ["category", "id"],
+  handler: ProductController.getByCategoryAndId
+}
+```
+
+### 4. `cache-dynamic`
+**Descripción:** Muestra específicamente las rutas dinámicas y sus expresiones regulares cacheadas.
+
+**Uso:**
+```
+cache-dynamic
+```
+
+**Salida típica:**
+```
+=== Rutas Dinámicas (con Regex) ===
+Total: 8 rutas dinámicas cacheadas
+
+1. GET /users/{id}
+   - Patrón: {id}
+   - Regex: /^\/users\/([^\/]+?)\/?$/
+   - Hits: 45
+   - Último acceso: 2026-02-12 08:45:22
+
+2. POST /api/v{version}/data
+   - Patrón: {version}
+   - Regex: /^\/api\/v([^\/]+?)\/data\/?$/
+   - Hits: 12
+   - Último acceso: 2026-02-12 08:44:15
+
+[... más rutas ...]
+```
+
+## Cómo Conectarse al Servidor de Administración
+
+Para usar estos comandos, debes conectarte al servidor de administración:
+
+### Método 1: Cliente CLI
+```
+node insitu-admin-client.js
+```
+
+### Método 2: Conexión TCP directa
+```
+telnet localhost 9999
+```
+o
+```
+nc localhost 9999
+```
+
+## Interpretación de las Estadísticas
+
+- **Hits**: Número de veces que se utilizó una ruta ya cacheada (bueno para el rendimiento)
+- **Misses**: Número de veces que se tuvo que compilar una nueva expresión regular (menos eficiente)
+- **Ratio de éxito**: Porcentaje de accesos que pudieron usar el caché (idealmente cercano al 100%)
+- **Patrones de regex**: Las expresiones regulares generadas a partir de los patrones de ruta como `{id}`, `{name}`, etc.
+
+## Consejos de Optimización
+
+- Un alto número de "misses" puede indicar que estás usando muchas rutas diferentes que no se benefician del caché
+- Las rutas estáticas (sin parámetros) tienen mejor rendimiento que las dinámicas
+- El sistema de caché de expresiones regulares se activa automáticamente para rutas parametrizadas como `/users/{id}`

package/manuales/CACHE_SYSTEM_MAP.md

@@ -0,0 +1,206 @@
+# Mapa de Procesos de Caché del Framework Insitu
+
+## Introducción
+
+Este documento describe los diferentes sistemas de caché implementados en el framework Insitu 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 Insitu 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.