jerkjs 2.5.6 → 2.6.1

package/doc-2.5/ROUTE_CACHE_MODULE_MANUAL.md

@@ -0,0 +1,205 @@
+# Manual del Módulo de Cache de Rutas para JERK Framework
+
+## Tabla de Contenidos
+1. [Introducción](#introducción)
+2. [Comandos Disponibles](#comandos-disponibles)
+3. [Uso Básico](#uso-básico)
+4. [Uso Avanzado](#uso-avanzado)
+5. [Ejemplos de Uso](#ejemplos-de-uso)
+
+## Introducción
+
+El módulo de Cache de Rutas es una extensión del sistema de administración CLI de JERK Framework que permite monitorear y gestionar el cache de rutas del sistema. Proporciona comandos para ver el estado del cache, visualizar su contenido, y limpiarlo cuando sea necesario.
+
+## Comandos Disponibles
+
+### Comandos Generales de Cache de Rutas
+- `route-cache` o `cache-stats`: Muestra estadísticas del cache de rutas
+- `cache-view`: Muestra el contenido completo del cache de rutas
+- `cache-dynamic`: Muestra solo el cache de rutas dinámicas (parametrizadas)
+- `cache-static`: Muestra solo el cache de rutas estáticas (exactas)
+- `cache-clear`: Limpia todo el cache de rutas
+
+## Uso Básico
+
+### Conectar al Sistema de Administración
+
+Para acceder al módulo de cache de rutas, primero debes conectarte al sistema de administración:
+
+```bash
+telnet localhost 9999
+```
+
+O alternativamente:
+
+```bash
+nc localhost 9999
+```
+
+### Ver estadísticas del cache de rutas
+
+Comando: `route-cache` o `cache-stats`
+
+Este comando muestra estadísticas generales del cache de rutas:
+
+```
+> route-cache
+
+=== Estadísticas del Cache de Rutas ===
+Rutas dinámicas (parametrizadas) en cache: 5
+Rutas estáticas exactas en cache: 10
+Tamaño total de índices: 15
+Índices válidos: Sí
+
+>
+```
+
+### Ver contenido del cache de rutas
+
+Comando: `cache-view`
+
+Este comando muestra el contenido completo del cache de rutas:
+
+```
+> cache-view
+
+=== Contenido del Cache de Rutas ===
+
+--- Rutas Dinámicas (Parametrizadas) en Cache ---
+1. /users/:id -> /^\/users\/([^\/]+?)$/
+2. /posts/:slug -> /^\/posts\/([^\/]+?)$/
+
+--- Rutas Estáticas Exactas en Cache ---
+1. GET /api/users -> anonymous
+2. POST /api/users -> anonymous
+
+>
+```
+
+## Uso Avanzado
+
+### Ver solo cache de rutas dinámicas
+
+Comando: `cache-dynamic`
+
+Muestra únicamente las rutas dinámicas (parametrizadas) en el cache:
+
+```
+> cache-dynamic
+
+=== Cache de Rutas Dinámicas (Parametrizadas) ===
+1. Ruta: /users/:id
+   Regex: /^\/users\/([^\/]+?)$/
+
+2. Ruta: /posts/:slug  
+   Regex: /^\/posts\/([^\/]+?)$/
+
+Total: 2 rutas dinámicas en cache.
+
+>
+```
+
+### Ver solo cache de rutas estáticas
+
+Comando: `cache-static`
+
+Muestra únicamente las rutas estáticas (exactas) en el cache:
+
+```
+> cache-static
+
+=== Cache de Rutas Estáticas (Exactas) ===
+1. GET /api/users
+   Handler: anonymous
+   Static: true
+
+2. POST /api/users
+   Handler: anonymous
+   Static: true
+
+Total: 2 rutas estáticas en cache.
+
+>
+```
+
+### Limpiar el cache de rutas
+
+Comando: `cache-clear`
+
+Elimina todas las entradas del cache de rutas:
+
+```
+> cache-clear
+
+=== Limpieza del Cache de Rutas ===
+Rutas dinámicas eliminadas: 5
+Rutas estáticas eliminadas: 10
+Cache de rutas limpiado exitosamente.
+
+>
+```
+
+## Ejemplos de Uso
+
+### Ejemplo 1: Diagnóstico de rendimiento
+
+Para diagnosticar problemas de rendimiento relacionados con el cache de rutas:
+
+```
+> route-cache
+Rutas dinámicas (parametrizadas) en cache: 50
+Rutas estáticas exactas en cache: 100
+Tamaño total de índices: 150
+Índices válidos: Sí
+
+> cache-dynamic
+[Detalles de las 50 rutas dinámicas en cache]
+>
+```
+
+### Ejemplo 2: Verificación de rutas parametrizadas
+
+Para verificar específicamente las rutas parametrizadas en el cache:
+
+```
+> cache-dynamic
+=== Cache de Rutas Dinámicas (Parametrizadas) ===
+1. Ruta: /users/:id
+   Regex: /^\/users\/([^\/]+?)$/
+   
+2. Ruta: /products/:category/:id
+   Regex: /^\/products\/([^\/]+?)\/([^\/]+?)$/
+   
+Total: 2 rutas dinámicas en cache.
+
+>
+```
+
+## Solución de Problemas
+
+### Problema: Comando no reconocido
+
+**Síntoma**: El sistema responde con "Comando desconocido para el módulo de cache de rutas"
+
+**Solución**: Verifica que estás usando uno de los comandos válidos: `route-cache`, `cache-stats`, `cache-view`, `cache-dynamic`, `cache-static`, `cache-clear`
+
+### Problema: No se encuentra el componente RouteMatcher
+
+**Síntoma**: El sistema responde con "No se encontró el componente RouteMatcher"
+
+**Solución**: Asegúrate de que el servidor esté completamente iniciado y que el componente RouteMatcher haya sido correctamente instanciado.
+
+## Compatibilidad
+
+- **Versión mínima del framework**: JERK 2.5.8
+- **Puerto de administración**: Por defecto 9999 (configurable)
+- **Acceso**: Solo desde localhost por razones de seguridad
+- **Protocolo**: Conexión TCP con interfaz de línea de comandos
+
+## Autor
+
+JERK Framework Team
+
+## Versión
+
+v2.6.0

package/doc-2.5/WAF_MODULE_MANUAL.md

@@ -0,0 +1,229 @@
+# Manual del Módulo WAF (Web Application Firewall) para JERK Framework
+
+## Tabla de Contenidos
+1. [Introducción](#introducción)
+2. [Características del WAF](#características-del-waf)
+3. [Comandos Disponibles](#comandos-disponibles)
+4. [Estadísticas del Servidor](#estadísticas-del-servidor)
+5. [Gestión de Reglas X-Headers](#gestión-de-reglas-x-headers)
+6. [Listas de IPs](#listas-de-ips)
+7. [Persistencia de Reglas](#persistencia-de-reglas)
+8. [Ejemplos de Uso](#ejemplos-de-uso)
+
+## Introducción
+
+El módulo WAF (Web Application Firewall) es una extensión de la extensión de administración de JERK Framework que permite monitorear, gestionar y proteger tu aplicación web. Proporciona estadísticas en tiempo real, gestión de reglas de seguridad y control de acceso basado en headers X-.
+
+## Características del WAF
+
+- **Estadísticas en tiempo real**: Conteo de solicitudes procesadas y respuestas enviadas con medición en kilobytes
+- **Monitoreo de tráfico**: Registro de accesos a rutas y endpoints
+- **Sistema de reglas X-Headers**: Bloqueo basado en headers como X-Forwarded-For, X-Real-IP, etc.
+- **Listas de IPs**: Sistema de whitelist (nunca bloqueadas) y blacklist (siempre bloqueadas)
+- **Persistencia**: Guardado y carga de reglas de seguridad
+- **Interfaz interactiva**: Sistema de comandos para gestión en tiempo real
+
+## Comandos Disponibles
+
+### Comandos Generales de Estadísticas
+- `waf-status` o `waf-stats`: Muestra estadísticas generales del servidor
+- `waf-blocked` o `waf-security`: Muestra estadísticas de seguridad
+- `waf-x-headers`: Muestra reglas de headers X- configuradas
+
+### Comandos de Gestión de Reglas
+- `create-x-rule`: Crea una nueva regla de seguridad basada en headers X-
+- `remove-x-rule`: Remueve una regla de seguridad existente
+- `save-rules`: Guarda todas las reglas a un archivo
+- `load-rules`: Carga reglas desde un archivo
+
+### Comandos de Gestión de IPs
+- `waf-block-ip`: Bloquea temporalmente una IP
+- `waf-unblock-ip`: Desbloquea una IP temporalmente bloqueada
+- `waf-whitelist`: Agrega una IP a la lista blanca
+- `waf-blacklist`: Agrega una IP a la lista negra
+
+## Estadísticas del Servidor
+
+### waf-status / waf-stats
+Muestra las estadísticas generales del servidor:
+
+```
+=== Estadísticas del WAF ===
+Solicitudes procesadas: 15
+Solicitudes procesadas (KB): 2.45 KB
+Respuestas enviadas: 15
+Respuestas enviadas (KB): 15.67 KB
+IPs en lista blanca: 2
+IPs en lista negra: 1
+Reglas de seguridad activas: 3
+```
+
+### Campos de Estadísticas
+- **Solicitudes procesadas**: Número total de solicitudes HTTP procesadas
+- **Solicitudes procesadas (KB)**: Cantidad total de datos recibidos en kilobytes
+- **Respuestas enviadas**: Número total de respuestas HTTP enviadas
+- **Respuestas enviadas (KB)**: Cantidad total de datos enviados en kilobytes
+- **IPs en lista blanca**: Número de IPs que nunca serán bloqueadas
+- **IPs en lista negra**: Número de IPs que siempre serán bloqueadas
+- **Reglas de seguridad activas**: Número de reglas de seguridad activas
+
+## Gestión de Reglas X-Headers
+
+### Crear Regla (`create-x-rule`)
+Proceso interactivo para crear reglas de seguridad basadas en headers X-:
+
+1. **Nombre del header**: Introduce el nombre del header X- (ej: X-Forwarded-For, X-Real-IP)
+2. **Patrón**: Introduce el patrón para coincidir (cadena o expresión regular)
+3. **Acción**: Selecciona la acción a tomar:
+   - `1` o `block`: Bloquear solicitudes que coincidan
+   - `2` o `log`: Registrar solicitudes que coincidan
+   - `3` o `monitor`: Monitorear solicitudes que coincidan
+4. **Razón**: Introduce la razón para la regla (opcional)
+
+### Remover Regla (`remove-x-rule`)
+Proceso interactivo para remover reglas existentes:
+1. Se muestra una lista numerada de reglas disponibles
+2. Introduce el número de la regla que deseas remover
+3. La regla se elimina inmediatamente del sistema
+
+## Listas de IPs
+
+### Whitelist (`waf-whitelist`)
+Agrega una IP a la lista blanca (nunca será bloqueada):
+
+```
+> waf-whitelist
+Introduce la IP a agregar a la lista blanca (ej: 192.168.1.100):
+> 192.168.1.100
+IP 192.168.1.100 agregada a la lista blanca.
+```
+
+### Blacklist (`waf-blacklist`)
+Agrega una IP a la lista negra (siempre será bloqueada):
+
+```
+> waf-blacklist
+Introduce la IP a agregar a la lista negra (ej: 10.0.0.100):
+> 10.0.0.100
+IP 10.0.0.100 agregada a la lista negra.
+```
+
+### Bloqueo Temporal (`waf-block-ip`)
+Bloquea temporalmente una IP:
+
+```
+> waf-block-ip
+Introduce la IP a bloquear temporalmente (ej: 192.168.1.100):
+> 192.168.1.200
+IP 192.168.1.200 bloqueada temporalmente.
+```
+
+## Persistencia de Reglas
+
+### Guardar Reglas (`save-rules`)
+Guarda todas las reglas de seguridad actuales a un archivo JSON:
+
+```
+> save-rules
+✅ Reglas guardadas exitosamente en: /path/to/waf-rules/waf-rules-timestamp.json
+Total de reglas guardadas: 3
+```
+
+### Cargar Reglas (`load-rules`)
+Carga reglas de seguridad desde un archivo JSON:
+
+```
+> load-rules
+=== Archivos de Reglas Disponibles ===
+1. waf-rules-1770795262452.json
+
+Introduce el número del archivo a cargar (o "cancel" para cancelar):
+> 1
+
+¿Deseas reemplazar las reglas actuales? (sí/no):
+> sí
+
+✅ Reglas cargadas exitosamente desde: /path/to/waf-rules/waf-rules-1770795262452.json
+Total de reglas cargadas: 3
+```
+
+## Ejemplos de Uso
+
+### Ejemplo 1: Crear Regla para Bloquear IPs Internas
+```
+> create-x-rule
+=== Crear Regla de Header X- ===
+Introduce el nombre del header X- (ej: X-Forwarded-For, X-Real-IP):
+> X-Forwarded-For
+Header seleccionado: X-Forwarded-For
+Introduce el patrón para coincidir (cadena o expresión regular):
+> 192.168.
+Selecciona la acción a tomar:
+1. block - Bloquear solicitudes que coincidan
+2. log - Registrar solicitudes que coincidan
+3. monitor - Monitorear solicitudes que coincidan
+Escribe el número o el nombre de la acción:
+> 1
+Acción seleccionada: block
+Introduce la razón para la regla (opcional):
+> Bloquear IPs internas
+✅ Regla de header X- creada exitosamente:
+  ID: xheader_x_forwarded_for_1770792842636
+  Header: x-forwarded-for
+  Patrón: 192.168.
+  Acción: block
+  Razón: Bloquear IPs internas
+```
+
+### Ejemplo 2: Ver Estadísticas de Seguridad
+```
+> waf-security
+=== Estadísticas de Seguridad del WAF ===
+IPs bloqueadas temporalmente: 2
+Intentos de ataque detectados: 5
+Tipos de ataques detectados: 3
+Registros de seguridad: 10
+
+Accesos a rutas (Input/Output):
+  GET /: 8 accesos
+  POST /api/users: 3 accesos
+  GET /api/users: 4 accesos
+
+Endpoints más accedidos:
+  GET /: 8 hits
+  GET /api/users: 4 hits
+  POST /api/users: 3 hits
+```
+
+### Ejemplo 3: Agregar IP a Lista Negra
+```
+> waf-blacklist
+Introduce la IP a agregar a la lista negra (ej: 10.0.0.100):
+> 10.0.0.100
+IP 10.0.0.100 agregada a la lista negra.
+```
+
+## Consideraciones de Seguridad
+
+- El servidor de administración solo escucha en localhost (127.0.0.1) por defecto
+- Todas las operaciones de bloqueo son inmediatas y afectan al sistema en tiempo real
+- Las reglas de seguridad se aplican antes de que la solicitud llegue a los controladores
+- El sistema de persistencia permite mantener reglas entre reinicios del servidor
+
+## Solución de Problemas
+
+### Las estadísticas no se actualizan
+- Verifica que el middleware de firewall esté activo en tu servidor
+- Asegúrate de que las solicitudes estén pasando por el sistema de firewall
+
+### Las reglas no se aplican
+- Verifica que el firewall esté correctamente integrado en tu pipeline de middlewares
+- Confirma que las reglas se hayan creado correctamente usando `waf-x-headers`
+
+## Autor
+
+JERK Framework Team
+
+## Versión
+
+v2.5.8

package/index.js

@@ -1,6 +1,6 @@
 /**
  * Punto de entrada del framework JERK
- * JERK Framework 2.5.1
+ * JERK Framework 2.5.8
  */
 
 // Mostrar mensaje de versión al iniciar
@@ -48,10 +48,18 @@ 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
 
+// Componentes de sistema de colas (v2.6.0)
+const QueueSystem = require('./lib/queue/QueueSystem');
+const QueueIntegration = require('./lib/queue/integration');
+
 
 // Exportar todos los componentes del framework
 module.exports = {
@@ -97,7 +105,7 @@ module.exports = {
   // Componentes de modelo (v2.4.0)
   ModelBase,
   ModelManager,
-  // Componentes del QueryBuilder (v2.3.0) 
+  // Componentes del QueryBuilder (v2.3.0)
   QueryBuilder,
   UserModel,
 
@@ -113,7 +121,14 @@ module.exports = {
   ErrorHandler,
   ValidationError,
   AuthenticationError,
-  DatabaseError
+  DatabaseError,
+
+  // Componentes de sistema de colas (v2.6.0)
+  QueueSystem,
+  QueueIntegration,
+
+  // Componentes de administración (v2.5.7)
+  AdminExtension: require('./lib/admin/AdminExtension')
 };
 
 // También exportar clases individuales por conveniencia
@@ -124,4 +139,4 @@ const hooksInstance = new HookSystem();
 module.exports.hooks = hooksInstance;
 
 // Disparar hooks de inicio del framework
-hooksInstance.doAction('framework_init');
+hooksInstance.doAction('framework_init');

package/jerk-admin-client/README.md

@@ -0,0 +1,69 @@
+# Cliente CLI para JERK Framework Administration Server
+
+Cliente de línea de comandos para interactuar con el servidor de administración de JERK Framework. Permite reutilizar comandos y cuenta con autocompletado.
+
+## Características
+
+- **Autocompletado**: Presiona TAB para autocompletar comandos conocidos
+- **Historial de comandos**: Accede a comandos previamente utilizados
+- **Reutilización de comandos**: Reutiliza comandos por número o por texto
+- **Conservación de contexto**: Mantiene el historial entre sesiones
+
+## Instalación
+
+El cliente CLI está incluido en el framework JERK y se puede ejecutar directamente:
+
+```bash
+node jerk-admin-client.js
+```
+
+O con parámetros específicos:
+
+```bash
+node jerk-admin-client.js --host 127.0.0.1 --port 9999
+```
+
+## Comandos del Cliente
+
+Además de los comandos del servidor de administración, el cliente CLI incluye comandos especiales:
+
+- `history` - Muestra el historial de comandos
+- `clear` - Limpia la pantalla
+- `re <número>` - Reutiliza el comando número n del historial
+- `re <texto>` - Reutiliza el último comando que contiene el texto
+- `help-cli` - Muestra la ayuda del cliente
+
+## Uso
+
+1. Inicia el cliente:
+```bash
+node jerk-admin-client.js
+```
+
+2. El cliente se conectará automáticamente al servidor de administración en `localhost:9999`
+
+3. Usa los comandos estándar del servidor de administración:
+   - `stats` - Ver estadísticas generales
+   - `requests` - Ver estadísticas de solicitudes
+   - `endpoints` - Ver endpoints más accedidos
+   - `routes` - Ver rutas registradas
+   - `help` - Ver todos los comandos disponibles
+
+4. Usa los comandos especiales del cliente para mejorar la experiencia:
+   - `history` para ver comandos anteriores
+   - `re 3` para reutilizar el tercer comando del historial
+   - `re stats` para reutilizar el último comando que contenía "stats"
+
+## Atajos
+
+- Presiona `↑` y `↓` para navegar por el historial de comandos
+- Presiona `TAB` para autocompletar comandos
+- Presiona `Ctrl+C` para salir del cliente
+
+## Configuración
+
+Por defecto, el cliente intenta conectarse a `localhost:9999`. Puedes especificar un host y puerto diferente usando los argumentos `--host` y `--port`.
+
+## Archivo de Historial
+
+El cliente guarda el historial de comandos en `~/.jerk_admin_history` para conservarlo entre sesiones.

package/jerk-admin-client/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jerkjs/admin-client",
+  "version": "1.0.0",
+  "description": "Cliente CLI para interactuar con el servidor de administración de JERK Framework",
+  "main": "jerk-admin-client.js",
+  "bin": {
+    "jerk-admin": "./jerk-admin-client.js"
+  },
+  "scripts": {
+    "start": "node jerk-admin-client.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "jerkjs",
+    "admin",
+    "cli",
+    "client",
+    "framework"
+  ],
+  "author": "JERK Framework Team",
+  "license": "Apache-2.0",
+  "dependencies": {}
+}