webspresso 0.0.104 → 0.0.105

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/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/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,
+};

package/core/health/normalize.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * Webspresso Health & Readiness Probes Normalization
+ * Standardizes configuration for Docker/Kubernetes liveness (/healthz),
+ * readiness (/readyz), and combined diagnostics endpoints.
+ *
+ * @module core/health/normalize
+ */
+
+const DEFAULT_HEALTH_CONFIG = Object.freeze({
+  enabled: false,
+  path: '/healthz',
+  readyPath: '/readyz',
+  combinedPath: '/health',
+  db: true,
+  queue: true,
+  eventLoopLag: true,
+  eventLoopThresholdMs: 300,
+  timeoutMs: 3000,
+  checks: Object.freeze({}),
+  headers: Object.freeze({
+    'Cache-Control': 'no-store, no-cache, must-revalidate',
+    'X-Content-Type-Options': 'nosniff',
+  }),
+});
+
+/**
+ * Normalizes user healthCheck configuration into a validated options object.
+ *
+ * @param {Object|boolean|string} [options]
+ * @returns {Object} Normalized health configuration
+ */
+function normalizeHealthConfig(options) {
+  if (options === undefined || options === null || options === false) {
+    return {
+      ...DEFAULT_HEALTH_CONFIG,
+      enabled: false,
+      checks: {},
+      headers: { ...DEFAULT_HEALTH_CONFIG.headers },
+    };
+  }
+
+  // If top-level createApp options passed, extract options.healthCheck ?? options.server?.healthCheck
+  let raw = options;
+  if (options && typeof options === 'object') {
+    if ('healthCheck' in options || (options.server && 'healthCheck' in options.server)) {
+      raw = options.healthCheck ?? options.server?.healthCheck ?? false;
+    }
+  }
+
+  // Boolean shorthand: healthCheck: true
+  if (raw === true) {
+    return {
+      ...DEFAULT_HEALTH_CONFIG,
+      enabled: true,
+      checks: {},
+      headers: { ...DEFAULT_HEALTH_CONFIG.headers },
+    };
+  }
+
+  // Boolean false or falsy: healthCheck: false
+  if (!raw || raw === false) {
+    return {
+      ...DEFAULT_HEALTH_CONFIG,
+      enabled: false,
+      checks: {},
+      headers: { ...DEFAULT_HEALTH_CONFIG.headers },
+    };
+  }
+
+  // String shorthand: healthCheck: '/healthz' or healthCheck: '/api/health'
+  if (typeof raw === 'string') {
+    const cleanPath = raw.startsWith('/') ? raw : `/${raw}`;
+    return {
+      ...DEFAULT_HEALTH_CONFIG,
+      enabled: true,
+      path: cleanPath,
+      combinedPath: cleanPath,
+      checks: {},
+      headers: { ...DEFAULT_HEALTH_CONFIG.headers },
+    };
+  }
+
+  // Object configuration: healthCheck: { path, readyPath, ... }
+  const opts = typeof raw === 'object' ? raw : {};
+
+  const cleanPath = (p, fallback) => {
+    if (p === false || p === null) return false;
+    if (typeof p === 'string' && p.trim()) {
+      const trimmed = p.trim();
+      return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    }
+    return fallback;
+  };
+
+  const hasExplicitConfig = Object.keys(opts).length > 0;
+  const enabled = opts.enabled !== undefined ? Boolean(opts.enabled) : hasExplicitConfig;
+  const path = cleanPath(opts.path, DEFAULT_HEALTH_CONFIG.path);
+  const readyPath = cleanPath(opts.readyPath, DEFAULT_HEALTH_CONFIG.readyPath);
+  const combinedPath = cleanPath(opts.combinedPath, DEFAULT_HEALTH_CONFIG.combinedPath);
+
+  const db = opts.db !== false;
+  const queue = opts.queue !== false;
+  const eventLoopLag = opts.eventLoopLag !== false;
+
+  const eventLoopThresholdMs = typeof opts.eventLoopThresholdMs === 'number' && opts.eventLoopThresholdMs > 0
+    ? opts.eventLoopThresholdMs
+    : DEFAULT_HEALTH_CONFIG.eventLoopThresholdMs;
+
+  const timeoutMs = typeof opts.timeoutMs === 'number' && opts.timeoutMs > 0
+    ? opts.timeoutMs
+    : DEFAULT_HEALTH_CONFIG.timeoutMs;
+
+  const checks = opts.checks && typeof opts.checks === 'object' ? { ...opts.checks } : {};
+
+  const headers = {
+    ...DEFAULT_HEALTH_CONFIG.headers,
+    ...(opts.headers && typeof opts.headers === 'object' ? opts.headers : {}),
+  };
+
+  return {
+    enabled,
+    path,
+    readyPath,
+    combinedPath,
+    db,
+    queue,
+    eventLoopLag,
+    eventLoopThresholdMs,
+    timeoutMs,
+    checks,
+    headers,
+  };
+}
+
+module.exports = {
+  DEFAULT_HEALTH_CONFIG,
+  normalizeHealthConfig,
+};