webspresso 0.0.90 → 0.0.91

package/core/errors/domain.js

@@ -0,0 +1,193 @@
+/**
+ * Framework Domain Exceptions
+ * Includes Validation, Configuration, Plugin, Router, Security, and Request errors.
+ * @module core/errors/domain
+ */
+
+const { WebspressoError } = require('./base');
+const { HttpError, NotFoundError } = require('./http');
+
+/**
+ * Validation Error
+ * Represents schema or business rule validation failures.
+ * Maps to HTTP 422 Unprocessable Entity by default.
+ */
+class ValidationError extends HttpError {
+  /**
+   * @param {string} [message='Validation failed']
+   * @param {Object} [options]
+   * @param {Record<string, string[]|string>} [options.fields={}] - Field-specific validation error messages
+   * @param {number} [options.status=422]
+   * @param {string} [options.code='VALIDATION_ERROR']
+   * @param {unknown} [options.details]
+   * @param {unknown} [options.cause]
+   */
+  constructor(message = 'Validation failed', options = {}) {
+    super(options.status || 422, message, {
+      code: options.code || 'VALIDATION_ERROR',
+      expose: true,
+      ...options,
+    });
+
+    this.fields = options.fields || {};
+  }
+}
+
+/**
+ * Configuration Error
+ * Represents framework, server, or application bootstrap misconfiguration.
+ */
+class ConfigurationError extends WebspressoError {
+  /**
+   * @param {string} message
+   * @param {Object} [options]
+   */
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code || 'CONFIGURATION_ERROR',
+      status: 500,
+      ...options,
+    });
+  }
+}
+
+/**
+ * Plugin Error
+ * Represents plugin lifecycle, registration, or dependency failure.
+ */
+class PluginError extends WebspressoError {
+  /**
+   * @param {string} message
+   * @param {Object} [options]
+   * @param {string} [options.plugin] - Name of the plugin that threw the error
+   */
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code || 'PLUGIN_ERROR',
+      status: 500,
+      ...options,
+    });
+
+    this.plugin = options.plugin || null;
+  }
+}
+
+/**
+ * Security Error
+ * Represents suspicious requests, invalid signatures, CSRF/cookie tampering.
+ * Maps to HTTP 400 Bad Request by default, with internal details masked.
+ */
+class SecurityError extends HttpError {
+  /**
+   * @param {string} [message='Security violation']
+   * @param {Object} [options]
+   */
+  constructor(message = 'Security violation', options = {}) {
+    super(options.status || 400, message, {
+      code: options.code || 'SECURITY_ERROR',
+      expose: false,
+      ...options,
+    });
+  }
+}
+
+/**
+ * Base Request Transport Error
+ */
+class RequestError extends HttpError {
+  /**
+   * @param {number} status
+   * @param {string} message
+   * @param {Object} [options]
+   */
+  constructor(status = 400, message = 'Request Error', options = {}) {
+    super(status, message, options);
+  }
+}
+
+/**
+ * Request Aborted Error
+ * Thrown when client connection is terminated/aborted before response completion.
+ */
+class RequestAbortedError extends RequestError {
+  /**
+   * @param {string} [message='Request aborted by client']
+   * @param {Object} [options]
+   */
+  constructor(message = 'Request aborted by client', options = {}) {
+    super(options.status || 499, message, {
+      code: options.code || 'REQUEST_ABORTED',
+      expose: false,
+      ...options,
+    });
+  }
+}
+
+/**
+ * Base Router Error
+ */
+class RouterError extends WebspressoError {
+  /**
+   * @param {string} message
+   * @param {Object} [options]
+   */
+  constructor(message, options = {}) {
+    super(message, options);
+  }
+}
+
+/**
+ * Route Not Found Error
+ * Represents a URL that cannot be resolved to any page or route handler.
+ * Maps to HTTP 404.
+ */
+class RouteNotFoundError extends NotFoundError {
+  /**
+   * @param {string} [pathOrMessage='Route not found']
+   * @param {Object} [options]
+   */
+  constructor(pathOrMessage = 'Route not found', options = {}) {
+    const msg = typeof pathOrMessage === 'string' && pathOrMessage.startsWith('/')
+      ? `Route not found: ${pathOrMessage}`
+      : pathOrMessage;
+
+    super(msg, {
+      code: options.code || 'ROUTE_NOT_FOUND',
+      ...options,
+    });
+
+    if (typeof pathOrMessage === 'string' && pathOrMessage.startsWith('/')) {
+      this.path = pathOrMessage;
+    }
+  }
+}
+
+/**
+ * Route Generation Error
+ * Developer error when generating a URL for a named route with missing or invalid parameters.
+ */
+class RouteGenerationError extends RouterError {
+  /**
+   * @param {string} message
+   * @param {Object} [options]
+   */
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code || 'ROUTE_GENERATION_ERROR',
+      status: 500,
+      ...options,
+    });
+  }
+}
+
+module.exports = {
+  ValidationError,
+  ConfigurationError,
+  PluginError,
+  SecurityError,
+  RequestError,
+  RequestAbortedError,
+  RouterError,
+  RouteNotFoundError,
+  RouteGenerationError,
+};

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