webspresso 0.0.103 → 0.0.105

package/core/errors/domain.js

@@ -180,6 +180,51 @@ class RouteGenerationError extends RouterError {
   }
 }
 
+/**
+ * Circuit Breaker Open Error
+ * Thrown when an invocation is rejected because the circuit is in the OPEN state.
+ * Maps to HTTP 503 Service Unavailable.
+ */
+class CircuitBreakerOpenError extends HttpError {
+  /**
+   * @param {string} [breakerName='default']
+   * @param {number} [resetTimeoutMs=0]
+   * @param {Object} [options]
+   */
+  constructor(breakerName = 'default', resetTimeoutMs = 0, options = {}) {
+    super(503, `Circuit breaker '${breakerName}' is OPEN and failing fast`, {
+      code: 'CIRCUIT_BREAKER_OPEN',
+      expose: true,
+      ...options,
+    });
+    this.breakerName = breakerName;
+    this.resetTimeoutMs = resetTimeoutMs;
+    this.state = 'OPEN';
+  }
+}
+
+/**
+ * Circuit Breaker Timeout Error
+ * Thrown when execution inside a circuit breaker exceeds timeout.
+ * Maps to HTTP 504 Gateway Timeout.
+ */
+class CircuitBreakerTimeoutError extends HttpError {
+  /**
+   * @param {string} [breakerName='default']
+   * @param {number} [timeoutMs=0]
+   * @param {Object} [options]
+   */
+  constructor(breakerName = 'default', timeoutMs = 0, options = {}) {
+    super(504, `Execution in circuit breaker '${breakerName}' timed out after ${timeoutMs}ms`, {
+      code: 'CIRCUIT_BREAKER_TIMEOUT',
+      expose: true,
+      ...options,
+    });
+    this.breakerName = breakerName;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 module.exports = {
   ValidationError,
   ConfigurationError,
@@ -190,4 +235,7 @@ module.exports = {
   RouterError,
   RouteNotFoundError,
   RouteGenerationError,
+  CircuitBreakerOpenError,
+  CircuitBreakerTimeoutError,
 };
+

package/core/errors/http.js

@@ -109,6 +109,15 @@ class UnprocessableEntityError extends HttpError {
   }
 }
 
+/**
+ * 408 Request Timeout
+ */
+class RequestTimeoutError extends HttpError {
+  constructor(message = 'Request Timeout', options = {}) {
+    super(408, message, { code: 'REQUEST_TIMEOUT', ...options });
+  }
+}
+
 /**
  * 429 Too Many Requests
  */
@@ -118,6 +127,24 @@ class TooManyRequestsError extends HttpError {
   }
 }
 
+/**
+ * 503 Service Unavailable
+ */
+class ServiceUnavailableError extends HttpError {
+  constructor(message = 'Service Unavailable', options = {}) {
+    super(503, message, { code: 'SERVICE_UNAVAILABLE', ...options });
+  }
+}
+
+/**
+ * 504 Gateway Timeout
+ */
+class GatewayTimeoutError extends HttpError {
+  constructor(message = 'Gateway Timeout', options = {}) {
+    super(504, message, { code: 'GATEWAY_TIMEOUT', ...options });
+  }
+}
+
 module.exports = {
   HttpError,
   BadRequestError,
@@ -129,5 +156,9 @@ module.exports = {
   PayloadTooLargeError,
   UnsupportedMediaTypeError,
   UnprocessableEntityError,
+  RequestTimeoutError,
   TooManyRequestsError,
+  ServiceUnavailableError,
+  GatewayTimeoutError,
 };
+

package/core/errors/index.js

@@ -15,7 +15,10 @@ const {
   PayloadTooLargeError,
   UnsupportedMediaTypeError,
   UnprocessableEntityError,
+  RequestTimeoutError,
   TooManyRequestsError,
+  ServiceUnavailableError,
+  GatewayTimeoutError,
 } = require('./http');
 const {
   ValidationError,
@@ -27,6 +30,8 @@ const {
   RouterError,
   RouteNotFoundError,
   RouteGenerationError,
+  CircuitBreakerOpenError,
+  CircuitBreakerTimeoutError,
 } = require('./domain');
 const {
   getStatusTitle,
@@ -54,7 +59,10 @@ module.exports = {
   PayloadTooLargeError,
   UnsupportedMediaTypeError,
   UnprocessableEntityError,
+  RequestTimeoutError,
   TooManyRequestsError,
+  ServiceUnavailableError,
+  GatewayTimeoutError,
 
   // Domain Exceptions
   ValidationError,
@@ -66,6 +74,8 @@ module.exports = {
   RouterError,
   RouteNotFoundError,
   RouteGenerationError,
+  CircuitBreakerOpenError,
+  CircuitBreakerTimeoutError,
 
   // Utilities & Middleware
   getStatusTitle,

package/core/errors/middleware.js

@@ -5,6 +5,7 @@
 
 const { normalizeError, toErrorResponseObject } = require('./normalize');
 const { RequestAbortedError } = require('./domain');
+const { escapeHtml } = require('../utils/html');
 
 /**
  * Check if the request prefers a JSON error response
@@ -60,14 +61,7 @@ function renderDefaultErrorHtml(err, isDev) {
 </html>`;
 }
 
-function escapeHtml(str) {
-  return String(str || '')
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
-}
+
 
 /**
  * Create Webspresso Central Error Handler Middleware

package/core/errors/normalize.js

@@ -5,7 +5,11 @@
  */
 
 const { WebspressoError } = require('./base');
-const { HttpError } = require('./http');
+const {
+  HttpError,
+  BadRequestError,
+  PayloadTooLargeError,
+} = require('./http');
 
 const HTTP_TITLES = {
   400: 'Bad Request',
@@ -62,6 +66,60 @@ function normalizeError(err, isDev = false) {
     const isClientError = status < 500;
     const expose = typeof err.expose === 'boolean' ? err.expose : isClientError;
 
+    // Body parser / payload limit error mapping (HTTP 413)
+    if (status === 413 || err.type === 'entity.too.large' || err.type === 'parameters.too.many') {
+      const code = err.code || (err.type === 'parameters.too.many' ? 'PARAMETERS_TOO_MANY' : 'PAYLOAD_TOO_LARGE');
+      const details = err.details || (
+        (err.limit !== undefined || err.length !== undefined || err.expected !== undefined)
+          ? { limit: err.limit, length: err.length, expected: err.expected }
+          : (err.type ? { type: err.type } : undefined)
+      );
+      const payloadErr = new PayloadTooLargeError(
+        (expose || isDev) ? (err.message || getStatusTitle(413)) : getStatusTitle(413),
+        {
+          code,
+          details,
+          cause: err,
+          headers: err.headers,
+          expose,
+        }
+      );
+
+      if (err.stack) payloadErr.stack = err.stack;
+      if (err.route) payloadErr.route = err.route;
+      if (err.method) payloadErr.method = err.method;
+      if (err.source) payloadErr.source = err.source;
+      if (err.module) payloadErr.module = err.module;
+      if (err.phase) payloadErr.phase = err.phase;
+      if (err.requestId) payloadErr.requestId = err.requestId;
+
+      return payloadErr;
+    }
+
+    // Body parser JSON syntax error (HTTP 400)
+    if (err.type === 'entity.parse.failed') {
+      const badReqErr = new BadRequestError(
+        (expose || isDev) ? (err.message || 'Invalid JSON payload') : 'Invalid JSON payload',
+        {
+          code: err.code || 'INVALID_JSON_PAYLOAD',
+          details: err.details || { type: err.type },
+          cause: err,
+          headers: err.headers,
+          expose: true,
+        }
+      );
+
+      if (err.stack) badReqErr.stack = err.stack;
+      if (err.route) badReqErr.route = err.route;
+      if (err.method) badReqErr.method = err.method;
+      if (err.source) badReqErr.source = err.source;
+      if (err.module) badReqErr.module = err.module;
+      if (err.phase) badReqErr.phase = err.phase;
+      if (err.requestId) badReqErr.requestId = err.requestId;
+
+      return badReqErr;
+    }
+
     const httpErr = new HttpError(
       status,
       (expose || isDev) ? (err.message || getStatusTitle(status)) : getStatusTitle(status),
@@ -105,13 +163,41 @@ function normalizeError(err, isDev = false) {
       ? err.status
       : (typeof err.statusCode === 'number' ? err.statusCode : 500);
 
+    const isClientError = status < 500;
+    const expose = typeof err.expose === 'boolean' ? err.expose : isClientError;
+
+    if (status === 413 || err.type === 'entity.too.large' || err.type === 'parameters.too.many') {
+      const code = err.code || (err.type === 'parameters.too.many' ? 'PARAMETERS_TOO_MANY' : 'PAYLOAD_TOO_LARGE');
+      const details = err.details || (
+        (err.limit !== undefined || err.length !== undefined || err.expected !== undefined)
+          ? { limit: err.limit, length: err.length, expected: err.expected }
+          : (err.type ? { type: err.type } : undefined)
+      );
+      const payloadErr = new PayloadTooLargeError(
+        (expose || isDev) ? (err.message || getStatusTitle(413)) : getStatusTitle(413),
+        {
+          code,
+          details,
+          headers: err.headers,
+          expose,
+        }
+      );
+      if (err.route) payloadErr.route = err.route;
+      if (err.method) payloadErr.method = err.method;
+      if (err.source) payloadErr.source = err.source;
+      if (err.module) payloadErr.module = err.module;
+      if (err.phase) payloadErr.phase = err.phase;
+      if (err.requestId) payloadErr.requestId = err.requestId;
+      return payloadErr;
+    }
+
     const msg = typeof err.message === 'string' ? err.message : getStatusTitle(status);
 
     const httpErr = new HttpError(status, (status < 500 || isDev) ? msg : getStatusTitle(status), {
       code: err.code,
       details: err.details,
       headers: err.headers,
-      expose: typeof err.expose === 'boolean' ? err.expose : status < 500,
+      expose,
     });
 
     if (err.route) httpErr.route = err.route;

package/core/events/discovery.js

@@ -6,6 +6,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { walkDirectory } = require('../utils/fs');
 
 /**
  * Define a typed event listener
@@ -44,29 +45,6 @@ function filePathToEventName(relPath) {
   return parts.join('.');
 }
 
-/**
- * Recursively find all .js / .cjs files in a directory
- * @param {string} dir
- * @returns {string[]}
- */
-function walkDirectory(dir) {
-  const files = [];
-  if (!fs.existsSync(dir)) return files;
-
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...walkDirectory(fullPath));
-    } else if (entry.isFile() && (entry.name.endsWith('.js') || entry.name.endsWith('.cjs'))) {
-      if (!entry.name.startsWith('_') && !entry.name.endsWith('.test.js')) {
-        files.push(fullPath);
-      }
-    }
-  }
-  return files;
-}
-
 /**
  * Load and register listeners from a directory into an EventDispatcher
  * @param {string} dirPath - Absolute or relative directory path
@@ -84,7 +62,11 @@ function loadListeners(dirPath, dispatcher, options = {}) {
     return [];
   }
 
-  const filePaths = walkDirectory(resolvedDir);
+  const filePaths = walkDirectory(resolvedDir, {
+    extensions: ['.js', '.cjs'],
+    ignorePrefixes: ['_', '.'],
+    ignoreTests: true,
+  });
   const loaded = [];
 
   for (const filePath of filePaths) {

package/core/events/dispatcher.js

@@ -6,6 +6,7 @@
  */
 
 const EventEmitter = require('events');
+const { globToRegExp } = require('../utils/regex');
 
 /**
  * Convert a glob/wildcard pattern (e.g. 'order.*', 'order.**', '*') into a RegExp
@@ -21,13 +22,7 @@ function patternToRegExp(pattern) {
   const cached = patternRegexCache.get(pattern);
   if (cached !== undefined) return cached;
 
-  const escaped = pattern
-    .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars except *
-    .replace(/\*\*/g, '___DOUBLE_STAR___')
-    .replace(/\*/g, '[^.]+')
-    .replace(/___DOUBLE_STAR___/g, '.*');
-
-  const reg = new RegExp(`^${escaped}$`);
+  const reg = globToRegExp(pattern, { separator: '.' });
   if (patternRegexCache.size < 500) {
     patternRegexCache.set(pattern, reg);
   }

package/core/forms/form-builder.js

@@ -4,15 +4,7 @@
  * @module core/forms/form-builder
  */
 
-function escapeHtml(str) {
-  if (str === null || str === undefined) return '';
-  return String(str)
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#039;');
-}
+const { escapeHtml } = require('../utils/html');
 
 /**
  * Render a single form field with label, input, and validation error message

package/core/health/index.js

@@ -0,0 +1,41 @@
+'use strict';
+
+/**
+ * Webspresso Health & Readiness Probes Module
+ * Kubernetes, Docker & Cloud-ready liveness (/healthz), readiness (/readyz),
+ * and diagnostics endpoints with database pings, queue stats, and graceful draining integration.
+ *
+ * @module core/health
+ */
+
+const {
+  DEFAULT_HEALTH_CONFIG,
+  normalizeHealthConfig,
+} = require('./normalize');
+
+const {
+  formatMb,
+  createEventLoopMonitor,
+  getSystemMetrics,
+  probeDatabase,
+  probeQueue,
+  probeCustomChecks,
+} = require('./probes');
+
+const {
+  createHealthManager,
+  setupHealthMiddleware,
+} = require('./middleware');
+
+module.exports = {
+  DEFAULT_HEALTH_CONFIG,
+  normalizeHealthConfig,
+  formatMb,
+  createEventLoopMonitor,
+  getSystemMetrics,
+  probeDatabase,
+  probeQueue,
+  probeCustomChecks,
+  createHealthManager,
+  setupHealthMiddleware,
+};

package/core/health/middleware.js

@@ -0,0 +1,213 @@
+'use strict';
+
+/**
+ * Webspresso Health Check Middleware & Coordinator
+ * Exposes /healthz (liveness) and /readyz (readiness) endpoints conforming to cloud & Kubernetes standards.
+ *
+ * @module core/health/middleware
+ */
+
+const { normalizeHealthConfig } = require('./normalize');
+const {
+  createEventLoopMonitor,
+  getSystemMetrics,
+  probeDatabase,
+  probeQueue,
+  probeCustomChecks,
+} = require('./probes');
+
+/**
+ * Creates a health manager instance coordinating probes and runtime metrics.
+ *
+ * @param {Object} config - Normalized health configuration
+ * @param {Object} [context={}] - Server context (db, queue, shutdownManager)
+ * @returns {Object} HealthManager
+ */
+function createHealthManager(config, context = {}) {
+  const eventLoopMonitor = config.eventLoopLag ? createEventLoopMonitor() : null;
+
+  async function getLiveness() {
+    const metrics = getSystemMetrics(eventLoopMonitor);
+    let status = 'ok';
+
+    if (config.eventLoopLag && metrics.eventLoopLag && config.eventLoopThresholdMs) {
+      if (metrics.eventLoopLag.meanMs > config.eventLoopThresholdMs) {
+        status = 'degraded';
+      }
+    }
+
+    return {
+      status,
+      timestamp: new Date().toISOString(),
+      ...metrics,
+    };
+  }
+
+  async function getReadiness() {
+    const shutdownManager = context.shutdownManager || context.app?.shutdownManager;
+
+    // 1. Check if server is currently draining connections during shutdown
+    if (shutdownManager && (shutdownManager.isShuttingDown || shutdownManager.isClosed)) {
+      return {
+        ready: false,
+        status: 'draining',
+        message: 'Server is currently shutting down and draining active connections',
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    let isReady = true;
+    const checks = {};
+
+    // 2. Check Database connectivity
+    if (config.db && context.db) {
+      const dbResult = await probeDatabase(context.db, config.timeoutMs);
+      checks.database = dbResult;
+      if (dbResult.status === 'down') {
+        isReady = false;
+      }
+    }
+
+    // 3. Check Queue readiness
+    if (config.queue && context.queue) {
+      const queueResult = await probeQueue(context.queue);
+      checks.queue = queueResult;
+      if (queueResult.status === 'down') {
+        isReady = false;
+      }
+    }
+
+    // 4. Run user-defined custom checks
+    if (config.checks && Object.keys(config.checks).length > 0) {
+      const customResults = await probeCustomChecks(config.checks, context, config.timeoutMs);
+      checks.custom = customResults.results;
+      if (!customResults.isHealthy) {
+        isReady = false;
+      }
+    }
+
+    return {
+      ready: isReady,
+      status: isReady ? 'ready' : 'unhealthy',
+      timestamp: new Date().toISOString(),
+      checks,
+    };
+  }
+
+  async function getStatus() {
+    const [liveness, readiness] = await Promise.all([getLiveness(), getReadiness()]);
+    return {
+      status: readiness.ready ? liveness.status : 'unhealthy',
+      liveness,
+      readiness,
+    };
+  }
+
+  function destroy() {
+    if (eventLoopMonitor) {
+      eventLoopMonitor.destroy();
+    }
+  }
+
+  return {
+    config,
+    getLiveness,
+    getReadiness,
+    getStatus,
+    destroy,
+  };
+}
+
+/**
+ * Mounts standard health check endpoints onto the Express app
+ *
+ * @param {import('express').Application} app
+ * @param {Object} [options] - Health check options or createApp options
+ * @param {Object} [context={}] - Server context (db, queue, shutdownManager)
+ * @returns {Object|null} Active HealthManager or null if disabled
+ */
+function setupHealthMiddleware(app, options = {}, context = {}) {
+  const config = normalizeHealthConfig(options);
+  if (!config.enabled) {
+    return null;
+  }
+
+  const serverContext = {
+    ...context,
+    app,
+    db: context.db || app.db || (app.get ? app.get('db') : null),
+    queue: context.queue || app.queue || (app.get ? app.get('queue') : null),
+    shutdownManager: context.shutdownManager || app.shutdownManager,
+  };
+
+  const healthManager = createHealthManager(config, serverContext);
+
+  // Helper to attach configured headers (Cache-Control: no-store, etc.)
+  function applyHealthHeaders(res) {
+    if (config.headers && typeof config.headers === 'object') {
+      for (const [key, val] of Object.entries(config.headers)) {
+        res.setHeader(key, val);
+      }
+    }
+  }
+
+  // 1. Mount Liveness Endpoint (/healthz)
+  if (config.path) {
+    app.get(config.path, async (req, res) => {
+      try {
+        applyHealthHeaders(res);
+        const liveness = await healthManager.getLiveness();
+        const statusCode = liveness.status === 'ok' ? 200 : 200; // Liveness passes if process responds
+        return res.status(statusCode).json(liveness);
+      } catch (err) {
+        return res.status(500).json({ status: 'error', error: err.message });
+      }
+    });
+  }
+
+  // 2. Mount Readiness Endpoint (/readyz)
+  if (config.readyPath && config.readyPath !== config.path) {
+    app.get(config.readyPath, async (req, res) => {
+      try {
+        applyHealthHeaders(res);
+        const readiness = await healthManager.getReadiness();
+        const statusCode = readiness.ready ? 200 : 503;
+        return res.status(statusCode).json(readiness);
+      } catch (err) {
+        return res.status(503).json({ ready: false, status: 'error', error: err.message });
+      }
+    });
+  }
+
+  // 3. Mount Combined Diagnostic Endpoint (/health)
+  if (config.combinedPath && config.combinedPath !== config.path && config.combinedPath !== config.readyPath) {
+    app.get(config.combinedPath, async (req, res) => {
+      try {
+        applyHealthHeaders(res);
+        const status = await healthManager.getStatus();
+        const statusCode = status.readiness.ready ? 200 : 503;
+        return res.status(statusCode).json(status);
+      } catch (err) {
+        return res.status(503).json({ status: 'error', error: err.message });
+      }
+    });
+  }
+
+  // Decorate app for programmatic inspection
+  app.healthManager = healthManager;
+  app.getHealthStatus = () => healthManager.getStatus();
+
+  // Attach cleanup to shutdownManager
+  if (serverContext.shutdownManager && typeof serverContext.shutdownManager.onShutdown === 'function') {
+    serverContext.shutdownManager.onShutdown(() => {
+      healthManager.destroy();
+    });
+  }
+
+  return healthManager;
+}
+
+module.exports = {
+  createHealthManager,
+  setupHealthMiddleware,
+};