@reldens/server-utils 0.43.0 → 0.44.0

package/CLAUDE.md

@@ -21,242 +21,74 @@ npm test
 
 ## Architecture
 
-### Core Classes
+See `.claude/package-architecture.md` for detailed information about:
+- Design philosophy and independence principles
+- Callback-based extensibility pattern
+- Available callbacks (onError, onRequestSuccess, onRequestError, onEvent)
+- Integration patterns
 
-**FileHandler** (`lib/file-handler.js`):
-- Singleton wrapper for Node.js fs and path modules
-- Used instead of direct require('fs') or require('path') throughout Reldens
-- Key file operations:
-  - `exists(filePath)` - Check if file/directory exists
-  - `readFile(filePath)` - Read file contents
-  - `writeFile(filePath, content)` - Write file
-  - `createFolder(folderPath)` - Create directory recursively
-  - `remove(fullPath)` - Remove file/folder recursively
-  - `copyFile(from, to)` - Copy file
-  - `copyFolderSync(from, to)` - Copy folder recursively
-  - `moveFile(from, to)` - Move/rename file
-- Path operations:
-  - `joinPaths(...paths)` - Join path segments
-  - `getFileName(filePath)` - Get file name (basename)
-  - `getFolderName(filePath)` - Get directory name (dirname)
-  - `getRelativePath(from, to)` - Calculate relative path
-  - `normalizePath(filePath)` - Normalize path
-  - `isAbsolutePath(filePath)` - Check if path is absolute
-- File inspection:
-  - `isFile(filePath)` - Check if path is a file
-  - `isFolder(dirPath)` - Check if path is a folder
-  - `getFileSize(filePath)` - Get file size in bytes
-  - `getFileStats(filePath)` - Get file stats
-  - `getFilesInFolder(dirPath, extensions)` - List files with optional filtering
-  - `fetchSubFoldersList(folder, options)` - Get subfolder list
-- JSON operations:
-  - `fetchFileJson(filePath)` - Read and parse JSON file
-  - `isValidJson(filePath)` - Validate JSON file
-- Security features:
-  - `generateSecureFilename(originalName)` - Generate secure random filename
-  - `validateFileType(filePath, type, allowedTypes, maxSize)` - Validate file
-  - `detectFileType(filePath)` - Detect MIME type from magic numbers
-  - `quarantineFile(filePath, reason)` - Move suspicious file to quarantine
-  - `isValidPath(filePath)` - Validate path for security
-  - `sanitizePath(filePath)` - Sanitize path string
-- Advanced operations:
-  - `walkDirectory(dirPath, callback)` - Recursively process directory tree
-  - `getDirectorySize(dirPath)` - Calculate total directory size
-  - `emptyDirectory(dirPath)` - Remove all contents from directory
-  - `compareFiles(file1, file2)` - Compare file contents
-  - `appendToFile(filePath, content)` - Append to file
-  - `prependToFile(filePath, content)` - Prepend to file
-  - `replaceInFile(filePath, searchValue, replaceValue)` - Replace in file
-  - `createReadStream(filePath, options)` - Create readable stream for file
-  - `getFileModificationTime(filePath)` - Get file last modification time
-- All methods include built-in error handling, no need for try/catch
-- DO NOT use FileHandler.exists to validate other FileHandler methods
-- DO NOT enclose FileHandler methods in try/catch blocks
-
-**AppServerFactory** (`lib/app-server-factory.js`):
-- Creates Express app servers with modular security components
-- Supports HTTP, HTTPS, HTTP/2
-- Key features:
-  - Virtual host management with SNI support
-  - HTTP/2 CDN server integration
-  - Reverse proxy with WebSocket support
-  - Development mode detection and configuration
-  - Custom error handling via onError callback
-- Security configurers (modular):
-  - `DevelopmentModeDetector` - Auto-detect development environment
-  - `ProtocolEnforcer` - HTTP/HTTPS protocol enforcement
-  - `SecurityConfigurer` - Helmet integration and XSS protection
-  - `CorsConfigurer` - CORS with dynamic origin validation
-  - `RateLimitConfigurer` - Global and endpoint-specific rate limiting
-  - `ReverseProxyConfigurer` - Domain-based reverse proxy
-- Configuration properties:
-  - `onError` - Custom error handler callback for server errors
-- Methods:
-  - `createAppServer(config)` - Create and configure server
-  - `addDomain(domainConfig)` - Add virtual host domain
-  - `addDevelopmentDomain(domain)` - Add development domain
-  - `enableServeHome(app, callback)` - Enable homepage serving
-  - `serveStatics(app, staticPath)` - Serve static files
-  - `enableCSP(cspOptions)` - Enable Content Security Policy
-  - `listen(port)` - Start server listening
-  - `close()` - Gracefully close server
+See `.claude/api-reference.md` for complete API documentation of all classes and methods.
 
-**Encryptor** (`lib/encryptor.js`):
-- Singleton for cryptographic operations
-- Password hashing:
-  - `encryptPassword(password)` - Hash password with PBKDF2 (100k iterations, SHA-512)
-  - `validatePassword(password, storedPassword)` - Validate password against hash
-- Data encryption:
-  - `encryptData(data, key)` - Encrypt data with AES-256-GCM
-  - `decryptData(encryptedData, key)` - Decrypt AES-256-GCM data
-  - `generateSecretKey()` - Generate 256-bit secret key
-- Token generation:
-  - `generateSecureToken(length)` - Generate cryptographically secure token
-  - `generateTOTP(secret, timeStep)` - Generate time-based OTP
-- Hashing and verification:
-  - `hashData(data, algorithm)` - Hash with SHA-256, SHA-512, or MD5
-  - `generateHMAC(data, secret, algorithm)` - Generate HMAC signature
-  - `verifyHMAC(data, secret, signature, algorithm)` - Verify HMAC signature
-  - `constantTimeCompare(a, b)` - Constant-time string comparison
+## Core Classes Summary
 
-**UploaderFactory** (`lib/uploader-factory.js`):
-- File upload handling with Multer
-- Multi-level security validation:
-  - Filename security validation
-  - MIME type validation
-  - File extension validation
-  - File size validation
-  - Content validation using magic numbers
-  - Dangerous extension filtering
-- Features:
-  - Multiple file upload support with field mapping
-  - Secure filename generation option
-  - Automatic cleanup on validation failure
-  - Custom error response handling
-  - Per-field destination mapping
-- Methods:
-  - `createUploader(fields, buckets, allowedFileTypes)` - Create upload middleware
-  - `validateFilenameSecurity(filename)` - Validate filename
-  - `validateFile(file, allowedType, callback)` - Validate during upload
-  - `validateFileContents(file, allowedType)` - Validate after upload
-  - `convertToRegex(key)` - Convert MIME type patterns to regex
+**FileHandler** - Singleton wrapper for Node.js fs and path modules. Used instead of direct require('fs') or require('path') throughout Reldens.
 
-**Http2CdnServer** (`lib/http2-cdn-server.js`):
-- HTTP/2 secure server for CDN-like static file serving
-- Features:
-  - Optimized for CSS, JavaScript, images, and fonts
-  - Dynamic CORS origin validation with regex pattern support
-  - Configurable cache headers per file extension
-  - Comprehensive MIME type detection
-  - HTTP/1.1 fallback support
-  - Security headers (X-Content-Type-Options, X-Frame-Options, Vary)
-  - Query string stripping for cache optimization
-  - Comprehensive error handling (server, TLS, session, stream errors)
-  - Custom error handler callback support
-- Configuration properties:
-  - `onError` - Custom error handler callback for server errors
-- Methods:
-  - `create()` - Create HTTP/2 secure server
-  - `listen()` - Start listening on configured port
-  - `close()` - Gracefully close server
-  - `handleStream(stream, headers)` - Handle HTTP/2 stream
-  - `handleHttp1Request(req, res)` - Handle HTTP/1.1 fallback requests
-  - `resolveFilePath(requestPath)` - Resolve file path from request
-  - `setupEventHandlers()` - Configure server error event handlers
+**AppServerFactory** - Creates Express app servers with modular security components. Supports HTTP, HTTPS, HTTP/2, virtual hosts, CDN integration, reverse proxy, and callback-based logging.
 
-### Utility Classes
+**Encryptor** - Singleton for cryptographic operations including password hashing, data encryption, token generation, and HMAC verification.
 
-**ServerErrorHandler** (`lib/server-error-handler.js`):
-- Centralized error handling for all server components
-- Static class with standardized error handling interface
-- Methods:
-  - `handleError(onErrorCallback, instanceName, instance, key, error, context)` - Handle and delegate errors
-- Used by Http2CdnServer, AppServerFactory, and ReverseProxyConfigurer
-- Supports custom error callbacks for application-specific error processing
-- Provides structured error context with instance details and metadata
+**UploaderFactory** - File upload handling with Multer and multi-level security validation.
 
-**ServerDefaultConfigurations** (`lib/server-default-configurations.js`):
-- Static class providing default configurations
-- `mimeTypes` - Comprehensive MIME type mappings for common file extensions
-- `cacheConfig` - Default cache max-age settings (1 year for CSS/JS/fonts, 30 days for images)
+**Http2CdnServer** - HTTP/2 secure server for CDN-like static file serving with CORS, cache headers, and callback-based logging.
 
-**ServerFactoryUtils** (`lib/server-factory-utils.js`):
-- Static utility methods for server operations
-- `getCacheConfigForPath(path, cacheConfig)` - Get cache config for file path
-- `validateOrigin(origin, corsOrigins, corsAllowAll)` - Validate CORS origin (supports strings and RegExp)
-- `stripQueryString(url)` - Remove query string from URL
+## Utility Classes Summary
 
-**ServerHeaders** (`lib/server-headers.js`):
-- Centralized header management
-- HTTP/2 headers configuration
-- Express security headers
-- Cache control headers
-- Proxy forwarding headers
-- `buildCacheControlHeader(maxAge)` - Build cache control header string
+**RequestLogger** - Express middleware for request logging that invokes callbacks based on status codes.
 
-### Security Configurers (in `lib/app-server-factory/`)
+**EventDispatcher** - Static utility for dispatching lifecycle events with structured event data.
 
-**DevelopmentModeDetector** (`development-mode-detector.js`):
-- Auto-detects development environment
-- Checks NODE_ENV, domain patterns, and configured domains
-- Built-in patterns: localhost, 127.0.0.1, .local, .test, .dev, .staging, etc.
-- `detect(config)` - Detect if in development mode
-- `matchesPattern(domain)` - Check if domain matches development pattern
+**ServerErrorHandler** - Centralized error handling with structured error context.
 
-**ProtocolEnforcer** (`protocol-enforcer.js`):
-- Enforces HTTP/HTTPS protocol consistency
-- Development mode awareness
-- Automatic redirects when protocol doesn't match configuration
-- `setup(app, config)` - Setup protocol enforcement middleware
+**ServerDefaultConfigurations** - Static class providing MIME types and cache configurations.
 
-**SecurityConfigurer** (`security-configurer.js`):
-- Helmet integration with CSP management
-- XSS protection with request body sanitization
-- Development-friendly CSP configuration
-- Supports CSP directive merging or override
-- `setupHelmet(app, config)` - Setup Helmet middleware
-- `setupXssProtection(app, config)` - Setup XSS protection
-- `enableCSP(app, cspOptions)` - Enable Content Security Policy
-- `addExternalDomainsToCsp(directives, externalDomains)` - Add external domains to CSP
+**ServerFactoryUtils** - Static utility methods for cache config, CORS validation, and URL manipulation.
 
-**CorsConfigurer** (`cors-configurer.js`):
-- Dynamic CORS origin validation
-- Development domain support with automatic port variations
-- Credential support configuration
-- `setup(app, config)` - Setup CORS middleware
-- `extractDevelopmentOrigins(domainMapping)` - Extract development origins
-- `normalizeHost(originOrHost)` - Normalize host string
+**ServerHeaders** - Centralized header management for HTTP/2, security, cache, and proxy headers.
 
-**RateLimitConfigurer** (`rate-limit-configurer.js`):
-- Global and endpoint-specific rate limiting
-- Development mode multiplier for lenient limits
-- IP-based key generation option
-- `setup(app, config)` - Setup global rate limiting
-- `createHomeLimiter()` - Create homepage-specific limiter
+## Security Configurers Summary
 
-**ReverseProxyConfigurer** (`reverse-proxy-configurer.js`):
-- Domain-based reverse proxy routing
-- WebSocket support
-- SSL termination
-- Header preservation (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host)
-- Virtual host integration
-- Comprehensive error handling with proper HTTP status codes:
-  - 502 Bad Gateway for ECONNREFUSED errors
-  - 504 Gateway Timeout for ETIMEDOUT/ESOCKETTIMEDOUT errors
-  - 500 Internal Server Error for other proxy errors
-- Custom error callback support via ServerErrorHandler
-- Methods:
-  - `setup(app, config)` - Setup reverse proxy
-  - `createProxyMiddleware(rule)` - Create proxy middleware for rule
-  - `handleProxyError(err, req, res)` - Handle proxy errors with status codes
-  - `validateProxyRule(rule)` - Validate proxy rule configuration
-  - `extractHostname(req)` - Extract hostname from request
+Located in `lib/app-server-factory/`:
+- **DevelopmentModeDetector** - Auto-detect development environment
+- **ProtocolEnforcer** - HTTP/HTTPS protocol enforcement
+- **SecurityConfigurer** - Helmet integration and XSS protection
+- **CorsConfigurer** - CORS with dynamic origin validation
+- **RateLimitConfigurer** - Global and endpoint-specific rate limiting
+- **ReverseProxyConfigurer** - Domain-based reverse proxy with WebSocket support
 
 ## Important Notes
 
+### FileHandler Usage
 - **ALWAYS use FileHandler** instead of Node.js fs/path modules
 - FileHandler methods have built-in error handling - no try/catch needed
 - DO NOT enclose FileHandler methods in try/catch blocks
 - DO NOT use FileHandler.exists to validate other FileHandler methods (e.g., before createFolder)
+
+### Callback System
+- Package provides callback hooks (onError, onRequestSuccess, onRequestError, onEvent)
+- Applications provide implementations via configuration
+- Package does NOT import @reldens/utils Logger
+- Applications wire callbacks to their own logging/monitoring systems
+
+### Server Configuration
 - AppServerFactory handles all Express server configuration
 - All server utilities support both HTTP and HTTPS
+- Virtual hosts with SNI support for multiple domains
+- HTTP/2 CDN server integration for static file serving
+- Reverse proxy with WebSocket support
+
+### Security
+- Multi-level validation for file uploads
+- XSS protection with request body sanitization
+- CSP management with Helmet integration
+- CORS with dynamic origin validation (supports strings and RegExp)
+- Rate limiting with development mode awareness

package/lib/app-server-factory/cors-configurer.js

@@ -5,6 +5,7 @@
  */
 
 const cors = require('cors');
+const { EventDispatcher } = require('../event-dispatcher');
 
 class CorsConfigurer
 {
@@ -18,6 +19,7 @@ class CorsConfigurer
         this.corsHeaders = ['Content-Type','Authorization'];
         this.developmentCorsOrigins = [];
         this.developmentPorts = [];
+        this.onEvent = null;
     }
 
     setup(app, config)
@@ -28,6 +30,7 @@ class CorsConfigurer
         this.corsMethods = config.corsMethods || this.corsMethods;
         this.corsHeaders = config.corsHeaders || this.corsHeaders;
         this.developmentPorts = config.developmentPorts || this.developmentPorts;
+        this.onEvent = config.onEvent || null;
         if(!this.useCors){
             return;
         }
@@ -58,6 +61,13 @@ class CorsConfigurer
             };
         }
         app.use(cors(corsOptions));
+        EventDispatcher.dispatch(
+            this.onEvent,
+            'cors-configured',
+            'corsConfigurer',
+            this,
+            {useCors: this.useCors, isDevelopmentMode: this.isDevelopmentMode, corsOrigin: this.corsOrigin}
+        );
     }
 
     extractDevelopmentOrigins(domainMapping)

package/lib/app-server-factory/development-mode-detector.js

@@ -4,6 +4,8 @@
  *
  */
 
+const { EventDispatcher } = require('../event-dispatcher');
+
 class DevelopmentModeDetector
 {
 
@@ -27,10 +29,12 @@ class DevelopmentModeDetector
         ];
         this.developmentEnvironments = ['development', 'dev', 'test'];
         this.env = process?.env?.NODE_ENV || 'production';
+        this.onEvent = null;
     }
 
     detect(config = {})
     {
+        this.onEvent = config.onEvent || null;
         if(config.developmentPatterns){
             this.developmentPatterns = config.developmentPatterns;
         }
@@ -38,11 +42,25 @@ class DevelopmentModeDetector
             this.developmentEnvironments = config.developmentEnvironments;
         }
         if(this.developmentEnvironments.includes(this.env)){
+            EventDispatcher.dispatch(
+                this.onEvent,
+                'development-mode-detected',
+                'developmentModeDetector',
+                this,
+                {detectionMethod: 'environment', env: this.env}
+            );
             return true;
         }
         if(config.developmentDomains && 0 < config.developmentDomains.length){
             for(let domain of config.developmentDomains){
                 if(this.matchesPattern(domain)){
+                    EventDispatcher.dispatch(
+                        this.onEvent,
+                        'development-mode-detected',
+                        'developmentModeDetector',
+                        this,
+                        {detectionMethod: 'developmentDomain', domain: domain}
+                    );
                     return true;
                 }
             }
@@ -53,6 +71,13 @@ class DevelopmentModeDetector
                     continue;
                 }
                 if(this.matchesPattern(domainConfig.hostname)){
+                    EventDispatcher.dispatch(
+                        this.onEvent,
+                        'development-mode-detected',
+                        'developmentModeDetector',
+                        this,
+                        {detectionMethod: 'domainPattern', hostname: domainConfig.hostname}
+                    );
                     return true;
                 }
             }

package/lib/app-server-factory/protocol-enforcer.js

@@ -4,6 +4,8 @@
  *
  */
 
+const { EventDispatcher } = require('../event-dispatcher');
+
 class ProtocolEnforcer
 {
 
@@ -12,6 +14,7 @@ class ProtocolEnforcer
         this.isDevelopmentMode = false;
         this.useHttps = false;
         this.enforceProtocol = true;
+        this.onEvent = null;
     }
 
     setup(app, config)
@@ -19,6 +22,7 @@ class ProtocolEnforcer
         this.isDevelopmentMode = config.isDevelopmentMode || false;
         this.useHttps = config.useHttps || false;
         this.enforceProtocol = config.enforceProtocol !== false;
+        this.onEvent = config.onEvent || null;
         app.use((req, res, next) => {
             let forwardedProto = req.get('X-Forwarded-Proto');
             let protocol = (forwardedProto || req.protocol || '').toLowerCase();
@@ -41,6 +45,13 @@ class ProtocolEnforcer
             res.set('X-Forwarded-Proto', protocol);
             next();
         });
+        EventDispatcher.dispatch(
+            this.onEvent,
+            'protocol-enforcement-enabled',
+            'protocolEnforcer',
+            this,
+            {isDevelopmentMode: this.isDevelopmentMode, useHttps: this.useHttps, enforceProtocol: this.enforceProtocol}
+        );
     }
 
 }

package/lib/app-server-factory/rate-limit-configurer.js

@@ -5,6 +5,7 @@
  */
 
 const rateLimit = require('express-rate-limit');
+const { EventDispatcher } = require('../event-dispatcher');
 
 class RateLimitConfigurer
 {
@@ -19,6 +20,7 @@ class RateLimitConfigurer
         this.applyKeyGenerator = false;
         this.tooManyRequestsMessage = 'Too many requests, please try again later.';
         this.rateLimit = rateLimit;
+        this.onEvent = null;
     }
 
     setup(app, config)
@@ -30,6 +32,7 @@ class RateLimitConfigurer
         this.developmentMultiplier = Number(config.developmentMultiplier || this.developmentMultiplier);
         this.applyKeyGenerator = config.applyKeyGenerator || false;
         this.tooManyRequestsMessage = config.tooManyRequestsMessage || this.tooManyRequestsMessage;
+        this.onEvent = config.onEvent || null;
         if(!this.globalRateLimit){
             return;
         }
@@ -49,6 +52,13 @@ class RateLimitConfigurer
             };
         }
         app.use(this.rateLimit(limiterParams));
+        EventDispatcher.dispatch(
+            this.onEvent,
+            'rate-limiting-configured',
+            'rateLimitConfigurer',
+            this,
+            {globalRateLimit: this.globalRateLimit, maxRequests: limiterParams.limit, windowMs: this.windowMs}
+        );
     }
 
     createHomeLimiter()

package/lib/app-server-factory/reverse-proxy-configurer.js

@@ -7,6 +7,7 @@
 const { createProxyMiddleware } = require('http-proxy-middleware');
 const { ServerHeaders } = require('../server-headers');
 const { ServerErrorHandler } = require('../server-error-handler');
+const { EventDispatcher } = require('../event-dispatcher');
 
 class ReverseProxyConfigurer
 {
@@ -24,6 +25,7 @@ class ReverseProxyConfigurer
         };
         this.serverHeaders = new ServerHeaders();
         this.onError = null;
+        this.onEvent = null;
     }
 
     setup(app, config)
@@ -33,10 +35,18 @@ class ReverseProxyConfigurer
         this.reverseProxyRules = config.reverseProxyRules || [];
         this.reverseProxyOptions = config.reverseProxyOptions || this.reverseProxyOptions;
         this.onError = config.onError || null;
+        this.onEvent = config.onEvent || null;
         if(0 === this.reverseProxyRules.length){
             return;
         }
         this.applyRules(app);
+        EventDispatcher.dispatch(
+            this.onEvent,
+            'reverse-proxy-configured',
+            'reverseProxyConfigurer',
+            this,
+            {rulesCount: this.reverseProxyRules.length, useVirtualHosts: this.useVirtualHosts}
+        );
     }
 
     applyRules(app)

package/lib/app-server-factory/security-configurer.js

@@ -6,6 +6,7 @@
 
 const helmet = require('helmet');
 const sanitizeHtml = require('sanitize-html');
+const { EventDispatcher } = require('../event-dispatcher');
 
 class SecurityConfigurer
 {
@@ -18,15 +19,24 @@ class SecurityConfigurer
         this.helmetConfig = false;
         this.helmetOptions = {};
         this.sanitizeOptions = {allowedTags: [], allowedAttributes: {}};
+        this.onEvent = null;
     }
 
     setupHelmet(app, config)
     {
         this.useHelmet = config.useHelmet !== false;
+        this.onEvent = config.onEvent || null;
         if(!this.useHelmet){
             return;
         }
         app.use(helmet(this.mapHelmetOptions(config)));
+        EventDispatcher.dispatch(
+            this.onEvent,
+            'helmet-configured',
+            'securityConfigurer',
+            this,
+            {useHelmet: this.useHelmet, isDevelopmentMode: this.isDevelopmentMode}
+        );
     }
 
     mapHelmetOptions(config)
@@ -131,6 +141,7 @@ class SecurityConfigurer
     {
         this.useXssProtection = config.useXssProtection !== false;
         this.sanitizeOptions = config.sanitizeOptions || this.sanitizeOptions;
+        this.onEvent = config.onEvent || null;
         if(!this.useXssProtection){
             return;
         }
@@ -143,6 +154,13 @@ class SecurityConfigurer
             }
             next();
         });
+        EventDispatcher.dispatch(
+            this.onEvent,
+            'xss-protection-enabled',
+            'securityConfigurer',
+            this,
+            {useXssProtection: this.useXssProtection}
+        );
     }
 
     sanitizeRequestBody(body)