insitu-js 1.1.0 → 1.2.0

package/CHANGELOG-INSITU.md

@@ -0,0 +1,235 @@
+# Insitu Framework Modifications - BlackCoffee
+
+Este documento detalla las modificaciones realizadas al framework Insitu para soportar el sistema de templates 404 personalizados en BlackCoffee.
+
+---
+
+## [2026-02-16] - Custom Static 404 Response Filter
+
+### Resumen
+
+Se añadió el filtro `customize_static_404_response` al manejador de archivos estáticos del servidor Insitu. Este filtro permite interceptar las respuestas 404 para archivos estáticos y reemplazar la respuesta JSON por defecto con un template HTML personalizado.
+
+### Archivos Modificados
+
+#### `lib/core/server.js`
+
+**Ubicación:** Líneas ~456-520, ~545-565, ~615-630
+
+**Cambios realizados:**
+
+1. **Manejador de error ENOENT (archivo no encontrado)**
+   ```javascript
+   // ANTES:
+   if (error.code === 'ENOENT') {
+     this.sendNotFoundResponse(res, error.path);
+     StaticFileHooksHandler.handleStaticFileNotFound(this, error.path, req, res);
+   }
+
+   // DESPUÉS:
+   if (error.code === 'ENOENT') {
+     if (this.hooks) {
+       const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+         shouldSendDefaultResponse: true,
+         filePath: error.path,
+         req,
+         res
+       }, error.path, req, res);
+
+       if (hookResult.shouldSendDefaultResponse !== false) {
+         this.sendNotFoundResponse(res, error.path);
+       }
+     } else {
+       this.sendNotFoundResponse(res, error.path);
+     }
+
+     StaticFileHooksHandler.handleStaticFileNotFound(this, error.path, req, res);
+   }
+   ```
+
+2. **Directorio no encontrado (dentro del try-catch de stat)**
+   ```javascript
+   // Se añadió el filtro customize_static_404_response antes de sendJsonResponse
+   if (this.hooks) {
+     const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+       shouldSendDefaultResponse: true,
+       filePath: dirPath,
+       req,
+       res
+     }, dirPath, req, res);
+
+     if (hookResult.shouldSendDefaultResponse !== false) {
+       this.sendJsonResponse(res, 404, { error: 'Directorio no encontrado', path: dirPath });
+     }
+   } else {
+     this.sendJsonResponse(res, 404, { error: 'Directorio no encontrado', path: dirPath });
+   }
+   ```
+
+3. **Archivo no encontrado (error de stat)**
+   ```javascript
+   // Se añadió el filtro customize_static_404_response antes de sendNotFoundResponse
+   if (this.hooks) {
+     const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+       shouldSendDefaultResponse: true,
+       filePath: physicalPath,
+       req,
+       res
+     }, physicalPath, req, res);
+
+     if (hookResult.shouldSendDefaultResponse !== false) {
+       this.sendNotFoundResponse(res, physicalPath);
+     }
+   } else {
+     this.sendNotFoundResponse(res, physicalPath);
+   }
+   ```
+
+4. **Directorio sin archivo índice**
+   ```javascript
+   // Se añadió el filtro customize_static_404_response antes de sendNotFoundResponse
+   if (this.hooks) {
+     const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+       shouldSendDefaultResponse: true,
+       filePath: dirPath + ' (no index file)',
+       req,
+       res
+     }, dirPath, req, res);
+
+     if (hookResult.shouldSendDefaultResponse !== false) {
+       this.sendNotFoundResponse(res);
+     }
+   } else {
+     this.sendNotFoundResponse(res);
+   }
+   ```
+
+### Nuevo Hook Registrado
+
+**Nombre:** `customize_static_404_response`
+
+**Tipo:** Filter
+
+**Parámetros:**
+- `data` (Object): Datos del filtro
+  - `shouldSendDefaultResponse` (boolean): Si true, envía la respuesta JSON por defecto
+  - `filePath` (string): Ruta del archivo no encontrado
+  - `req` (Object): Objeto de solicitud HTTP
+  - `res` (Object): Objeto de respuesta HTTP
+- `filePath` (string): Ruta del archivo (parámetro directo)
+- `req` (Object): Objeto de solicitud HTTP
+- `res` (Object): Objeto de respuesta HTTP
+
+**Comportamiento:**
+- Si `data.shouldSendDefaultResponse` se establece en `false`, NO se envía la respuesta JSON por defecto
+- El filtro puede enviar una respuesta personalizada (ej: template HTML) directamente
+- Si el filtro no modifica `shouldSendDefaultResponse`, se envía la respuesta JSON estándar
+
+### Ejemplo de Uso
+
+```javascript
+const { hooks } = require('insitu-js');
+
+// Registrar filtro para servir template HTML 404
+hooks.addFilter('customize_static_404_response', (data, filePath, req, res) => {
+  const template = load404Template();
+  
+  if (template && req && res) {
+    const errorData = {
+      type: 'file',
+      path: filePath,
+      method: req.method,
+      url: req.url,
+      timestamp: new Date().toISOString()
+    };
+
+    // Inyectar datos en el template
+    let html = template.replace(
+      'window.errorData = {};',
+      `window.errorData = ${JSON.stringify(errorData)};`
+    );
+
+    // Enviar respuesta HTML personalizada
+    res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+
+    // Evitar respuesta por defecto
+    data.shouldSendDefaultResponse = false;
+  }
+  
+  return data;
+}, 5); // Prioridad alta
+```
+
+### Compatibilidad
+
+- **Retrocompatible:** Sí. Si no hay filtros registrados, el comportamiento es idéntico al original
+- **Requiere:** Sistema de hooks de Insitu (disponible en v1.1.0+)
+- **Afecta:** Solo a rutas estáticas (archivos servidos con `static: { dir: '...' }`)
+
+### Puntos de Ejecución
+
+El filtro se ejecuta en 4 puntos del flujo de archivos estáticos:
+
+```
+Solicitud → createStaticFileHandler()
+   ↓
+┌─ Try-catch principal
+│  ├─ fs.promises.access() falla
+│  │  └─ [HOOK] ENOENT handler (línea ~617)
+│  │
+│  ├─ stats.isDirectory() = true
+│  │  └─ [HOOK] Directory not found (línea ~456)
+│  │
+│  └─ Catch statErr
+│     └─ [HOOK] Stat error (línea ~487)
+│
+└─ Es directorio, buscar index
+   └─ No hay index file
+      └─ [HOOK] No index file (línea ~545)
+```
+
+### Testing
+
+Para verificar que el hook funciona correctamente:
+
+```bash
+# 1. Iniciar servidor con hooks registrados
+node server.js
+
+# 2. Solicitar archivo inexistente
+curl -k https://localhost:9791/nonexistent.css
+
+# 3. Verificar respuesta HTML (no JSON)
+# Expected: <!DOCTYPE html>... (template 404)
+# Not expected: {"error":"Archivo no encontrado"...}
+```
+
+### Notas de Implementación
+
+1. **Orden de ejecución:** El filtro se registra con prioridad 5 (alta) para ejecutarse antes que cualquier otro filtro que pueda modificar la respuesta
+
+2. **Manejo de undefined:** Los parámetros `req` y `res` pueden llegar como `undefined` en algunos contextos. Los filtros deben validar antes de usarlos
+
+3. **Fallback:** Si el filtro falla o no envía respuesta, `shouldSendDefaultResponse` permanece en `true` y se envía la respuesta JSON estándar
+
+4. **Performance:** El template debe cachearse para evitar lectura de archivo en cada 404
+
+### Referencias
+
+- Hook existente similar: `customize_404_response` (para rutas dinámicas, línea ~1088)
+- Handler estático: `StaticFileHooksHandler.handleStaticFileNotFound()` (línea ~84 de static-file-hooks-handler.js)
+
+---
+
+## Historial de Versiones
+
+| Fecha | Versión Insitu | Cambio |
+|-------|---------------|--------|
+| 2026-02-16 | 1.1.0 | Añadido filtro `customize_static_404_response` en 4 puntos |
+
+---
+
+**Documentación creada para:** BlackCoffee v1.2.0  
+**Autor:** Benjamin Sanchez Cardenas  
+**Repositorio:** https://gitlab.com/bytedogssyndicate1/bc2

package/CHANGELOG.md

@@ -5,6 +5,98 @@ El versionado sigue SemVer (MAJOR.MINOR.PATCH).
 
 ---
 
+## [1.2.0] - 2026-02-16
+
+### Custom Static 404 Response Filter - Insitu Framework
+
+#### Nuevo Hook: `customize_static_404_response`
+
+Se añadió el filtro `customize_static_404_response` al manejador de archivos estáticos del servidor Insitu. Este filtro permite interceptar las respuestas 404 para archivos estáticos y reemplazar la respuesta JSON por defecto con un template HTML personalizado.
+
+#### Puntos de Aplicación en `lib/core/server.js`
+
+El filtro se ejecuta en 4 puntos del flujo de archivos estáticos:
+
+1. **Manejador de error ENOENT (archivo no encontrado)** - Línea ~617
+   - Se ejecuta cuando `fs.promises.access()` falla con error ENOENT
+   - Permite personalizar la respuesta antes de enviar `sendNotFoundResponse()`
+
+2. **Directorio no encontrado (dentro del try-catch de stat)** - Línea ~456
+   - Se ejecuta cuando `stats.isDirectory()` es true pero el directorio no existe
+   - Permite personalizar la respuesta antes de enviar el error de directorio
+
+3. **Archivo no encontrado (error de stat)** - Línea ~487
+   - Se ejecuta cuando ocurre un error al obtener estadísticas del archivo
+   - Permite personalizar la respuesta antes de enviar `sendNotFoundResponse()`
+
+4. **Directorio sin archivo índice** - Línea ~545
+   - Se ejecuta cuando un directorio no contiene archivo índice
+   - Permite personalizar la respuesta antes de enviar `sendNotFoundResponse()`
+
+#### Parámetros del Hook
+
+- `data` (Object): Datos del filtro
+  - `shouldSendDefaultResponse` (boolean): Si true, envía la respuesta JSON por defecto
+  - `filePath` (string): Ruta del archivo no encontrado
+  - `req` (Object): Objeto de solicitud HTTP
+  - `res` (Object): Objeto de respuesta HTTP
+- `filePath` (string): Ruta del archivo (parámetro directo)
+- `req` (Object): Objeto de solicitud HTTP
+- `res` (Object): Objeto de respuesta HTTP
+
+#### Comportamiento
+
+- Si `data.shouldSendDefaultResponse` se establece en `false`, NO se envía la respuesta JSON por defecto
+- El filtro puede enviar una respuesta personalizada (ej: template HTML) directamente
+- Si el filtro no modifica `shouldSendDefaultResponse`, se envía la respuesta JSON estándar
+
+#### Ejemplo de Uso
+
+```javascript
+const { hooks } = require('insitu-js');
+
+hooks.addFilter('customize_static_404_response', (data, filePath, req, res) => {
+  const template = load404Template();
+
+  if (template && req && res) {
+    const errorData = {
+      type: 'file',
+      path: filePath,
+      method: req.method,
+      url: req.url,
+      timestamp: new Date().toISOString()
+    };
+
+    let html = template.replace(
+      'window.errorData = {};',
+      `window.errorData = ${JSON.stringify(errorData)};`
+    );
+
+    res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+
+    data.shouldSendDefaultResponse = false;
+  }
+
+  return data;
+}, 5);
+```
+
+#### Compatibilidad
+
+- **Retrocompatible:** Sí. Si no hay filtros registrados, el comportamiento es idéntico al original
+- **Requiere:** Sistema de hooks de Insitu (disponible en v1.1.0+)
+- **Afecta:** Solo a rutas estáticas (archivos servidos con `static: { dir: '...' }`)
+
+#### Beneficios Obtenidos
+
+- Capacidad de servir templates HTML personalizados para errores 404 en archivos estáticos
+- Mejor experiencia de usuario con páginas de error estilizadas
+- Flexibilidad para incluir datos de error dinámicos en la respuesta
+- Mantenimiento del comportamiento por defecto cuando no hay filtros registrados
+
+---
+
 ## [1.0.2] - 2026-02-16
 
 ### Mejoras en Presentación Visual, Corrección de Dependencias Circulares y Hooks de Seguimiento - Insitu Framework

package/lib/core/server.js

@@ -453,20 +453,62 @@ class APIServer {
               }
 
               // Si es directorio pero no hay archivo índice
-              this.sendJsonResponse(res, 404, { error: 'Directorio no encontrado', path: dirPath });
+              // Permitir que los filtros personalicen la respuesta 404
+              if (this.hooks) {
+                const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+                  shouldSendDefaultResponse: true,
+                  filePath: dirPath,
+                  req,
+                  res
+                }, dirPath, req, res);
+
+                if (hookResult.shouldSendDefaultResponse !== false) {
+                  this.sendJsonResponse(res, 404, { error: 'Directorio no encontrado', path: dirPath });
+                }
+              } else {
+                this.sendJsonResponse(res, 404, { error: 'Directorio no encontrado', path: dirPath });
+              }
 
               StaticFileHooksHandler.handleStaticDirectoryNoIndex(this, dirPath, req, res);
               return;
             } else {
               // No es directorio ni archivo existente
-              this.sendNotFoundResponse(res, physicalPath);
+              // Permitir que los filtros personalicen la respuesta 404
+              if (this.hooks) {
+                const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+                  shouldSendDefaultResponse: true,
+                  filePath: physicalPath,
+                  req,
+                  res
+                }, physicalPath, req, res);
+
+                if (hookResult.shouldSendDefaultResponse !== false) {
+                  this.sendNotFoundResponse(res, physicalPath);
+                }
+              } else {
+                this.sendNotFoundResponse(res, physicalPath);
+              }
 
               StaticFileHooksHandler.handleStaticFileNotFound(this, physicalPath, req, res);
               return;
             }
           } catch (statErr) {
             // No es directorio ni archivo
-            this.sendNotFoundResponse(res, physicalPath);
+            // Permitir que los filtros personalicen la respuesta 404
+            if (this.hooks) {
+              const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+                shouldSendDefaultResponse: true,
+                filePath: physicalPath,
+                req,
+                res
+              }, physicalPath, req, res);
+
+              if (hookResult.shouldSendDefaultResponse !== false) {
+                this.sendNotFoundResponse(res, physicalPath);
+              }
+            } else {
+              this.sendNotFoundResponse(res, physicalPath);
+            }
 
             StaticFileHooksHandler.handleStaticFileNotFound(this, physicalPath, req, res);
             return;
@@ -501,7 +543,21 @@ class APIServer {
           }
 
           // Si es directorio pero no hay archivo índice
-          this.sendNotFoundResponse(res);
+          // Permitir que los filtros personalicen la respuesta 404
+          if (this.hooks) {
+            const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+              shouldSendDefaultResponse: true,
+              filePath: dirPath + ' (no index file)',
+              req,
+              res
+            }, dirPath, req, res);
+
+            if (hookResult.shouldSendDefaultResponse !== false) {
+              this.sendNotFoundResponse(res);
+            }
+          } else {
+            this.sendNotFoundResponse(res);
+          }
 
           StaticFileHooksHandler.handleStaticDirectoryNoIndex(this, dirPath, req, res);
           return;
@@ -558,7 +614,21 @@ class APIServer {
         StaticFileHooksHandler.handleStaticFileServed(this, physicalPath, req, res);
       } catch (error) {
         if (error.code === 'ENOENT') {
-          this.sendNotFoundResponse(res, error.path);
+          // Permitir que los filtros personalicen la respuesta 404 para archivos estáticos
+          if (this.hooks) {
+            const hookResult = this.hooks.applyFilters('customize_static_404_response', {
+              shouldSendDefaultResponse: true,
+              filePath: error.path,
+              req,
+              res
+            }, error.path, req, res);
+
+            if (hookResult.shouldSendDefaultResponse !== false) {
+              this.sendNotFoundResponse(res, error.path);
+            }
+          } else {
+            this.sendNotFoundResponse(res, error.path);
+          }
 
           StaticFileHooksHandler.handleStaticFileNotFound(this, error.path, req, res);
         } else if (error.code === 'EACCES') {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "insitu-js",
-  "version": "1.1.0",
-  "description": "Insitu Framework v1.0.2 - A comprehensive framework for building secure and scalable APIs with frontend support, sessions, template engine, integration with qbuilderjs, complete MVC architecture with models, enhanced route loading from directory, improved model loading system, administration extension, queue management system, route cache management module, and fixed routing issues with static and parametrized routes",
+  "version": "1.2.0",
+  "description": "Insitu Framework v1.2.0 - A comprehensive framework for building secure and scalable APIs with frontend support, sessions, template engine, integration with qbuilderjs, complete MVC architecture with models, enhanced route loading from directory, improved model loading system, administration extension, queue management system, route cache management module, fixed routing issues with static and parametrized routes, and custom static 404 response filter for personalized HTML templates",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",