jerkjs 2.2.0 → 2.3.0

package/README_PT.md

@@ -0,0 +1,230 @@
+# JERK Framework v2.3.0
+
+![JERK Framework Logo](jerk.jpg)
+
+**Novo no JERK? Comece seu projeto rapidamente com nosso Kit Inicial**
+
+Nosso Kit Inicial em `@standard/server.js` é a forma mais rápida de começar com o JERK. Ele vem com todas as funcionalidades do framework já configuradas, permitindo que você se concentre em desenvolver sua aplicação em vez de configurar infraestrutura.
+
+**Recursos do Kit Inicial:**
+- Configuração pronta para uso com todos os componentes principais
+- Carregamento de rotas a partir de arquivo JSON (`routes.json`)
+- Sistema de controladores pré-configurado
+- Middlewares essenciais já integrados (autenticação, CORS, compressão, firewall, etc.)
+- Sistema de logging e tratamento de erros implementado
+
+**Como começar:**
+1. Edite o arquivo `routes.json` para definir suas rotas e associá-las aos seus controladores
+
+Exemplo 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. Crie seus controladores de acordo com as rotas definidas
+
+Por exemplo, para a rota principal "/", crie um arquivo `HomeController.js`:
+```javascript
+class HomeController {
+  index(req, res) {
+    res.render('index.html', { data: 'Olá' });
+  }
+}
+
+module.exports = new HomeController();
+```
+
+3. Sua aplicação está pronta para usar!
+
+O Kit Inicial inclui controladores de exemplo para que você possa ver como o sistema funciona.
+
+Visite nosso site: https://jerk.page.gd/
+Repositório oficial: https://gitlab.com/bytedogssyndicate1/jerk/
+
+## Recursos
+
+- **Arquitetura Modular**: Componentes independentes para maior flexibilidade
+- **Segurança Avançada**: Firewall integrado (WAF) com detecção de ataques
+- **Sistema de Hooks**: Semelhante ao sistema do WordPress para extensibilidade
+- **Autenticação Flexível**: Suporte para JWT, API Keys, Basic Auth, OAuth2, OpenID Connect
+- **Armazenamento de Tokens**: Suporte para memória, JSON, SQLite e MariaDB
+- **Roteamento Avançado**: Suporte para rotas parametrizadas e aninhadas
+- **Suporte para Frontend**: Capacidade de servir conteúdo HTML e outros tipos de conteúdo
+- **Configuração de Content-Type**: Especificação de cabeçalhos Content-Type em routes.json
+- **Middlewares Integrados**: CORS, limitação de taxa, compressão, firewall, etc.
+- **Gerenciamento de Controladores**: Carregamento dinâmico de controladores a partir de arquivos
+- **Carregamento de Rotas**: Definição de rotas a partir de arquivos JSON
+- **Sistema de Sessões**: Gerenciamento completo de sessões com suporte para autenticação
+- **Mecanismo de Templates MVC**: Sistema profissional de visualização com suporte para filtros, helpers e hooks
+- **Extensibilidade**: Sistema de hooks e filtros para personalização
+
+## Instalação
+
+```bash
+npm install jerkjs
+```
+
+## Uso Básico
+
+```javascript
+const { APIServer, Router, Logger } = require('jerkjs');
+
+// Criar instância do servidor
+const server = new APIServer({
+  port: 3000,
+  host: 'localhost'
+});
+
+// Criar instância do logger
+const logger = new Logger({ level: 'info' });
+
+// Definir rotas
+server.addRoute('GET', '/', (req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ message: 'Olá Mundo!' }));
+});
+
+// Iniciar o servidor
+server.start();
+```
+
+## Componentes Principais
+
+### APIServer
+Servidor HTTP/HTTPS básico com suporte para rotas parametrizadas, middlewares e configuração avançada.
+
+### Router
+Sistema de roteamento avançado com suporte para rotas aninhadas e prefixos.
+
+### Authenticator
+Middleware de autenticação com suporte para múltiplos métodos (JWT, API Keys, Basic Auth, OAuth2, OpenID Connect).
+
+### SecurityEnhancedServer
+Servidor com recursos de segurança avançada (WAF) integrados.
+
+### RouteLoader
+Carregamento de rotas a partir de arquivos JSON com suporte para autenticação, controladores e especificação de tipo de conteúdo.
+
+### TokenManager
+Gerenciamento de tokens JWT com diferentes tipos de armazenamento (memória, JSON, SQLite, MariaDB).
+
+### Firewall
+Middleware de firewall com detecção de padrões de ataque e listas brancas/negras.
+
+### Sistema de Hooks
+Sistema de hooks e filtros semelhante ao WordPress para extensibilidade.
+
+### SessionManager
+Sistema completo de gerenciamento de sessões com suporte para autenticação baseada em sessões.
+
+### ViewEngine
+Mecanismo de templates profissional com suporte para filtros, helpers, condições, loops e hooks.
+
+### ControllerBase
+Controlador base que facilita o desenvolvimento de controladores MVC com suporte para visualizações.
+
+## Segurança
+
+O framework inclui múltiplas camadas de segurança:
+
+- **Web Application Firewall (WAF)**: Detecção de injeção SQL, XSS, travessia de caminho, etc.
+- **Limitação de Taxa**: Limitação de requisições por IP ou usuário
+- **Firewall**: Bloqueio automático por tentativas falhas
+- **Listas Brancas/Negras**: Controle de acesso por IP
+- **Auditoria de Segurança**: Registro de eventos de segurança
+- **Autenticação Robusta**: Suporte para múltiplos métodos de autenticação
+
+## Sistema de Hooks
+
+O framework inclui um sistema de hooks e filtros semelhante ao WordPress:
+
+```javascript
+const { hooks } = require('jerkjs');
+
+// Registrar uma ação
+hooks.addAction('firewall_request_blocked', (rule, clientIP, req, res) => {
+  console.log(`Solicitação bloqueada: ${rule.name} para IP: ${clientIP}`);
+});
+
+// Registrar um filtro
+hooks.addFilter('session_create_data', (userData, req) => {
+  return {
+    ...userData,
+    ipAddress: req.headers['x-forwarded-for'] || req.connection.remoteAddress,
+    createdAt: new Date().toISOString()
+  };
+});
+```
+
+## Mecanismo de Templates MVC
+
+O framework inclui um mecanismo de templates profissional com suporte para:
+
+- Variáveis: `{{variable}}`
+- Condições: `{{if variable}}conteúdo{{endif}}`
+- Loops: `{{foreach:array}}conteúdo{{endforeach}}`
+- Inclusões: `{{include:header}}`
+- Filtros: `{{variable|upper}}`
+- Helpers personalizados
+
+## Gerenciamento de Sessões
+
+O framework inclui um sistema completo de gerenciamento de sessões:
+
+```javascript
+const { SessionManager } = require('jerkjs');
+
+const sessionManager = new SessionManager({
+  secret: 'your-session-secret',
+  timeout: 3600000 // 1 hora
+});
+
+// Usar como middleware
+server.use(sessionManager.middleware());
+```
+
+## Exemplos
+
+O projeto inclui vários exemplos completos:
+
+- **v2_json_auth**: Autenticação JWT com tokens armazenados em JSON
+- **v2_mariadb_auth**: Autenticação JWT com tokens armazenados em MariaDB
+- **v2_sqlite_auth**: Autenticação JWT com tokens armazenados em SQLite
+- **public**: API pública de exemplo com CORS e limitação de taxa
+- **frontend**: Exemplo de servidor que combina API e frontend com diferentes tipos de conteúdo
+- **hooks**: Exemplo avançado de uso do sistema de hooks com logging e rastreamento de solicitações
+
+Para ver os exemplos completos, visite os diretórios `v2examplle/` e `examples/`.
+
+## Documentação
+
+Além da documentação no README, o projeto inclui documentação adicional:
+
+- **Guia de início rápido**: `docs/guia_inicio_rapido_jerkjs.md` - Um guia completo para começar rapidamente com o JERKJS, incluindo formatos de arquivos, estrutura de controladores, mecanismo de templates e sistema de hooks.
+
+## Contribuições
+
+As contribuições são bem-vindas. Por favor, abra uma issue ou envie um pull request no GitLab.
+
+## Licença
+
+Apache 2.0
+
+## Documentação do Framework
+
+Para uma descrição detalhada da arquitetura e componentes do framework, consulte o arquivo [JERK_FRAMEWORK_DOCUMENTATION.md](JERK_FRAMEWORK_DOCUMENTATION.md).

package/docs/ARQUITECTURA_ROUTES.md

@@ -0,0 +1,186 @@
+# Arquitectura del Sistema de Rutas en JERK Framework
+
+## Descripción General
+
+El sistema de rutas en JERK Framework permite definir endpoints de API mediante dos métodos principales:
+1. Archivo JSON (`routes.json`) - Carga masiva de rutas
+2. Método `addRoute()` - Definición individual de rutas
+
+## Componentes Principales
+
+### 1. APIServer (lib/core/server.js)
+
+Componente principal que gestiona las rutas y el ciclo de vida de la solicitud HTTP.
+
+**Características:**
+- Almacena rutas en el array `this.routes`
+- Implementa el método `addRoute(method, path, handler)` para definir rutas individuales
+- Maneja el enrutamiento en `findRoute(method, pathname)`
+- Soporta rutas parametrizadas con conversión a expresiones regulares
+- Mantiene un cache de expresiones regulares para rutas parametrizadas
+- Ejecuta middlewares antes de los handlers de rutas
+- Soporta rutas estáticas para servir archivos desde directorios locales
+
+**Método `addRoute`:**
+- Recibe: método HTTP, path y handler
+- Soporta autenticación por ruta
+- Soporta content-type por ruta
+- Soporta rutas estáticas con propiedad `static`
+- Carga controladores desde archivos externos
+- Registra la ruta en el array
+
+### 2. RouteLoader (lib/loader/routeLoader.js)
+
+Componente encargado de cargar rutas desde archivos JSON.
+
+**Características:**
+- Lee y parsea archivos JSON de rutas
+- Valida la estructura del archivo de rutas
+- Carga controladores desde archivos externos
+- Aplica autenticación por ruta
+- Aplica content-type por ruta
+- Soporta rutas estáticas
+- Dispara hooks antes y después de cargar rutas
+- Soporta recarga automática de rutas
+
+**Método `loadSingleRoute`:**
+- Carga el módulo del controlador
+- Obtiene el handler del controlador
+- Aplica content-type si está especificado
+- Aplica autenticación si está especificada
+- Procesa rutas estáticas si están definidas
+- Integra el handler procesado con el servidor usando `server.addRoute`
+
+## Funcionalidades Soportadas por routes.json
+
+### 1. Estructura Básica
+```json
+[
+  {
+    "path": "/ruta/ejemplo",
+    "method": "GET",
+    "controller": "./controllers/EjemploController.js",
+    "handler": "metodoHandler"
+  }
+]
+```
+
+### 2. Content-Type por Ruta
+```json
+{
+  "contentType": "application/json"
+}
+```
+
+### 3. Autenticación por Ruta
+```json
+{
+  "auth": "jwt",
+  "authOptions": {
+    "jwtSecret": "secreto-ejemplo"
+  }
+}
+```
+
+Tipos de autenticación soportados:
+- `jwt` - Autenticación JWT
+- `apiKey` - Autenticación por API Key
+- `session` - Autenticación por sesión
+- Otros tipos registrados en el authenticator
+
+### 4. Rutas Parametrizadas
+Soporta rutas con parámetros como `/usuarios/:id` que se convierten a expresiones regulares.
+
+### 5. Rutas Estáticas
+Soporta rutas para servir archivos estáticos desde directorios locales:
+
+```json
+[
+  {
+    "path": "/static",
+    "method": "GET",
+    "static": {
+      "dir": "./public",
+      "index": ["index.html", "index.htm"],
+      "cacheControl": "public, max-age=3600"
+    }
+  }
+]
+```
+
+## Comparativa: routes.json vs addRoute()
+
+| Característica | routes.json | addRoute() |
+|---|---|---|
+| Definición de rutas | Masiva (archivo JSON) | Individual |
+| Carga de controladores | Automática desde archivos | Manual (función handler) |
+| Autenticación por ruta | ✅ Soportada | ✅ Soportada |
+| Content-Type por ruta | ✅ Soportado | ✅ Soportado |
+| Opciones de autenticación | ✅ Soportadas | ✅ Soportadas |
+| Rutas parametrizadas | ✅ Soportadas | ✅ Soportadas |
+| Rutas estáticas | ✅ Soportadas | ✅ Soportadas |
+| Integración con hooks | ✅ Soportada | ✅ Soportada |
+
+## Flujo de Procesamiento de Rutas
+
+### Para routes.json:
+1. `RouteLoader.loadRoutes()` lee el archivo JSON
+2. Valida la estructura del archivo
+3. Para cada ruta, `loadSingleRoute()`:
+   - Si es ruta estática, llama directamente a `server.addRoute()` con configuración estática
+   - Si es ruta dinámica, carga el módulo del controlador
+   - Obtiene el handler del controlador
+   - Aplica content-type si existe
+   - Aplica autenticación si existe
+   - Llama a `server.addRoute()` con el handler procesado
+4. El servidor procesa las solicitudes normalmente
+
+### Para addRoute():
+1. Cliente llama directamente `server.addRoute(method, path, handler)` o `server.addRoute(configObject)`
+2. La ruta se registra directamente en `this.routes`
+3. Si es una ruta estática (tiene propiedad `static`), se crea un handler especial para servir archivos
+4. El servidor procesa las solicitudes normalmente
+
+## Rutas Estáticas
+
+### Definición
+Las rutas estáticas permiten servir archivos desde directorios locales. Se definen con la propiedad `static`:
+
+```json
+{
+  "path": "/assets",
+  "method": "GET",
+  "static": {
+    "dir": "./public/assets",
+    "index": ["index.html"],
+    "cacheControl": "public, max-age=3600"
+  }
+}
+```
+
+### Características
+- Sirve cualquier archivo dentro del directorio especificado
+- Detecta automáticamente el tipo MIME
+- Soporta archivos índice para carpetas
+- Permite configurar headers de caché
+- Previene ataques de path traversal
+- Compatible con el sistema de hooks del framework
+
+### Integración con Hooks
+El sistema de rutas estáticas incluye integración con el sistema de hooks:
+
+- `pre_static_file_serve`: Antes de procesar un archivo estático
+- `static_file_served`: Después de servir un archivo estático
+- `static_file_not_found`: Cuando no se encuentra un archivo estático
+- `static_file_access_denied`: Cuando se niega el acceso a un archivo estático
+- `serving_index_file`: Cuando se sirve un archivo índice
+- `static_directory_no_index`: Cuando un directorio no tiene archivo índice
+- `before_reading_static_file`: Antes de leer un archivo estático
+- `static_file_error`: Cuando ocurre un error al servir un archivo estático
+
+## Problemas Resueltos
+
+### 1. Soporte para archivos estáticos
+- Se ha añadido soporte nativo para servir archivos estáticos
+- Ambos sistemas (routes.json y addRoute) soportan rutas estáticas
+- Se mantiene la seguridad y funcionalidad existente