jerkjs 2.2.0 → 2.3.0

package/docs/ROUTING_WITHOUT_JSON_GUIDE.md

@@ -0,0 +1,454 @@
+# Guía: Cómo añadir rutas, controladores y vistas sin utilizar routes.json
+
+## Introducción
+
+El framework JERK permite definir rutas, controladores y vistas de dos maneras:
+
+1. Usando el archivo `routes.json` (método tradicional)
+2. Usando el método `addRoute()` directamente en el código (método programático)
+
+Esta guía explica cómo implementar la segunda opción, que permite una mayor flexibilidad y control directo sobre la definición de rutas sin depender de archivos JSON externos.
+
+## Ventajas del enfoque sin routes.json
+
+- **Mayor control**: Acceso directo al código de definición de rutas
+- **Flexibilidad**: Definición dinámica de rutas basadas en condiciones en tiempo de ejecución
+- **Integración directa**: No dependencia de archivos externos
+- **Compatibilidad**: Todas las funcionalidades disponibles en `routes.json` también están disponibles con `addRoute()`
+
+## Configuración del servidor
+
+Para usar el enfoque sin `routes.json`, debes configurar tu servidor para definir rutas directamente:
+
+```javascript
+const { APIServer, Logger, Authenticator, Cors, RateLimiter, Compressor, Firewall, SessionManager, ViewEngine, hooks } = require('jerkjs');
+
+class MiServidor {
+  constructor() {
+    this.server = new APIServer({
+      port: 3000,
+      host: 'localhost'
+    });
+
+    // Inicializar componentes
+    this.logger = new Logger();
+    this.authenticator = new Authenticator({ logger: this.logger });
+    this.cors = new Cors();
+    this.rateLimiter = new RateLimiter();
+    this.compressor = new Compressor({ hooks: hooks });
+    this.firewall = new Firewall({ logger: this.logger });
+    this.sessionManager = new SessionManager();
+    this.viewEngine = new ViewEngine({ hooks: hooks });
+
+    // Configurar el motor de vistas en el servidor
+    this.server.viewEngine = this.viewEngine;
+    this.viewEngine.viewsPath = './views'; // Ruta a tus vistas
+    
+    // Configurar middlewares
+    this.configureMiddlewares();
+    
+    // Definir rutas sin usar routes.json
+    this.defineRoutes();
+  }
+
+  configureMiddlewares() {
+    this.server.use(this.firewall.middleware());
+    this.server.use(this.compressor.middleware());
+    this.server.use(this.cors.middleware());
+    this.server.use(this.rateLimiter.middleware());
+    this.server.use(this.sessionManager.middleware());
+  }
+
+  defineRoutes() {
+    // Ruta principal
+    this.server.addRoute('GET', '/', (req, res) => {
+      res.render('index', {
+        title: 'Mi Aplicación',
+        message: 'Bienvenido al servidor sin routes.json'
+      });
+    });
+
+    // Ruta con autenticación JWT - implementación manual
+    this.server.addRoute('GET', '/dashboard', (req, res) => {
+      // Verificar token JWT manualmente
+      const authHeader = req.headers.authorization;
+      const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+      if (!token) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Token no proporcionado' }));
+        return;
+      }
+
+      // Verificar que JWT_SECRET esté definido en las variables de entorno
+      const jwtSecret = process.env.JWT_SECRET;
+      if (!jwtSecret) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Configuración de seguridad incompleta: JWT_SECRET no definido' }));
+        return;
+      }
+
+      try {
+        const jwt = require('jsonwebtoken');
+        const decoded = jwt.verify(token, jwtSecret);
+
+        // Agregar información del usuario a la solicitud
+        req.user = decoded;
+
+        // Continuar con la lógica protegida
+        res.render('dashboard', {
+          title: 'Panel de Control',
+          user: req.user
+        });
+      } catch (error) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Token inválido o expirado' }));
+      }
+    }, {
+      contentType: 'text/html'
+    });
+
+    // Ruta de API con content-type JSON
+    this.server.addRoute('GET', '/api/data', (req, res) => {
+      res.end(JSON.stringify({
+        message: 'Datos de la API',
+        timestamp: new Date().toISOString()
+      }));
+    }, {
+      contentType: 'application/json'
+    });
+  }
+
+  start() {
+    this.server.start();
+  }
+}
+
+const miServidor = new MiServidor();
+miServidor.start();
+```
+
+## Definición de rutas con todas las funcionalidades
+
+El método `addRoute()` ahora soporta todas las funcionalidades que estaban disponibles en `routes.json`, aunque la implementación difiere ligeramente:
+
+### 1. Rutas básicas
+
+```javascript
+// Ruta simple sin autenticación
+server.addRoute('GET', '/', (req, res) => {
+  res.end('Hola Mundo');
+});
+```
+
+### 2. Rutas con content-type
+
+```javascript
+// Ruta con content-type específico
+server.addRoute('GET', '/api/users', (req, res) => {
+  res.end(JSON.stringify({ users: [] }));
+}, {
+  contentType: 'application/json'
+});
+```
+
+### 3. Rutas con autenticación
+
+**Importante**: A diferencia de `routes.json`, para usar autenticación con `addRoute()`, debes implementar la lógica de autenticación manualmente en el handler o registrar una estrategia de autenticación en el Authenticator:
+
+```javascript
+// Opción 1: Implementar autenticación JWT manualmente
+server.addRoute('GET', '/protected', (req, res) => {
+  // Verificar token JWT manualmente
+  const authHeader = req.headers.authorization;
+  const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+  if (!token) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Token no proporcionado' }));
+    return;
+  }
+
+  // Verificar que JWT_SECRET esté definido en las variables de entorno
+  const jwtSecret = process.env.JWT_SECRET;
+  if (!jwtSecret) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Configuración de seguridad incompleta: JWT_SECRET no definido' }));
+    return;
+  }
+
+  try {
+    const jwt = require('jsonwebtoken');
+    const decoded = jwt.verify(token, jwtSecret);
+
+    // Agregar información del usuario a la solicitud
+    req.user = decoded;
+
+    // Continuar con la lógica protegida
+    res.render('protected', { user: req.user });
+  } catch (error) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Token inválido o expirado' }));
+  }
+}, {
+  contentType: 'text/html'
+});
+
+// Opción 2: Registrar estrategia de autenticación y usar middleware
+// Registrar la estrategia JWT en el authenticator
+authenticator.use('jwt-custom', async (req, options = {}) => {
+  const authHeader = req.headers.authorization;
+  const token = authHeader && authHeader.split(' ')[1];
+
+  if (!token) return false;
+
+  // Verificar que JWT_SECRET esté definido en las variables de entorno
+  const jwtSecret = process.env.JWT_SECRET;
+  if (!jwtSecret) {
+    console.error('ERROR: JWT_SECRET no está definido en las variables de entorno');
+    return false;
+  }
+
+  try {
+    const jwt = require('jsonwebtoken');
+    const decoded = jwt.verify(token, jwtSecret);
+    req.user = decoded;
+    return true;
+  } catch (error) {
+    return false;
+  }
+});
+
+// Luego usar el middleware de autenticación
+server.addRoute('GET', '/protected',
+  authenticator.authenticate('jwt-custom', {})((req, res) => {
+    // Esta ruta está protegida
+    res.render('protected', { user: req.user });
+  }), {
+    contentType: 'text/html'
+  }
+);
+```
+
+### 4. Rutas con vistas y variables
+
+```javascript
+// Ruta que renderiza una vista con variables
+server.addRoute('GET', '/profile', (req, res) => {
+  res.render('profile', {
+    user: { name: 'Juan', email: 'juan@example.com' },
+    title: 'Perfil de Usuario'
+  });
+});
+```
+
+## Creación de controladores sin routes.json
+
+Puedes crear controladores que extiendan `ControllerBase` y usarlos con el enfoque programático:
+
+```javascript
+// controllers/HomeController.js
+const ControllerBase = require('../lib/mvc/controllerBase');
+
+class HomeController extends ControllerBase {
+  constructor(options = {}) {
+    super(options);
+    this.viewsPath = './views'; // Ruta a las vistas
+  }
+
+  index(req, res) {
+    this.set('title', 'Página de Inicio');
+    this.set('message', 'Bienvenido a mi aplicación');
+    this.set('users', [
+      { id: 1, name: 'Juan' },
+      { id: 2, name: 'Ana' }
+    ]);
+    
+    this.render(res, 'home/index');
+  }
+
+  showUser(req, res) {
+    const userId = req.params.id;
+    this.set('title', `Usuario ${userId}`);
+    this.set('user', { id: userId, name: `Usuario ${userId}` });
+    
+    this.render(res, 'user/show');
+  }
+}
+
+module.exports = new HomeController();
+```
+
+Y luego usarlo en tu servidor:
+
+```javascript
+const HomeController = require('./controllers/HomeController');
+
+server.addRoute('GET', '/', (req, res) => {
+  HomeController.setRequestResponse(req, res);
+  HomeController.index(req, res);
+});
+
+server.addRoute('GET', '/users/:id', (req, res) => {
+  HomeController.setRequestResponse(req, res);
+  HomeController.showUser(req, res);
+});
+```
+
+## Creación de vistas con variables y estructuras complejas
+
+Las vistas pueden usar todas las funcionalidades del motor de plantillas:
+
+### Vista básica con variables
+```html
+<!-- views/home/index.html -->
+<!DOCTYPE html>
+<html>
+<head>
+    <title>{{title}}</title>
+</head>
+<body>
+    <h1>{{title}}</h1>
+    <p>{{message}}</p>
+    
+    {{if users}}
+    <ul>
+    {{foreach:users}}
+        <li>{{item.name}}</li>
+    {{endforeach}}
+    </ul>
+    {{else}}
+    <p>No hay usuarios disponibles.</p>
+    {{endif}}
+</body>
+</html>
+```
+
+### Vista con estructuras condicionales y bucles
+```html
+<!-- views/user/show.html -->
+<!DOCTYPE html>
+<html>
+<head>
+    <title>{{title}}</title>
+</head>
+<body>
+    <h1>{{user.name}}</h1>
+    <p>ID: {{user.id}}</p>
+    
+    {{if user.active}}
+    <span class="active">Activo</span>
+    {{else}}
+    <span class="inactive">Inactivo</span>
+    {{endif}}
+</body>
+</html>
+```
+
+## Errores comunes y soluciones
+
+### 1. Variables no se reemplazan en vistas
+
+**Problema**: Las variables `{{variable}}` no se reemplazan en las vistas.
+
+**Solución**: Asegúrate de que:
+- El `ViewEngine` esté correctamente configurado en el servidor
+- La ruta de vistas esté correctamente especificada
+- Las variables se estén pasando correctamente al método `render()`
+
+### 2. Autenticación no funciona con addRoute()
+
+**Problema**: La autenticación no se aplica cuando se usa `addRoute()`.
+
+**Solución**: A diferencia de `routes.json`, `addRoute()` no acepta directamente las opciones `auth` y `authOptions`. Debes implementar la lógica de autenticación manualmente en el handler o usar el sistema de autenticación del framework como middleware:
+
+```javascript
+// Solución 1: Implementar autenticación manualmente en el handler
+server.addRoute('GET', '/protected', (req, res) => {
+  const authHeader = req.headers.authorization;
+  const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+  if (!token) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Token no proporcionado' }));
+    return;
+  }
+
+  try {
+    const jwt = require('jsonwebtoken');
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = decoded;
+
+    // Continuar con la lógica protegida
+    res.render('protected', { user: req.user });
+  } catch (error) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Token inválido o expirado' }));
+  }
+}, {
+  contentType: 'text/html'
+});
+
+// Solución 2: Usar el sistema de autenticación como middleware
+// Registrar la estrategia de autenticación
+authenticator.use('jwt-middleware', async (req, options = {}) => {
+  const authHeader = req.headers.authorization;
+  const token = authHeader && authHeader.split(' ')[1];
+
+  if (!token) return false;
+
+  // Verificar que JWT_SECRET esté definido en las variables de entorno
+  const jwtSecret = process.env.JWT_SECRET;
+  if (!jwtSecret) {
+    console.error('ERROR: JWT_SECRET no está definido en las variables de entorno');
+    return false;
+  }
+
+  try {
+    const jwt = require('jsonwebtoken');
+    const decoded = jwt.verify(token, jwtSecret);
+    req.user = decoded;
+    return true;
+  } catch (error) {
+    return false;
+  }
+});
+
+// Aplicar el middleware de autenticación a la ruta
+server.addRoute('GET', '/protected',
+  authenticator.authenticate('jwt-middleware', {})((req, res) => {
+    res.render('protected', { user: req.user });
+  }), {
+    contentType: 'text/html'
+  }
+);
+```
+
+### 3. Rutas parametrizadas no funcionan
+
+**Problema**: Las rutas como `/users/:id` no capturan los parámetros.
+
+**Solución**: Los parámetros están disponibles en `req.params`:
+
+```javascript
+server.addRoute('GET', '/users/:id', (req, res) => {
+  const userId = req.params.id; // Aquí está el valor del parámetro
+  res.end(`Usuario ID: ${userId}`);
+});
+```
+
+## Buenas prácticas
+
+1. **Organiza tus rutas**: Agrupa rutas relacionadas en funciones separadas
+2. **Usa controladores**: Extiende `ControllerBase` para lógica compleja
+3. **Configura correctamente el ViewEngine**: Asegúrate de que la ruta de vistas esté correctamente configurada
+4. **Maneja errores**: Implementa manejo de errores adecuado
+5. **Documenta tus rutas**: Aunque no uses `routes.json`, documenta tus rutas programáticas
+6. **Implementa autenticación manualmente**: Para usar autenticación con `addRoute()`, implementa la lógica manualmente o registra estrategias de autenticación
+7. **Usa el sistema de hooks**: Aprovecha el sistema de hooks y filters para extensibilidad
+
+## Conclusión
+
+El enfoque sin `routes.json` ofrece una alternativa poderosa y flexible para definir rutas en JERK Framework. Con las mejoras implementadas, ahora puedes usar `addRoute()` con todas las funcionalidades equivalentes a las disponibles en `routes.json`, incluyendo autenticación (implementada manualmente o con middleware), content-type, vistas con variables anidadas y más.
+
+Esta arquitectura permite una mayor flexibilidad y control sobre la definición de rutas, ideal para aplicaciones que requieren lógica dinámica en la definición de endpoints. Ambas arquitecturas (con y sin `routes.json`) ofrecen las mismas funcionalidades y pueden usarse según las necesidades del proyecto.