blackcoffee2 2.1.0

package/manuales/hooks_chaining_conditions_guide.md

@@ -0,0 +1,261 @@
+# Soporte para Chaining y Condiciones en Hooks y Filtros
+
+## Uso Condicional de Hooks y Filtros
+
+Sí, los hooks y filtros pueden ser condicionales basados en `matchedRoute`, `req` u otros parámetros. El framework permite implementar lógica condicional dentro de los callbacks de hooks y filtros.
+
+### Ejemplos de Uso Condicional
+
+#### 1. Condición basada en la ruta coincidente (matchedRoute)
+
+```javascript
+// Aplicar lógica solo a rutas específicas
+hooks.addAction('before_route_handler', (req, res, matchedRoute) => {
+  // Verificar si la ruta coincide con un patrón específico
+  if (matchedRoute.path.startsWith('/admin/')) {
+    // Aplicar lógica específica para rutas de administración
+    console.log(`Acceso a área de administración: ${req.url}`);
+    
+    // Verificar permisos de administrador
+    if (!req.user || req.user.role !== 'admin') {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Acceso denegado: Requiere rol de administrador' }));
+      return; // Detener ejecución del handler original
+    }
+  }
+}, 10, 3);
+```
+
+#### 2. Condición basada en propiedades de la solicitud (req)
+
+```javascript
+// Aplicar lógica basada en cabeceras o propiedades de la solicitud
+hooks.addFilter('before_static_file_load', (data, req, res, filePath, staticConfig) => {
+  // Verificar si el usuario tiene un rol específico
+  if (req.userRole === 'premium') {
+    // Permitir acceso a recursos premium
+    return {
+      ...data,
+      staticConfig: {
+        ...staticConfig,
+        // Configuración específica para usuarios premium
+        maxAge: 3600 * 24 * 7 // Cache por una semana
+      }
+    };
+  }
+  
+  // Para usuarios normales, retornar sin cambios
+  return data;
+}, 10, 4);
+```
+
+#### 3. Condición basada en el tipo de archivo o ruta
+
+```javascript
+// Aplicar lógica condicional según el tipo de archivo
+hooks.addFilter('after_static_file_load', (data, req, res, filePath, staticConfig, fileContent) => {
+  // Solo aplicar a archivos HTML
+  if (filePath.endsWith('.html')) {
+    let content = data.fileContent.toString();
+    
+    // Inyectar script condicionalmente
+    if (req.user && req.user.analyticsEnabled) {
+      content = content.replace('</body>', '<script src="/analytics.js"></script></body>');
+    }
+    
+    return {
+      ...data,
+      fileContent: Buffer.from(content)
+    };
+  }
+  
+  return data;
+}, 10, 5);
+```
+
+## Composición y Encadenamiento de Hooks
+
+### 1. Encadenamiento Simple (Cascada)
+
+Los hooks se ejecutan en orden según su prioridad, permitiendo una composición en cascada:
+
+```javascript
+// Primer filtro: autenticación
+hooks.addFilter('before_route_handler', (data, req, res, matchedRoute) => {
+  if (needsAuthentication(matchedRoute)) {
+    if (!req.isAuthenticated) {
+      res.writeHead(401);
+      res.end('Unauthorized');
+      return data; // Detener la cadena
+    }
+  }
+  return data;
+}, 5, 3);
+
+// Segundo filtro: autorización (se ejecuta después si el primero no detuvo)
+hooks.addFilter('before_route_handler', (data, req, res, matchedRoute) => {
+  if (needsAuthorization(matchedRoute)) {
+    if (!hasPermission(req.user, matchedRoute)) {
+      res.writeHead(403);
+      res.end('Forbidden');
+      return data; // Detener la cadena
+    }
+  }
+  return data;
+}, 10, 3); // Prioridad más alta que el anterior
+
+// Tercer filtro: auditoría (se ejecuta si los anteriores permitieron continuar)
+hooks.addFilter('before_route_handler', (data, req, res, matchedRoute) => {
+  logAccess(req, matchedRoute);
+  return data;
+}, 15, 3); // Prioridad más alta que los anteriores
+```
+
+### 2. Encadenamiento Condicional Avanzado
+
+```javascript
+// Cadena de procesamiento condicional
+hooks.addFilter('after_route_handler', (data, req, res, matchedRoute) => {
+  // Solo aplicar a rutas que requieren métricas
+  if (requiresMetrics(matchedRoute)) {
+    // Calcular métricas
+    const metrics = calculateMetrics(req, res);
+    
+    // Pasar métricas al siguiente filtro
+    return {
+      ...data,
+      req: {
+        ...req,
+        metrics: metrics
+      }
+    };
+  }
+  
+  return data;
+}, 5, 3);
+
+hooks.addFilter('after_route_handler', (data, req, res, matchedRoute) => {
+  // Solo aplicar si hay métricas disponibles
+  if (req.metrics) {
+    // Enviar métricas a servicio externo
+    sendMetricsToService(req.metrics);
+  }
+  
+  return data;
+}, 10, 3);
+```
+
+### 3. Patrón de Interruptor Condicional
+
+```javascript
+// Hook que actúa como interruptor basado en condiciones
+hooks.addAction('before_route_handler', (req, res, matchedRoute) => {
+  // Verificar si la ruta está en modo mantenimiento
+  if (isMaintenanceMode() && isInMaintenanceArea(matchedRoute)) {
+    res.writeHead(503, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      error: 'Sistema en mantenimiento', 
+      retryAfter: '300' // Reintentar en 5 minutos
+    }));
+    return; // Interrumpir la ejecución normal
+  }
+  
+  // Verificar límite de tasa (rate limiting)
+  if (isRateLimited(req)) {
+    res.writeHead(429, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      error: 'Límite de solicitudes excedido',
+      retryAfter: '60' // Reintentar en 1 minuto
+    }));
+    return; // Interrumpir la ejecución normal
+  }
+  
+  // Si pasa todas las condiciones, continuar normalmente
+}, 5, 3);
+```
+
+## Buenas Prácticas para Evitar Abusos
+
+### 1. Separación de Responsabilidades
+
+```javascript
+// MAL: Un solo hook que hace muchas cosas
+hooks.addFilter('before_route_handler', (data, req, res, matchedRoute) => {
+  // Mucha lógica mezclada aquí
+  authenticate(req);
+  authorize(req, matchedRoute);
+  logRequest(req);
+  validateInput(req);
+  // ...
+  return data;
+});
+
+// BIEN: Hooks separados por responsabilidad
+hooks.addAction('before_route_handler', (req, res, matchedRoute) => {
+  authenticate(req);
+}, 5, 3);
+
+hooks.addAction('before_route_handler', (req, res, matchedRoute) => {
+  authorize(req, matchedRoute);
+}, 10, 3);
+
+hooks.addAction('before_route_handler', (req, res, matchedRoute) => {
+  logRequest(req);
+}, 15, 3);
+```
+
+### 2. Uso de Prioridades Apropiadas
+
+```javascript
+// Prioridades recomendadas para diferentes tipos de hooks:
+// 1-10: Validación y seguridad crítica
+// 11-30: Autenticación y autorización
+// 31-50: Preparación de contexto
+// 51-70: Lógica de negocio
+// 71-90: Auditoría y logging
+// 91-100: Limpieza y post-procesamiento
+
+hooks.addAction('before_route_handler', (req, res, matchedRoute) => {
+  // Validación de seguridad crítica - alta prioridad
+  validateSecurity(req);
+}, 3, 3);
+
+hooks.addAction('before_route_handler', (req, res, matchedRoute) => {
+  // Autenticación - prioridad media-alta
+  authenticate(req);
+}, 15, 3);
+
+hooks.addAction('before_route_handler', (req, res, matchedRoute) => {
+  // Preparación de contexto - prioridad media
+  setupContext(req);
+}, 40, 3);
+```
+
+### 3. Manejo Correcto de la Cadena
+
+```javascript
+// Interrupción controlada de la cadena
+hooks.addFilter('before_route_handler', (data, req, res, matchedRoute) => {
+  if (!isValidRequest(req)) {
+    if (!res.headersSent) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Solicitud inválida' }));
+    }
+    // Retornar data sin cambios para evitar ejecución del handler original
+    return data;
+  }
+  
+  // Continuar la cadena si la validación pasa
+  return data;
+}, 5, 3);
+```
+
+## Conclusión
+
+Los hooks y filtros en el framework Insitu soportan completamente el uso condicional y la composición en cadena. La clave para aprovechar esta funcionalidad sin abusos es:
+
+1. **Usar condiciones claras** basadas en `req`, `matchedRoute`, `res` u otros parámetros
+2. **Separar responsabilidades** en hooks diferentes
+3. **Utilizar prioridades apropiadas** para controlar el orden de ejecución
+4. **Manejar correctamente las interrupciones** de la cadena cuando sea necesario
+5. **Documentar el comportamiento** de los hooks complejos