webspresso 0.0.103 → 0.0.105

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

package/core/health/probes.js

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * Webspresso System & Component Health Probes
+ * Gathers system metrics (uptime, memory, event loop delay),
+ * tests database and queue availability, and runs user-defined health probes.
+ *
+ * @module core/health/probes
+ */
+
+const { monitorEventLoopDelay } = require('perf_hooks');
+
+/**
+ * Formats bytes to human-readable megabytes
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatMb(bytes) {
+  if (typeof bytes !== 'number' || isNaN(bytes)) return '0 MB';
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+/**
+ * Creates an event loop delay monitor
+ * @returns {{ getStats: () => Object, destroy: () => void }|null}
+ */
+function createEventLoopMonitor() {
+  try {
+    const histogram = monitorEventLoopDelay({ resolution: 20 });
+    histogram.enable();
+
+    return {
+      getStats() {
+        const meanNs = histogram.mean || 0;
+        const maxNs = histogram.max || 0;
+        const p50Ns = histogram.percentile ? histogram.percentile(50) : 0;
+        const p99Ns = histogram.percentile ? histogram.percentile(99) : 0;
+
+        return {
+          meanMs: Math.round((meanNs / 1e6) * 100) / 100,
+          maxMs: Math.round((maxNs / 1e6) * 100) / 100,
+          p50Ms: Math.round((p50Ns / 1e6) * 100) / 100,
+          p99Ms: Math.round((p99Ns / 1e6) * 100) / 100,
+        };
+      },
+      destroy() {
+        try {
+          histogram.disable();
+        } catch {}
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collects runtime system health metrics
+ * @param {Object} [monitor] - Event loop monitor instance
+ * @returns {Object}
+ */
+function getSystemMetrics(monitor = null) {
+  const mem = process.memoryUsage();
+  const uptimeSeconds = Math.floor(process.uptime());
+
+  const metrics = {
+    uptimeSeconds,
+    memory: {
+      rss: formatMb(mem.rss),
+      heapUsed: formatMb(mem.heapUsed),
+      heapTotal: formatMb(mem.heapTotal),
+      external: formatMb(mem.external),
+      bytes: {
+        rss: mem.rss,
+        heapUsed: mem.heapUsed,
+        heapTotal: mem.heapTotal,
+      },
+    },
+    pid: process.pid,
+    nodeVersion: process.version,
+    platform: process.platform,
+  };
+
+  if (monitor && typeof monitor.getStats === 'function') {
+    metrics.eventLoopLag = monitor.getStats();
+  }
+
+  return metrics;
+}
+
+/**
+ * Safely probes database connectivity with timeout
+ * @param {Object} db - Webspresso database instance
+ * @param {number} [timeoutMs=3000] - Timeout in milliseconds
+ * @returns {Promise<{ status: 'up'|'down'|'skipped', latencyMs?: number, error?: string }>}
+ */
+async function probeDatabase(db, timeoutMs = 3000) {
+  if (!db) {
+    return { status: 'skipped', message: 'No database configured' };
+  }
+
+  const knex = db.knex || db;
+  if (!knex || typeof knex.raw !== 'function') {
+    return { status: 'up', message: 'Custom database without raw ping' };
+  }
+
+  const startTime = Date.now();
+  let timer = null;
+
+  try {
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(`Database ping timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+
+    await Promise.race([knex.raw('SELECT 1'), timeoutPromise]);
+    const latencyMs = Date.now() - startTime;
+    return { status: 'up', latencyMs };
+  } catch (err) {
+    return { status: 'down', error: err.message };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Probes background worker queue readiness
+ * @param {Object} queue - Queue instance
+ * @returns {Promise<{ status: 'up'|'down'|'skipped', stats?: Object, error?: string }>}
+ */
+async function probeQueue(queue) {
+  if (!queue) {
+    return { status: 'skipped', message: 'No queue configured' };
+  }
+
+  try {
+    if (typeof queue.getStats === 'function') {
+      const stats = await queue.getStats();
+      return { status: 'up', stats };
+    }
+    if (typeof queue.isReady === 'boolean') {
+      return { status: queue.isReady ? 'up' : 'down' };
+    }
+    return { status: 'up' };
+  } catch (err) {
+    return { status: 'down', error: err.message };
+  }
+}
+
+/**
+ * Runs user-registered custom health checks concurrently
+ * @param {Record<string, Function>} checks - Map of named probe functions
+ * @param {Object} context - Server context
+ * @param {number} [timeoutMs=3000] - Timeout per probe
+ * @returns {Promise<{ isHealthy: boolean, results: Record<string, Object> }>}
+ */
+async function probeCustomChecks(checks = {}, context = {}, timeoutMs = 3000) {
+  const entries = Object.entries(checks);
+  if (entries.length === 0) {
+    return { isHealthy: true, results: {} };
+  }
+
+  const results = {};
+  let isHealthy = true;
+
+  const promises = entries.map(async ([name, checkFn]) => {
+    let timer = null;
+    const startTime = Date.now();
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Health check "${name}" timed out after ${timeoutMs}ms`)), timeoutMs);
+      });
+
+      const res = await Promise.race([Promise.resolve(checkFn(context)), timeoutPromise]);
+      const latencyMs = Date.now() - startTime;
+
+      if (res === false || (res && typeof res === 'object' && res.status === 'down')) {
+        isHealthy = false;
+        results[name] = { status: 'down', latencyMs, ...(typeof res === 'object' ? res : {}) };
+      } else {
+        results[name] = { status: 'up', latencyMs, ...(typeof res === 'object' ? res : {}) };
+      }
+    } catch (err) {
+      isHealthy = false;
+      results[name] = { status: 'down', error: err.message };
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  });
+
+  await Promise.all(promises);
+  return { isHealthy, results };
+}
+
+module.exports = {
+  formatMb,
+  createEventLoopMonitor,
+  getSystemMetrics,
+  probeDatabase,
+  probeQueue,
+  probeCustomChecks,
+};

package/core/limits/index.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * Webspresso Payload Limits & DoS Protection Module
+ * Configurable body size limits for JSON, URL-encoded, raw, and text payloads,
+ * with route-level overrides, raw body capture, and seamless 413 PayloadTooLargeError handling.
+ *
+ * @module core/limits
+ */
+
+const {
+  DEFAULT_LIMITS,
+  parseByteSize,
+  normalizeLimits,
+} = require('./normalize');
+
+const {
+  matchesPath,
+  shouldSkipBodyParser,
+  shouldCaptureRawBody,
+  createLimitsMiddleware,
+  setupLimitsMiddleware,
+} = require('./middleware');
+
+module.exports = {
+  DEFAULT_LIMITS,
+  parseByteSize,
+  normalizeLimits,
+  matchesPath,
+  shouldSkipBodyParser,
+  shouldCaptureRawBody,
+  createLimitsMiddleware,
+  setupLimitsMiddleware,
+};

package/core/limits/middleware.js

@@ -0,0 +1,317 @@
+'use strict';
+
+/**
+ * Webspresso Payload Limits Middleware
+ * Zero-dependency body size enforcement, DoS protection, and raw body capture.
+ *
+ * @module core/limits/middleware
+ */
+
+const express = require('express');
+const { normalizeLimits } = require('./normalize');
+
+/**
+ * Checks if a given URL pathname matches a path pattern (string, glob wildcard, or RegExp).
+ *
+ * @param {string|RegExp|Function} pattern
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function matchesPath(pattern, pathname) {
+  if (!pathname || !pattern) return false;
+
+  if (typeof pattern === 'function') {
+    try {
+      return Boolean(pattern(pathname));
+    } catch {
+      return false;
+    }
+  }
+
+  if (pattern instanceof RegExp) {
+    return pattern.test(pathname);
+  }
+
+  if (typeof pattern !== 'string') return false;
+
+  // Exact match
+  if (pattern === pathname) return true;
+
+  // Wildcard match (e.g. /api/webhooks/* or /api/webhooks/**)
+  if (pattern.endsWith('/**')) {
+    const base = pattern.slice(0, -3);
+    return pathname === base || pathname.startsWith(base.endsWith('/') ? base : `${base}/`);
+  }
+  if (pattern.endsWith('/*')) {
+    const base = pattern.slice(0, -2);
+    return pathname === base || pathname.startsWith(base.endsWith('/') ? base : `${base}/`);
+  }
+
+  // Parameterized express pattern: /api/users/:id/upload
+  if (pattern.includes(':')) {
+    const regexPattern = '^' + pattern.replace(/\/:[^/]+/g, '/[^/]+') + '$';
+    try {
+      return new RegExp(regexPattern).test(pathname);
+    } catch {
+      return false;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Determines whether body parsing should be skipped for the incoming request.
+ *
+ * @param {import('express').Request} req
+ * @param {Array<string|RegExp|Function>} excludeList
+ * @returns {boolean}
+ */
+function shouldSkipBodyParser(req, excludeList) {
+  if (!Array.isArray(excludeList) || excludeList.length === 0) {
+    return false;
+  }
+  const currentPath = req.path || '';
+  const originalUrl = req.originalUrl ? req.originalUrl.split('?')[0] : '';
+
+  return excludeList.some(
+    (pattern) => matchesPath(pattern, currentPath) || matchesPath(pattern, originalUrl)
+  );
+}
+
+/**
+ * Determines whether raw body buffer should be captured into `req.rawBody`.
+ *
+ * @param {import('express').Request} req
+ * @param {boolean|Array<string|RegExp>|Function} captureSetting
+ * @returns {boolean}
+ */
+function shouldCaptureRawBody(req, captureSetting) {
+  if (!captureSetting) return false;
+  if (captureSetting === true) return true;
+
+  if (typeof captureSetting === 'function') {
+    try {
+      return Boolean(captureSetting(req));
+    } catch {
+      return false;
+    }
+  }
+
+  if (Array.isArray(captureSetting)) {
+    const currentPath = req.path || '';
+    const originalUrl = req.originalUrl ? req.originalUrl.split('?')[0] : '';
+    return captureSetting.some(
+      (pattern) => matchesPath(pattern, currentPath) || matchesPath(pattern, originalUrl)
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Creates route-level limits middleware executing custom body parsers.
+ *
+ * @param {Object} [routeOptions]
+ * @returns {import('express').RequestHandler}
+ */
+function createLimitsMiddleware(routeOptions = {}) {
+  const limits = normalizeLimits(routeOptions);
+  const parsers = [];
+
+  function makeVerify(userVerify) {
+    return (req, res, buf, encoding) => {
+      if (typeof userVerify === 'function') {
+        userVerify(req, res, buf, encoding);
+      }
+      if (shouldCaptureRawBody(req, limits.captureRawBody)) {
+        req.rawBody = buf;
+      }
+    };
+  }
+
+  if (limits.json.enabled) {
+    parsers.push(
+      express.json({
+        ...limits.json.options,
+        limit: limits.json.limit,
+        strict: limits.json.strict,
+        verify: makeVerify(limits.json.verify),
+      })
+    );
+  }
+
+  if (limits.urlencoded.enabled) {
+    parsers.push(
+      express.urlencoded({
+        ...limits.urlencoded.options,
+        limit: limits.urlencoded.limit,
+        extended: limits.urlencoded.extended,
+        parameterLimit: limits.urlencoded.parameterLimit,
+        verify: makeVerify(limits.urlencoded.verify),
+      })
+    );
+  }
+
+  if (limits.raw.enabled) {
+    parsers.push(
+      express.raw({
+        ...limits.raw.options,
+        limit: limits.raw.limit,
+        type: limits.raw.type,
+        verify: makeVerify(limits.raw.verify),
+      })
+    );
+  }
+
+  if (limits.text.enabled) {
+    parsers.push(
+      express.text({
+        ...limits.text.options,
+        limit: limits.text.limit,
+        type: limits.text.type,
+        verify: makeVerify(limits.text.verify),
+      })
+    );
+  }
+
+  return function routeLimitsMiddleware(req, res, next) {
+    if (shouldSkipBodyParser(req, limits.exclude)) {
+      return next();
+    }
+
+    let idx = 0;
+    function runNextParser(err) {
+      if (err) return next(err);
+      if (idx >= parsers.length) return next();
+      const parser = parsers[idx++];
+      parser(req, res, runNextParser);
+    }
+
+    runNextParser();
+  };
+}
+
+/**
+ * Mounts payload limits and body parsing middleware onto an Express application.
+ *
+ * @param {import('express').Application} app
+ * @param {Object} [options]
+ * @returns {Object} Normalized limits configuration
+ */
+function setupLimitsMiddleware(app, options = {}) {
+  const limits = normalizeLimits(options);
+
+  // Expose limits on app instance for introspection
+  app.limits = limits;
+  if (typeof app.set === 'function') {
+    app.set('webspresso.limits', limits);
+  }
+
+  const allExcludes = [...limits.exclude];
+
+  // 1. Mount route-specific overrides (mounted first so they take precedence)
+  if (limits.routes && typeof limits.routes === 'object') {
+    for (const [routePattern, routeConfig] of Object.entries(limits.routes)) {
+      if (routeConfig === false) {
+        // Entirely exclude this route from global body parsing
+        allExcludes.push(routePattern);
+      } else if (routeConfig && typeof routeConfig === 'object') {
+        // Mount route-specific body parsers on the path
+        const routeMw = createLimitsMiddleware(routeConfig);
+        app.use(routePattern, routeMw);
+      }
+    }
+  }
+
+  // 2. Setup Global Body Parsers with exclusion checking and raw body capture
+  function globalVerify(userVerify) {
+    return (req, res, buf, encoding) => {
+      if (typeof userVerify === 'function') {
+        userVerify(req, res, buf, encoding);
+      }
+      if (shouldCaptureRawBody(req, limits.captureRawBody)) {
+        req.rawBody = buf;
+      }
+    };
+  }
+
+  // Global JSON Parser
+  if (limits.json.enabled) {
+    const jsonParserFn = express.json({
+      ...limits.json.options,
+      limit: limits.json.limit,
+      strict: limits.json.strict,
+      verify: globalVerify(limits.json.verify),
+    });
+
+    app.use(function jsonParser(req, res, next) {
+      if (req._body || shouldSkipBodyParser(req, allExcludes)) {
+        return next();
+      }
+      jsonParserFn(req, res, next);
+    });
+  }
+
+  // Global URL-Encoded Parser
+  if (limits.urlencoded.enabled) {
+    const urlencodedParserFn = express.urlencoded({
+      ...limits.urlencoded.options,
+      limit: limits.urlencoded.limit,
+      extended: limits.urlencoded.extended,
+      parameterLimit: limits.urlencoded.parameterLimit,
+      verify: globalVerify(limits.urlencoded.verify),
+    });
+
+    app.use(function urlencodedParser(req, res, next) {
+      if (req._body || shouldSkipBodyParser(req, allExcludes)) {
+        return next();
+      }
+      urlencodedParserFn(req, res, next);
+    });
+  }
+
+  // Global Raw Body Parser
+  if (limits.raw.enabled) {
+    const rawParser = express.raw({
+      ...limits.raw.options,
+      limit: limits.raw.limit,
+      type: limits.raw.type,
+      verify: globalVerify(limits.raw.verify),
+    });
+
+    app.use((req, res, next) => {
+      if (req._body || shouldSkipBodyParser(req, allExcludes)) {
+        return next();
+      }
+      rawParser(req, res, next);
+    });
+  }
+
+  // Global Text Parser
+  if (limits.text.enabled) {
+    const textParser = express.text({
+      ...limits.text.options,
+      limit: limits.text.limit,
+      type: limits.text.type,
+      verify: globalVerify(limits.text.verify),
+    });
+
+    app.use((req, res, next) => {
+      if (req._body || shouldSkipBodyParser(req, allExcludes)) {
+        return next();
+      }
+      textParser(req, res, next);
+    });
+  }
+
+  return limits;
+}
+
+module.exports = {
+  matchesPath,
+  shouldSkipBodyParser,
+  shouldCaptureRawBody,
+  createLimitsMiddleware,
+  setupLimitsMiddleware,
+};