webspresso 0.0.89 → 0.0.91

package/core/errors/http.js

@@ -0,0 +1,133 @@
+/**
+ * HTTP Exception Hierarchy
+ * @module core/errors/http
+ */
+
+const { WebspressoError } = require('./base');
+
+/**
+ * Base HTTP Error
+ */
+class HttpError extends WebspressoError {
+  /**
+   * @param {number} status - HTTP status code
+   * @param {string} [message] - Error message
+   * @param {Object} [options]
+   * @param {string} [options.code] - Machine-readable error code
+   * @param {unknown} [options.details] - Additional contextual details
+   * @param {unknown} [options.cause] - Underlying root cause error
+   * @param {Record<string, string>} [options.headers] - Response headers to attach
+   * @param {boolean} [options.expose] - Whether to expose message to clients in production
+   */
+  constructor(status = 500, message = 'Internal Server Error', options = {}) {
+    super(message, options);
+
+    this.status = typeof status === 'number' ? status : 500;
+    this.headers = options.headers || {};
+    this.expose = options.expose !== undefined ? Boolean(options.expose) : this.status < 500;
+  }
+}
+
+/**
+ * 400 Bad Request
+ */
+class BadRequestError extends HttpError {
+  constructor(message = 'Bad Request', options = {}) {
+    super(400, message, { code: 'BAD_REQUEST', ...options });
+  }
+}
+
+/**
+ * 401 Unauthorized
+ */
+class UnauthorizedError extends HttpError {
+  constructor(message = 'Unauthorized', options = {}) {
+    super(401, message, { code: 'UNAUTHORIZED', ...options });
+  }
+}
+
+/**
+ * 403 Forbidden
+ */
+class ForbiddenError extends HttpError {
+  constructor(message = 'Forbidden', options = {}) {
+    super(403, message, { code: 'FORBIDDEN', ...options });
+  }
+}
+
+/**
+ * 404 Not Found
+ */
+class NotFoundError extends HttpError {
+  constructor(message = 'Not Found', options = {}) {
+    super(404, message, { code: 'NOT_FOUND', ...options });
+  }
+}
+
+/**
+ * 405 Method Not Allowed
+ */
+class MethodNotAllowedError extends HttpError {
+  constructor(message = 'Method Not Allowed', options = {}) {
+    super(405, message, { code: 'METHOD_NOT_ALLOWED', ...options });
+  }
+}
+
+/**
+ * 409 Conflict
+ */
+class ConflictError extends HttpError {
+  constructor(message = 'Conflict', options = {}) {
+    super(409, message, { code: 'CONFLICT', ...options });
+  }
+}
+
+/**
+ * 413 Payload Too Large
+ */
+class PayloadTooLargeError extends HttpError {
+  constructor(message = 'Payload Too Large', options = {}) {
+    super(413, message, { code: 'PAYLOAD_TOO_LARGE', ...options });
+  }
+}
+
+/**
+ * 415 Unsupported Media Type
+ */
+class UnsupportedMediaTypeError extends HttpError {
+  constructor(message = 'Unsupported Media Type', options = {}) {
+    super(415, message, { code: 'UNSUPPORTED_MEDIA_TYPE', ...options });
+  }
+}
+
+/**
+ * 422 Unprocessable Entity
+ */
+class UnprocessableEntityError extends HttpError {
+  constructor(message = 'Unprocessable Entity', options = {}) {
+    super(422, message, { code: 'UNPROCESSABLE_ENTITY', ...options });
+  }
+}
+
+/**
+ * 429 Too Many Requests
+ */
+class TooManyRequestsError extends HttpError {
+  constructor(message = 'Too Many Requests', options = {}) {
+    super(429, message, { code: 'TOO_MANY_REQUESTS', ...options });
+  }
+}
+
+module.exports = {
+  HttpError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  MethodNotAllowedError,
+  ConflictError,
+  PayloadTooLargeError,
+  UnsupportedMediaTypeError,
+  UnprocessableEntityError,
+  TooManyRequestsError,
+};

package/core/errors/index.js

@@ -0,0 +1,77 @@
+/**
+ * Webspresso Exceptions & Error Handling Module
+ * @module core/errors
+ */
+
+const { WebspressoError } = require('./base');
+const {
+  HttpError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  MethodNotAllowedError,
+  ConflictError,
+  PayloadTooLargeError,
+  UnsupportedMediaTypeError,
+  UnprocessableEntityError,
+  TooManyRequestsError,
+} = require('./http');
+const {
+  ValidationError,
+  ConfigurationError,
+  PluginError,
+  SecurityError,
+  RequestError,
+  RequestAbortedError,
+  RouterError,
+  RouteNotFoundError,
+  RouteGenerationError,
+} = require('./domain');
+const {
+  getStatusTitle,
+  normalizeError,
+  toErrorResponseObject,
+} = require('./normalize');
+const {
+  preferJsonErrorResponse,
+  createCentralErrorHandler,
+  renderDefaultErrorHtml,
+} = require('./middleware');
+
+module.exports = {
+  // Base
+  WebspressoError,
+
+  // HTTP Exceptions
+  HttpError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  MethodNotAllowedError,
+  ConflictError,
+  PayloadTooLargeError,
+  UnsupportedMediaTypeError,
+  UnprocessableEntityError,
+  TooManyRequestsError,
+
+  // Domain Exceptions
+  ValidationError,
+  ConfigurationError,
+  PluginError,
+  SecurityError,
+  RequestError,
+  RequestAbortedError,
+  RouterError,
+  RouteNotFoundError,
+  RouteGenerationError,
+
+  // Utilities & Middleware
+  getStatusTitle,
+  normalizeError,
+  toErrorResponseObject,
+  preferJsonErrorResponse,
+  createCentralErrorHandler,
+  renderDefaultErrorHtml,
+};

package/core/errors/middleware.js

@@ -0,0 +1,162 @@
+/**
+ * Central Error Boundary Middleware
+ * @module core/errors/middleware
+ */
+
+const { normalizeError, toErrorResponseObject } = require('./normalize');
+const { RequestAbortedError } = require('./domain');
+
+/**
+ * Check if the request prefers a JSON error response
+ * @param {import('express').Request} req
+ * @returns {boolean}
+ */
+function preferJsonErrorResponse(req) {
+  if (req.path.startsWith('/api/') || req.path.startsWith('/_admin/api/')) {
+    return true;
+  }
+  const accept = req.headers['accept'] || '';
+  if (accept.includes('application/json') && !accept.includes('text/html')) {
+    return true;
+  }
+  return req.xhr || req.headers['x-requested-with'] === 'XMLHttpRequest';
+}
+
+/**
+ * Default HTML error renderer fallback
+ * @param {import('./http').HttpError|Error} err
+ * @param {boolean} isDev
+ * @returns {string}
+ */
+function renderDefaultErrorHtml(err, isDev) {
+  const status = err.status || 500;
+  const message = (err.expose !== false || isDev) ? (err.message || 'Internal Server Error') : 'Internal Server Error';
+  const stackHtml = isDev && err.stack
+    ? `<pre style="background:#1e293b;color:#f87171;padding:16px;border-radius:8px;overflow:auto;font-size:13px;line-height:1.5;">${escapeHtml(err.stack)}</pre>`
+    : '';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${status} - ${escapeHtml(message)}</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #f8fafc; margin: 0; padding: 40px 20px; display: flex; justify-content: center; }
+    .card { background: #1e293b; padding: 32px; border-radius: 12px; max-width: 650px; width: 100%; border: 1px solid #334155; }
+    h1 { margin-top: 0; color: #ef4444; font-size: 24px; }
+    p { color: #cbd5e1; line-height: 1.6; }
+    a { color: #38bdf8; text-decoration: none; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Error ${status}</h1>
+    <p>${escapeHtml(message)}</p>
+    ${stackHtml}
+    <p><a href="/">← Back to Home</a></p>
+  </div>
+</body>
+</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
+ * @param {Object} [options]
+ * @param {boolean} [options.isDev=false]
+ * @param {Function} [options.getCustomHandler]
+ * @param {Function} [options.renderHtmlError]
+ * @returns {import('express').ErrorRequestHandler}
+ */
+function createCentralErrorHandler(options = {}) {
+  const isDev = Boolean(options.isDev);
+  const getCustomHandler = typeof options.getCustomHandler === 'function' ? options.getCustomHandler : () => null;
+  const renderHtmlError = typeof options.renderHtmlError === 'function' ? options.renderHtmlError : null;
+
+  return async function centralErrorHandler(err, req, res, next) {
+    if (res.headersSent) {
+      return next(err);
+    }
+
+    // Handle Client Request Aborted
+    if (err instanceof RequestAbortedError || req.aborted || (req.socket && req.socket.destroyed)) {
+      // Do not attempt to write to closed socket
+      return;
+    }
+
+    // Normalize error
+    const normalized = normalizeError(err, isDev);
+    const status = normalized.status || 500;
+
+    // Attach custom headers from HttpError if present
+    if (normalized.headers && typeof normalized.headers === 'object') {
+      for (const [key, value] of Object.entries(normalized.headers)) {
+        res.setHeader(key, value);
+      }
+    }
+
+    // Check for custom error handler registered via app.setErrorHandler(...)
+    const customHandler = getCustomHandler();
+    if (typeof customHandler === 'function') {
+      try {
+        const handled = await customHandler(err, req, res, next);
+        if (res.headersSent || handled === true) {
+          return;
+        }
+      } catch (customErr) {
+        // Prevent infinite error loops by logging custom handler error and continuing with fallback
+        if (typeof console !== 'undefined' && console.error) {
+          console.error('[webspresso] Error in custom error handler:', customErr);
+        }
+      }
+    }
+
+    // Log errors based on severity
+    if (status >= 500) {
+      if (typeof console !== 'undefined' && console.error) {
+        console.error('[webspresso] Server Error:', err);
+      }
+    } else if (isDev && status >= 400) {
+      if (typeof console !== 'undefined' && console.warn) {
+        console.warn(`[webspresso] HTTP ${status}:`, normalized.message);
+      }
+    }
+
+    res.status(status);
+
+    // Format response (JSON vs HTML)
+    if (preferJsonErrorResponse(req)) {
+      return res.json(toErrorResponseObject(normalized, isDev));
+    }
+
+    if (renderHtmlError) {
+      try {
+        const html = await renderHtmlError(normalized, req, res);
+        if (html && !res.headersSent) {
+          return res.send(html);
+        }
+      } catch (renderErr) {
+        if (typeof console !== 'undefined' && console.error) {
+          console.error('[webspresso] Error rendering HTML error page:', renderErr);
+        }
+      }
+    }
+
+    return res.send(renderDefaultErrorHtml(normalized, isDev));
+  };
+}
+
+module.exports = {
+  preferJsonErrorResponse,
+  createCentralErrorHandler,
+  renderDefaultErrorHtml,
+};

package/core/errors/normalize.js

@@ -0,0 +1,171 @@
+/**
+ * Error Normalization & Formatting Utilities
+ * Standardizes errors across all layers and formats safe HTTP error payloads.
+ * @module core/errors/normalize
+ */
+
+const { WebspressoError } = require('./base');
+const { HttpError } = require('./http');
+
+const HTTP_TITLES = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  413: 'Payload Too Large',
+  415: 'Unsupported Media Type',
+  422: 'Unprocessable Entity',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+};
+
+/**
+ * Get human-readable title for an HTTP status code
+ * @param {number} status
+ * @returns {string}
+ */
+function getStatusTitle(status) {
+  return HTTP_TITLES[status] || (status >= 500 ? 'Internal Server Error' : 'Error');
+}
+
+/**
+ * Normalize any thrown value (Error, string, object, null) into a standardized HttpError or WebspressoError
+ * @param {unknown} err - The raw thrown error
+ * @param {boolean} [isDev=false] - Whether in development environment
+ * @returns {HttpError|WebspressoError}
+ */
+function normalizeError(err, isDev = false) {
+  // Handle nullish throws
+  if (err === null || err === undefined) {
+    return new HttpError(500, 'Internal Server Error', {
+      expose: false,
+    });
+  }
+
+  // If already a WebspressoError / HttpError
+  if (err instanceof WebspressoError) {
+    return err;
+  }
+
+  // If standard JavaScript Error (TypeError, RangeError, standard Error)
+  if (err instanceof Error) {
+    const status = typeof err.status === 'number'
+      ? err.status
+      : (typeof err.statusCode === 'number' ? err.statusCode : 500);
+
+    const isClientError = status < 500;
+    const expose = typeof err.expose === 'boolean' ? err.expose : isClientError;
+
+    const httpErr = new HttpError(
+      status,
+      (expose || isDev) ? (err.message || getStatusTitle(status)) : getStatusTitle(status),
+      {
+        code: err.code || (status === 500 ? 'INTERNAL_SERVER_ERROR' : undefined),
+        details: err.details,
+        cause: err,
+        headers: err.headers,
+        expose,
+      }
+    );
+
+    // Retain original stack
+    if (err.stack) {
+      httpErr.stack = err.stack;
+    }
+
+    return httpErr;
+  }
+
+  // If primitive string or number thrown
+  if (typeof err === 'string' || typeof err === 'number' || typeof err === 'boolean') {
+    const msg = String(err);
+    return new HttpError(500, isDev ? msg : 'Internal Server Error', {
+      details: { rawValue: err },
+      expose: false,
+    });
+  }
+
+  // If plain object thrown (e.g. { message: 'Failed', status: 400 })
+  if (typeof err === 'object') {
+    const status = typeof err.status === 'number'
+      ? err.status
+      : (typeof err.statusCode === 'number' ? err.statusCode : 500);
+
+    const msg = typeof err.message === 'string' ? err.message : getStatusTitle(status);
+
+    return 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,
+    });
+  }
+
+  return new HttpError(500, 'Internal Server Error', { expose: false });
+}
+
+/**
+ * Format a normalized error into a clean JSON response object conforming to contract
+ * @param {HttpError|WebspressoError|Error} error - Normalized error
+ * @param {boolean} [isDev=false] - Whether running in development mode
+ * @returns {Record<string, unknown>}
+ */
+function toErrorResponseObject(error, isDev = false) {
+  const status = typeof error.status === 'number' ? error.status : 500;
+  const errorTitle = error.name === 'ValidationError'
+    ? 'Validation Error'
+    : getStatusTitle(status);
+
+  let shouldExpose;
+  if (typeof error.expose === 'boolean') {
+    shouldExpose = error.expose || isDev;
+  } else {
+    shouldExpose = isDev || status < 500;
+  }
+
+  const message = shouldExpose && error.message ? error.message : getStatusTitle(status);
+
+  const payload = {
+    status,
+    error: errorTitle,
+    message,
+  };
+
+  if (error.code) {
+    payload.code = error.code;
+  }
+
+  // Include validation fields if present
+  if (error.fields && Object.keys(error.fields).length > 0 && shouldExpose) {
+    payload.fields = error.fields;
+  }
+
+  // Include contextual details if expose is true or in dev
+  if (error.details !== undefined && shouldExpose) {
+    payload.details = error.details;
+  }
+
+  // Include stack and cause strictly in development mode
+  if (isDev) {
+    if (error.stack) {
+      payload.stack = error.stack;
+    }
+    if (error.cause) {
+      payload.cause = error.cause instanceof Error ? (error.cause.stack || error.cause.message) : error.cause;
+    }
+  }
+
+  return payload;
+}
+
+module.exports = {
+  getStatusTitle,
+  normalizeError,
+  toErrorResponseObject,
+};

package/core/orm/complexity.js

@@ -0,0 +1,120 @@
+/**
+ * ORM Query Complexity & DoS Protection
+ * @module core/orm/complexity
+ */
+
+'use strict';
+
+const { BadRequestError } = require('../errors/http');
+
+class QueryComplexityError extends BadRequestError {
+  /**
+   * @param {string} message
+   * @param {Object} [details]
+   */
+  constructor(message, details = {}) {
+    super(message || 'Query complexity limit exceeded', details);
+    this.name = 'QueryComplexityError';
+    this.code = 'QUERY_COMPLEXITY_EXCEEDED';
+  }
+}
+
+const DEFAULT_QUERY_LIMITS = Object.freeze({
+  maxLimit: 100,
+  defaultLimit: 15,
+  maxIncludes: 5,
+  maxFilterConditions: 25,
+});
+
+/**
+ * Resolve query limits for a given model
+ * @param {import('./types').ModelDefinition} [model]
+ * @returns {typeof DEFAULT_QUERY_LIMITS}
+ */
+function resolveQueryLimits(model) {
+  if (!model || !model.queryLimits) {
+    return DEFAULT_QUERY_LIMITS;
+  }
+  return {
+    maxLimit: Number(model.queryLimits.maxLimit) || DEFAULT_QUERY_LIMITS.maxLimit,
+    defaultLimit: Number(model.queryLimits.defaultLimit) || DEFAULT_QUERY_LIMITS.defaultLimit,
+    maxIncludes: Number(model.queryLimits.maxIncludes) || DEFAULT_QUERY_LIMITS.maxIncludes,
+    maxFilterConditions: Number(model.queryLimits.maxFilterConditions) || DEFAULT_QUERY_LIMITS.maxFilterConditions,
+  };
+}
+
+/**
+ * Validate and clamp query complexity parameters against model / default limits
+ * @param {import('./types').ModelDefinition} [model]
+ * @param {Object} params
+ * @param {number} [params.perPage]
+ * @param {number} [params.limit]
+ * @param {string[]} [params.includes]
+ * @param {number} [params.filterCount]
+ * @param {boolean} [params.strict=false] - If true, throws QueryComplexityError instead of clamping
+ * @returns {{ limit: number, perPage: number, includes: string[] }}
+ */
+function validateQueryComplexity(model, params = {}) {
+  const limits = resolveQueryLimits(model);
+  const strict = params.strict === true;
+
+  // 1. Validate includes
+  let includes = Array.isArray(params.includes) ? params.includes : [];
+  if (includes.length > limits.maxIncludes) {
+    if (strict) {
+      throw new QueryComplexityError(
+        `Too many eager-loaded relations (${includes.length}). Maximum allowed is ${limits.maxIncludes}.`,
+        { maxIncludes: limits.maxIncludes, requested: includes.length }
+      );
+    }
+    includes = includes.slice(0, limits.maxIncludes);
+  }
+
+  // 2. Validate perPage / limit
+  let requestedLimit = params.perPage !== undefined ? params.perPage : params.limit;
+  if (requestedLimit !== undefined) {
+    const numLimit = parseInt(requestedLimit, 10);
+    if (!isNaN(numLimit)) {
+      if (numLimit > limits.maxLimit) {
+        if (strict) {
+          throw new QueryComplexityError(
+            `Requested limit (${numLimit}) exceeds maximum allowed limit of ${limits.maxLimit}.`,
+            { maxLimit: limits.maxLimit, requested: numLimit }
+          );
+        }
+        requestedLimit = limits.maxLimit;
+      } else if (numLimit < 1) {
+        requestedLimit = limits.defaultLimit;
+      } else {
+        requestedLimit = numLimit;
+      }
+    } else {
+      requestedLimit = limits.defaultLimit;
+    }
+  } else {
+    requestedLimit = limits.defaultLimit;
+  }
+
+  // 3. Validate filter count
+  if (params.filterCount !== undefined && params.filterCount > limits.maxFilterConditions) {
+    if (strict) {
+      throw new QueryComplexityError(
+        `Too many filter conditions (${params.filterCount}). Maximum allowed is ${limits.maxFilterConditions}.`,
+        { maxFilterConditions: limits.maxFilterConditions, requested: params.filterCount }
+      );
+    }
+  }
+
+  return {
+    limit: requestedLimit,
+    perPage: requestedLimit,
+    includes,
+  };
+}
+
+module.exports = {
+  QueryComplexityError,
+  DEFAULT_QUERY_LIMITS,
+  resolveQueryLimits,
+  validateQueryComplexity,
+};