blackcoffee2 2.1.0

package/manuales/hooks_filters_documentation_en.md

@@ -0,0 +1,493 @@
+# Hooks and Filters Documentation - Insitu Framework
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Types of Hooks](#types-of-hooks)
+3. [Available Hooks](#available-hooks)
+4. [Available Filters](#available-filters)
+5. [Route Hooks](#route-hooks)
+6. [Static File Hooks](#static-file-hooks)
+7. [Controller Hooks](#controller-hooks)
+8. [Request Hooks](#request-hooks)
+9. [Server Hooks](#server-hooks)
+10. [View Hooks](#view-hooks)
+11. [Statistics Hooks](#statistics-hooks)
+12. [Security Hooks](#security-hooks)
+13. [Administration Hooks](#administration-hooks)
+14. [Queue System Hooks](#queue-system-hooks)
+15. [Model Hooks](#model-hooks)
+16. [Session Hooks](#session-hooks)
+17. [Authentication Hooks](#authentication-hooks)
+18. [Middleware Hooks](#middleware-hooks)
+19. [Cache Hooks](#cache-hooks)
+20. [Database Hooks](#database-hooks)
+
+## Introduction
+
+The Insitu framework provides a robust system of hooks and filters that allows extending and customizing the framework's behavior at multiple points in the request lifecycle and operations. Hooks allow executing code at specific moments, while filters allow modifying data during the execution flow.
+
+## Types of Hooks
+
+### Action Hooks
+Action hooks allow executing code at specific points without modifying data. They are registered with `addAction()`.
+
+### Filter Hooks
+Filter hooks allow modifying data during the execution flow. They are registered with `addFilter()` and must return the modified value.
+
+## Available Hooks
+
+### `request_received`
+**Type:** Action and Filter  
+**Description:** Triggered when an HTTP request is received.  
+**Parameters:** `(req, res)`  
+**Filter Parameters:** `({ req, res }, req, res)`  
+**Usage:** Ideal for registering activity, initializing context, or applying global logic to all requests.
+
+### `route_matched`
+**Type:** Action and Filter  
+**Description:** Triggered when a matching route is found.  
+**Parameters:** `(matchedRoute, req, res)`  
+**Filter Parameters:** `({ matchedRoute, req, res }, matchedRoute, req, res)`  
+**Usage:** To apply specific logic after a route has been found.
+
+### `route_handler_executed`
+**Type:** Action and Filter  
+**Description:** Triggered after executing a route handler.  
+**Parameters:** `(matchedRoute, req, res)`  
+**Filter Parameters:** `({ matchedRoute, req, res }, matchedRoute, req, res)`  
+**Usage:** For post-execution auditing, metrics, or cleanup.
+
+### `route_not_found`
+**Type:** Action and Filter  
+**Description:** Triggered when no matching route is found (404 error).  
+**Parameters:** `(pathname, req, res)`  
+**Filter Parameters:** `({ pathname, req, res }, pathname, req, res)`  
+**Usage:** To handle unfound routes or register 404 errors.
+
+### `customize_404_response`
+**Type:** Filter  
+**Description:** Executes when a 404 error occurs to allow customizing the response.  
+**Parameters:** `({ shouldSendDefaultResponse, pathname, req, res }, pathname, req, res)`  
+**Usage:** To completely customize the 404 error response, including sending custom messages or avoiding the standard response.
+
+### `request_processed`
+**Type:** Action and Filter  
+**Description:** Triggered after completely processing a request.  
+**Parameters:** `(req, res)`  
+**Filter Parameters:** `({ req, res }, req, res)`  
+**Usage:** For cleanup tasks or request completion logging.
+
+### `request_error`
+**Type:** Action and Filter  
+**Description:** Triggered when an error occurs during request processing.  
+**Parameters:** `(req, res, error)`  
+**Filter Parameters:** `({ req, res, error }, req, res, error)`  
+**Usage:** For centralized error handling.
+
+### `middleware_response_finished`
+**Type:** Action and Filter  
+**Description:** Triggered when a middleware responds and finishes the request.  
+**Parameters:** `(req, res)`  
+**Filter Parameters:** `({ req, res }, req, res)`  
+**Usage:** To register when a middleware responds directly.
+
+### `options_response_sent`
+**Type:** Action and Filter  
+**Description:** Triggered when an OPTIONS response is sent.  
+**Parameters:** `(req, res)`  
+**Filter Parameters:** `({ req, res }, req, res)`  
+**Usage:** To register or audit OPTIONS responses (CORS preflight).
+
+## Available Filters
+
+### `before_route_handler`
+**Type:** Filter  
+**Description:** Executes before running a route handler (only for non-OPTIONS requests).  
+**Parameters:** `({ req, res, matchedRoute }, req, res, matchedRoute)`  
+**Usage:** For authentication, authorization, context preparation, or request/response object modification.
+
+### `after_route_handler`
+**Type:** Filter  
+**Description:** Executes after running a route handler (only for non-OPTIONS requests).  
+**Parameters:** `({ req, res, matchedRoute }, req, res, matchedRoute)`  
+**Usage:** For post-execution auditing, metrics, response modification, or cleanup.
+
+### `before_static_file_load`
+**Type:** Filter  
+**Description:** Executes before loading a static file.  
+**Parameters:** `({ req, res, filePath, staticConfig }, req, res, filePath, staticConfig)`  
+**Usage:** For permission checking, authentication, or static file configuration modification.
+
+### `after_static_file_load`
+**Type:** Filter  
+**Description:** Executes after loading a static file but before sending it to the client.  
+**Parameters:** `({ req, res, filePath, staticConfig, fileContent }, req, res, filePath, staticConfig, fileContent)`  
+**Usage:** To modify static file content, inject scripts, or apply transformations.
+
+### `before_controller_load`
+**Type:** Filter  
+**Description:** Executes before loading a controller.  
+**Parameters:** `({ controllerPath }, controllerPath)`  
+**Usage:** To modify the controller path or apply pre-loading logic.
+
+### `after_controller_load`
+**Type:** Filter  
+**Description:** Executes after loading a controller.  
+**Parameters:** `({ controllerModule, controllerPath }, controllerModule, controllerPath)`  
+**Usage:** To decorate controllers, apply post-loading logic, or modify controller modules.
+
+## Route Hooks
+
+### `route_registered`
+**Type:** Action  
+**Description:** Triggered when a new route is registered.  
+**Parameters:** `(route)`  
+**Usage:** To maintain active route records or apply post-registration logic.
+
+## Static File Hooks
+
+### `pre_static_file_serve`
+**Type:** Action and Filter  
+**Description:** Triggered before serving a static file.  
+**Parameters:** `(req, res, staticConfig, routePath)`  
+**Filter Parameters:** `({ req, res, staticConfig, routePath }, req, res, staticConfig, routePath)`  
+**Usage:** For permission checks or pre-delivery logic.
+
+### `static_file_access_denied`
+**Type:** Action  
+**Description:** Triggered when access to a static file is denied.  
+**Parameters:** `(req, res, normalizedPath)`  
+**Usage:** To register denied accesses or apply security measures.
+
+### `serving_index_file`
+**Type:** Action  
+**Description:** Triggered when serving an index file (like index.html).  
+**Parameters:** `(indexPath, req, res)`  
+**Usage:** To register access to main pages.
+
+### `static_file_served`
+**Type:** Action  
+**Description:** Triggered after serving a static file.  
+**Parameters:** `(filePath, req, res)`  
+**Usage:** To register static file access or apply auditing.
+
+### `static_file_not_found`
+**Type:** Action  
+**Description:** Triggered when a static file is not found.  
+**Parameters:** `(filePath, req, res)`  
+**Usage:** To register missing files or apply fallback logic.
+
+### `static_directory_no_index`
+**Type:** Action  
+**Description:** Triggered when accessing a directory without an index file.  
+**Parameters:** `(dirPath, req, res)`  
+**Usage:** To register directory accesses or apply directory logic.
+
+### `before_reading_static_file`
+**Type:** Action  
+**Description:** Triggered before reading a static file from disk.  
+**Parameters:** `(filePath, req, res)`  
+**Usage:** To apply pre-read logic.
+
+## Controller Hooks
+
+### `pre_controller_load` (DEPRECATED)
+**Type:** Action  
+**Description:** Triggered before loading a controller (will be removed in future versions).  
+**Parameters:** `(controllerPath)`  
+**Usage:** To apply pre-loading logic to controllers (use `before_controller_load` instead).
+
+### `post_controller_load` (DEPRECATED)
+**Type:** Action  
+**Description:** Triggered after loading a controller (will be removed in future versions).  
+**Parameters:** `(controllerModule, controllerPath)`  
+**Usage:** To apply post-loading logic to controllers (use `after_controller_load` instead).
+
+### `controller_registered_with_model`
+**Type:** Action  
+**Description:** Triggered when a controller is registered with a model.  
+**Parameters:** `(controllerName, modelName)`  
+**Usage:** To maintain relationships between controllers and models.
+
+### `controller_unregistered_from_model`
+**Type:** Action  
+**Description:** Triggered when a controller is unregistered from a model.  
+**Parameters:** `(controllerName, modelName)`  
+**Usage:** To clean up relationships between controllers and models.
+
+## Request Hooks
+
+### `framework_init`
+**Type:** Action  
+**Description:** Triggered during framework initialization.  
+**Parameters:** None  
+**Usage:** To initialize global components or apply initial configurations.
+
+## Server Hooks
+
+### `server_started`
+**Type:** Action  
+**Description:** Triggered when the server starts.  
+**Parameters:** `(server)`  
+**Usage:** To apply post-server startup logic.
+
+### `server_stopped`
+**Type:** Action  
+**Description:** Triggered when the server stops.  
+**Parameters:** `(server)`  
+**Usage:** To apply cleanup or shutdown logic.
+
+### `server_pre_start`
+**Type:** Action  
+**Description:** Triggered before starting the server.  
+**Parameters:** `(server)`  
+**Usage:** To apply pre-startup configurations.
+
+### `server_post_start`
+**Type:** Action  
+**Description:** Triggered after starting the server.  
+**Parameters:** `(server)`  
+**Usage:** To apply post-startup logic.
+
+## View Hooks
+
+### `view_rendered`
+**Type:** Action  
+**Description:** Triggered after rendering a view.  
+**Parameters:** `(viewName, data, req, res)`  
+**Usage:** To register rendered views or apply post-rendering logic.
+
+### `view_render_error`
+**Type:** Action  
+**Description:** Triggered when an error occurs while rendering a view.  
+**Parameters:** `(viewName, data, req, res, error)`  
+**Usage:** To handle view rendering errors.
+
+## Statistics Hooks
+
+### `stats_updated`
+**Type:** Action  
+**Description:** Triggered when server statistics are updated.  
+**Parameters:** `(stats)`  
+**Usage:** To register or process updated statistics.
+
+### `request_bytes_updated`
+**Type:** Action  
+**Description:** Triggered when request bytes are updated.  
+**Parameters:** `(bytes)`  
+**Usage:** To monitor incoming traffic.
+
+### `response_bytes_updated`
+**Type:** Action  
+**Description:** Triggered when response bytes are updated.  
+**Parameters:** `(bytes)`  
+**Usage:** To monitor outgoing traffic.
+
+### `requests_processed_updated`
+**Type:** Action  
+**Description:** Triggered when the processed requests counter is updated.  
+**Parameters:** `()`  
+**Usage:** To monitor request volume.
+
+### `responses_sent_updated`
+**Type:** Action  
+**Description:** Triggered when the sent responses counter is updated.  
+**Parameters:** `()`  
+**Usage:** To monitor response volume.
+
+### `route_access_registered`
+**Type:** Action  
+**Description:** Triggered when route access is registered.  
+**Parameters:** `(req)`  
+**Usage:** To monitor route usage.
+
+### `endpoint_hit_registered`
+**Type:** Action  
+**Description:** Triggered when an endpoint hit is registered.  
+**Parameters:** `(matchedRoute)`  
+**Usage:** To monitor usage of specific endpoints.
+
+## Security Hooks
+
+### `waf_request_processed`
+**Type:** Action  
+**Description:** Triggered when the WAF processes a request.  
+**Parameters:** `(req, res, action)`  
+**Usage:** To monitor firewall actions.
+
+### `security_check_performed`
+**Type:** Action  
+**Description:** Triggered when a security check is performed.  
+**Parameters:** `(req, checkType, result)`  
+**Usage:** To register security checks.
+
+## Administration Hooks
+
+### `admin_route_active`
+**Type:** Action  
+**Description:** Triggered when an active route is registered in the administration system.  
+**Parameters:** `(routeInfo)`  
+**Usage:** To maintain records of active routes in the admin panel.
+
+## Queue System Hooks
+
+### `queue_task_added`
+**Type:** Action  
+**Description:** Triggered when a task is added to a queue.  
+**Parameters:** `(task, queueName)`  
+**Usage:** To monitor addition of tasks to queues.
+
+### `queue_task_executed`
+**Type:** Action  
+**Description:** Triggered when a queue task is executed.  
+**Parameters:** `(task, queueName)`  
+**Usage:** To monitor execution of tasks.
+
+### `queue_task_failed`
+**Type:** Action  
+**Description:** Triggered when a queue task fails.  
+**Parameters:** `(task, queueName, error)`  
+**Usage:** To handle queue task failures.
+
+## Model Hooks
+
+### `model_loaded`
+**Type:** Action  
+**Description:** Triggered when a model is loaded.  
+**Parameters:** `(modelName, modelInstance)`  
+**Usage:** To register model loading or apply post-loading logic.
+
+### `model_saved`
+**Type:** Action  
+**Description:** Triggered when a model is saved.  
+**Parameters:** `(modelName, modelInstance, data)`  
+**Usage:** To register save operations or apply post-save logic.
+
+### `model_deleted`
+**Type:** Action  
+**Description:** Triggered when a model is deleted.  
+**Parameters:** `(modelName, modelInstance, id)`  
+**Usage:** To register deletion operations or apply post-delete logic.
+
+## Session Hooks
+
+### `session_created`
+**Type:** Action  
+**Description:** Triggered when a session is created.  
+**Parameters:** `(sessionId, sessionData)`  
+**Usage:** To register session creation or apply post-creation logic.
+
+### `session_destroyed`
+**Type:** Action  
+**Description:** Triggered when a session is destroyed.  
+**Parameters:** `(sessionId)`  
+**Usage:** To register session destruction or apply cleanup logic.
+
+## Authentication Hooks
+
+### `authentication_success`
+**Type:** Action  
+**Description:** Triggered when an authentication is successful.  
+**Parameters:** `(user, req)`  
+**Usage:** To register successful authentications or apply post-authentication logic.
+
+### `authentication_failure`
+**Type:** Action  
+**Description:** Triggered when an authentication fails.  
+**Parameters:** `(credentials, req, reason)`  
+**Usage:** To register authentication failures or apply security measures.
+
+## Middleware Hooks
+
+### `middleware_executed`
+**Type:** Action  
+**Description:** Triggered when a middleware is executed.  
+**Parameters:** `(middleware, req, res)`  
+**Usage:** To register middleware execution or apply post-execution logic.
+
+## Cache Hooks
+
+### `cache_hit`
+**Type:** Action  
+**Description:** Triggered when a cached element is found.  
+**Parameters:** `(key, value)`  
+**Usage:** To monitor cache effectiveness.
+
+### `cache_miss`
+**Type:** Action  
+**Description:** Triggered when a cached element is not found.  
+**Parameters:** `(key)`  
+**Usage:** To monitor cache misses.
+
+### `cache_set`
+**Type:** Action  
+**Description:** Triggered when a value is set in cache.  
+**Parameters:** `(key, value, ttl)`  
+**Usage:** To register cache write operations.
+
+### `cache_delete`
+**Type:** Action  
+**Description:** Triggered when a value is deleted from cache.  
+**Parameters:** `(key)`  
+**Usage:** To register cache deletion operations.
+
+## Database Hooks
+
+### `db_query_executed`
+**Type:** Action  
+**Description:** Triggered when a database query is executed.  
+**Parameters:** `(query, params, executionTime)`  
+**Usage:** To monitor database queries or apply auditing.
+
+### `db_connection_acquired`
+**Type:** Action  
+**Description:** Triggered when a database connection is acquired.  
+**Parameters:** `(connectionId)`  
+**Usage:** To monitor connection usage.
+
+### `db_connection_released`
+**Type:** Action  
+**Description:** Triggered when a database connection is released.  
+**Parameters:** `(connectionId)`  
+**Usage:** To monitor connection release.
+
+## Using Hooks and Filters
+
+### Registering an Action Hook
+```javascript
+hooks.addAction('request_received', (req, res) => {
+  console.log(`Request received: ${req.method} ${req.url}`);
+}, 10, 2);
+```
+
+### Registering a Filter
+```javascript
+hooks.addFilter('before_route_handler', (data, req, res, matchedRoute) => {
+  req.startTime = Date.now();
+  return {
+    ...data,
+    req: req
+  };
+}, 10, 3);
+```
+
+### Registration Parameters
+- `hookName`: Name of the hook
+- `callback`: Function to execute
+- `priority`: Priority (lower number executes first)
+- `acceptedArgs`: Number of accepted arguments
+- `identifier`: Optional identifier for the callback
+
+## Common Priorities
+- 1-10: Critical validation and security
+- 11-30: Authentication and authorization
+- 31-50: Context preparation
+- 51-70: Business logic
+- 71-90: Auditing and logging
+- 91-100: Cleanup and post-processing
+
+## Performance Considerations
+- Synchronous hooks execute in order and can block
+- Asynchronous hooks resolve in order but don't block
+- Recommended to use appropriate priorities to control execution order
+- Filters must always return a value to maintain the chain

package/manuales/hooks_vs_middlewares_comparison.md

@@ -0,0 +1,87 @@
+# Hooks vs Middlewares
+
+## Comparación entre Hooks y Middlewares en el Framework Insitu
+
+### Middlewares
+
+#### Ventajas:
+- **Fáciles para principiantes**: Sintaxis familiar similar a otros frameworks
+- **Ejecución lineal**: Secuencia predecible de ejecución
+- **Interceptan solicitudes**: Pueden modificar `req` y `res` antes de llegar al handler
+- **Útiles para autenticación**: Ideal para verificar credenciales antes de procesar rutas
+- **Manejo de errores centralizado**: Pueden capturar errores de forma temprana
+
+#### Desventajas:
+- **Ejecución lineal rígida**: No se puede alterar fácilmente el flujo
+- **Menos flexibilidad**: Solo se pueden aplicar en puntos específicos del flujo
+- **Dependencia del orden**: El comportamiento puede depender del orden de registro
+- **Menos granularidad**: No permiten puntos de extensión tan específicos
+
+### Hooks
+
+#### Ventajas:
+- **Mayor control para expertos**: Permite personalización precisa del comportamiento
+- **Prioridades configurables**: Se puede definir el orden exacto de ejecución
+- **Puntos de extensión específicos**: Se pueden insertar en momentos precisos del ciclo de vida
+- **Flexibilidad extrema**: Se pueden aplicar tanto como acciones como filtros
+- **Orquestación fina**: Permite coordinar múltiples componentes de forma precisa
+- **Separación de responsabilidades**: Cada hook tiene un propósito bien definido
+
+#### Desventajas:
+- **Curva de aprendizaje más pronunciada**: Requiere comprensión más profunda del sistema
+- **Complejidad**: Puede ser sobrecargado para casos simples
+- **Dependencia del conocimiento del sistema**: Se necesita entender los puntos de extensión
+
+### Casos de uso recomendados
+
+#### Middlewares:
+- Autenticación y autorización
+- Logging de solicitudes
+- Parsing de cuerpos de solicitud
+- CORS y seguridad básica
+- Manejo de sesiones
+
+#### Hooks:
+- Modificación de comportamiento interno del framework
+- Integración profunda con sistemas externos
+- Auditoría detallada
+- Personalización de respuesta
+- Manipulación de contenido de archivos estáticos
+- Extensión de funcionalidades del sistema
+
+### Ejemplo práctico
+
+#### Middleware para autenticación:
+```javascript
+const authMiddleware = (req, res, next) => {
+  if (!req.headers.authorization) {
+    res.writeHead(401);
+    res.end('Unauthorized');
+    return;
+  }
+  next();
+};
+server.use('/protected', authMiddleware);
+```
+
+#### Hook para manipulación de archivos estáticos:
+```javascript
+// Modificar contenido de archivos HTML antes de enviarlos
+hooks.addFilter('after_static_file_load', (data, req, res, filePath, staticConfig, fileContent) => {
+  if (filePath.endsWith('.html')) {
+    let content = data.fileContent.toString();
+    // Inyectar script de analytics
+    content = content.replace('</body>', '<script src="/analytics.js"></script></body>');
+    return {
+      ...data,
+      fileContent: Buffer.from(content)
+    };
+  }
+  return data;
+});
+```
+
+### Conclusión
+
+- **Middlewares**: Ideales para developers que buscan soluciones rápidas y sencillas, especialmente para tareas de preprocesamiento de solicitudes.
+- **Hooks**: Potentes herramientas para desarrolladores avanzados que necesitan control preciso sobre el comportamiento del framework en puntos específicos del ciclo de vida de las solicitudes y otros procesos.