webspresso 0.0.90 → 0.0.93

package/core/compression/middleware.js

@@ -0,0 +1,310 @@
+/**
+ * HTTP Compression Middleware
+ * Provides threshold-based streaming response compression for Webspresso applications.
+ * @module core/compression/middleware
+ */
+
+const { selectEncoding, getDefaultSupportedEncodings } = require('./negotiate');
+const { isCompressible } = require('./compressible');
+const { createCompressionStream } = require('./compression-stream');
+
+/**
+ * Safely append a field to the HTTP Vary header
+ * @param {import('http').ServerResponse} res
+ * @param {string} field
+ */
+function appendVary(res, field) {
+  const current = res.getHeader('Vary');
+  if (!current) {
+    res.setHeader('Vary', field);
+    return;
+  }
+
+  const currentStr = Array.isArray(current) ? current.join(', ') : String(current);
+  const parts = currentStr.split(',').map(s => s.trim().toLowerCase());
+
+  if (parts.includes('*') || parts.includes(field.toLowerCase())) {
+    return;
+  }
+
+  res.setHeader('Vary', `${currentStr}, ${field}`);
+}
+
+/**
+ * Create Webspresso HTTP Response Compression Middleware
+ * @param {Object} [options]
+ * @param {number} [options.threshold=1024] - Minimum response size in bytes to apply compression
+ * @param {number} [options.level=6] - Default compression level
+ * @param {string[]} [options.encodings] - Supported encodings in preference order
+ * @param {function(import('http').IncomingMessage, import('http').ServerResponse): boolean} [options.filter] - Custom filter function
+ * @param {Object} [options.brotli] - Custom Brotli options
+ * @param {Object} [options.gzip] - Custom Gzip options
+ * @param {Object} [options.deflate] - Custom Deflate options
+ * @returns {import('express').RequestHandler}
+ */
+function createCompressionMiddleware(options = {}) {
+  const threshold = typeof options.threshold === 'number' && options.threshold >= 0 ? options.threshold : 1024;
+  const supportedEncodings = Array.isArray(options.encodings) && options.encodings.length > 0
+    ? options.encodings
+    : getDefaultSupportedEncodings();
+
+  const customFilter = typeof options.filter === 'function' ? options.filter : null;
+
+  return function compressionMiddleware(req, res, next) {
+    // Expose opt-out API on response object
+    res._noCompression = false;
+    res.compress = function(enable = true) {
+      res._noCompression = !enable;
+      return res;
+    };
+
+    // Skip compression for HEAD requests
+    if (req.method === 'HEAD') {
+      return next();
+    }
+
+    const acceptEncoding = req.headers['accept-encoding'];
+    let selectedEncoding = null;
+    let checkedEncoding = false;
+
+    function getSelectedEncoding() {
+      if (!checkedEncoding) {
+        checkedEncoding = true;
+        selectedEncoding = selectEncoding(acceptEncoding, supportedEncodings);
+      }
+      return selectedEncoding;
+    }
+
+    // Original methods to wrap
+    const origWrite = res.write.bind(res);
+    const origEnd = res.end.bind(res);
+    const origWriteHead = res.writeHead.bind(res);
+
+    let compressStream = null;
+    let isCompressing = false;
+    let headersSent = false;
+    let bufferedChunks = [];
+    let bufferedLength = 0;
+    let decided = false;
+
+    /**
+     * Check if response should be compressed
+     * @param {number} [expectedLength]
+     * @returns {boolean}
+     */
+    function shouldCompress(expectedLength) {
+      if (res._noCompression || res.locals?.compress === false || res.shouldCompress === false) {
+        return false;
+      }
+
+      // Check status codes that must not have a body
+      const statusCode = res.statusCode || 200;
+      if (statusCode === 204 || statusCode === 304 || statusCode === 205 || statusCode < 200) {
+        return false;
+      }
+
+      // If response already has a Content-Encoding, do not double-compress
+      if (res.getHeader('Content-Encoding')) {
+        return false;
+      }
+
+      // Check Content-Type compressibility
+      const contentType = res.getHeader('Content-Type');
+      if (!contentType || !isCompressible(contentType)) {
+        return false;
+      }
+
+      // Check threshold if length is known
+      if (typeof expectedLength === 'number' && expectedLength < threshold) {
+        return false;
+      }
+
+      // Custom filter hook
+      if (customFilter && !customFilter(req, res)) {
+        return false;
+      }
+
+      // Check if client supports any available encoding
+      const encoding = getSelectedEncoding();
+      if (!encoding || encoding === 'identity') {
+        return false;
+      }
+
+      return true;
+    }
+
+    /**
+     * Initialize compression stream and headers
+     */
+    function startCompression() {
+      const encoding = getSelectedEncoding();
+      compressStream = createCompressionStream(encoding, options);
+      if (!compressStream) {
+        isCompressing = false;
+        return;
+      }
+
+      isCompressing = true;
+      appendVary(res, 'Accept-Encoding');
+      res.setHeader('Content-Encoding', encoding);
+      res.removeHeader('Content-Length');
+
+      // Pipe compression stream chunks directly into underlying socket/response
+      compressStream.on('data', (chunk) => {
+        origWrite(chunk);
+      });
+
+      compressStream.on('end', () => {
+        origEnd();
+      });
+
+      compressStream.on('error', (err) => {
+        origEnd();
+      });
+    }
+
+    // Wrap writeHead
+    res.writeHead = function(statusCode, ...args) {
+      if (res.headersSent) return res;
+
+      if (typeof args[0] === 'object' && args[0] !== null) {
+        for (const [k, v] of Object.entries(args[0])) {
+          res.setHeader(k, v);
+        }
+      } else if (typeof args[1] === 'object' && args[1] !== null) {
+        for (const [k, v] of Object.entries(args[1])) {
+          res.setHeader(k, v);
+        }
+      }
+
+      if (isCompressing) {
+        const encoding = getSelectedEncoding();
+        if (encoding) {
+          res.setHeader('Content-Encoding', encoding);
+        }
+        res.removeHeader('Content-Length');
+        appendVary(res, 'Accept-Encoding');
+      }
+
+      return origWriteHead.call(res, statusCode, ...args);
+    };
+
+    // Wrap write
+    res.write = function(chunk, encoding, callback) {
+      if (typeof encoding === 'function') {
+        callback = encoding;
+        encoding = undefined;
+      }
+
+      if (!chunk) {
+        return true;
+      }
+
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
+
+      if (!decided) {
+        bufferedChunks.push(buf);
+        bufferedLength += buf.length;
+
+        // If buffered size exceeds threshold, decide to start compression immediately
+        if (bufferedLength >= threshold) {
+          decided = true;
+          if (shouldCompress()) {
+            startCompression();
+            // Flush buffered chunks through compressor
+            for (const b of bufferedChunks) {
+              compressStream.write(b);
+            }
+            bufferedChunks = [];
+          } else {
+            // Send buffered chunks uncompressed
+            for (const b of bufferedChunks) {
+              origWrite(b);
+            }
+            bufferedChunks = [];
+          }
+        }
+        if (typeof callback === 'function') callback();
+        return true;
+      }
+
+      if (isCompressing && compressStream) {
+        return compressStream.write(buf, callback);
+      }
+
+      return origWrite(buf, callback);
+    };
+
+    // Wrap end
+    res.end = function(chunk, encoding, callback) {
+      if (typeof chunk === 'function') {
+        callback = chunk;
+        chunk = null;
+      } else if (typeof encoding === 'function') {
+        callback = encoding;
+        encoding = undefined;
+      }
+
+      if (chunk) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
+        if (!decided) {
+          bufferedChunks.push(buf);
+          bufferedLength += buf.length;
+        } else if (isCompressing && compressStream) {
+          compressStream.write(buf);
+        } else {
+          origWrite(buf);
+        }
+      }
+
+      if (!decided) {
+        decided = true;
+        // Check if total length satisfies threshold and compressibility
+        if (shouldCompress(bufferedLength)) {
+          startCompression();
+          if (bufferedChunks.length === 1) {
+            if (typeof callback === 'function') {
+              compressStream.once('end', callback);
+            }
+            const singleBuf = bufferedChunks[0];
+            bufferedChunks = [];
+            compressStream.end(singleBuf);
+            return res;
+          }
+          for (const b of bufferedChunks) {
+            compressStream.write(b);
+          }
+          bufferedChunks = [];
+        } else {
+          // Output uncompressed
+          if (shouldCompress(Infinity) && bufferedLength < threshold) {
+            // Ensure Vary is set if content was compressible but just below threshold
+            appendVary(res, 'Accept-Encoding');
+          }
+          for (const b of bufferedChunks) {
+            origWrite(b);
+          }
+          bufferedChunks = [];
+          return origEnd(callback);
+        }
+      }
+
+      if (isCompressing && compressStream) {
+        if (typeof callback === 'function') {
+          compressStream.once('end', callback);
+        }
+        compressStream.end();
+        return res;
+      }
+
+      return origEnd(callback);
+    };
+
+    next();
+  };
+}
+
+module.exports = {
+  createCompressionMiddleware,
+  appendVary,
+};

package/core/compression/negotiate.js

@@ -0,0 +1,165 @@
+/**
+ * HTTP Compression Negotiation Utilities
+ * Parses Accept-Encoding headers with quality (q-value) support, wildcards, and algorithm selection.
+ * @module core/compression/negotiate
+ */
+
+const zlib = require('zlib');
+
+/**
+ * Check if Brotli compression is supported by the runtime
+ * @returns {boolean}
+ */
+function supportsBrotli() {
+  return typeof zlib.createBrotliCompress === 'function';
+}
+
+/**
+ * Available server-side encodings in preference order
+ * @param {boolean} [includeBrotli=true]
+ * @returns {string[]}
+ */
+function getDefaultSupportedEncodings(includeBrotli = true) {
+  const encodings = [];
+  if (includeBrotli && supportsBrotli()) {
+    encodings.push('br');
+  }
+  encodings.push('gzip', 'deflate');
+  return encodings;
+}
+
+/**
+ * Parse an Accept-Encoding header into structured entries with q-values
+ * @param {string|undefined|null} header
+ * @returns {Array<{ encoding: string, q: number, index: number }>}
+ */
+function parseAcceptEncoding(header) {
+  if (!header || typeof header !== 'string') {
+    return [];
+  }
+
+  const raw = header.trim();
+  if (!raw) return [];
+
+  const parts = raw.split(',');
+  const results = [];
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i].trim();
+    if (!part) continue;
+
+    const [encPart, ...params] = part.split(';');
+    const encoding = encPart.trim().toLowerCase();
+    if (!encoding) continue;
+
+    let q = 1.0;
+    for (const param of params) {
+      const trimmed = param.trim();
+      if (trimmed.startsWith('q=')) {
+        const val = parseFloat(trimmed.slice(2));
+        if (!isNaN(val)) {
+          q = Math.max(0, Math.min(1, val));
+        }
+      }
+    }
+
+    results.push({ encoding, q, index: i });
+  }
+
+  return results;
+}
+
+const selectEncodingCache = new Map();
+const MAX_ENCODING_CACHE_SIZE = 128;
+
+/**
+ * Select the best compression encoding given client header and server supported list
+ * @param {string|undefined|null} acceptEncoding - The Accept-Encoding header value
+ * @param {string[]} [supportedEncodings] - Server supported encodings in preference order
+ * @returns {string|null} The selected encoding ('br', 'gzip', 'deflate', 'identity', or null)
+ */
+function selectEncoding(acceptEncoding, supportedEncodings) {
+  if (!acceptEncoding) {
+    return 'identity';
+  }
+
+  const supported = Array.isArray(supportedEncodings) && supportedEncodings.length > 0
+    ? supportedEncodings.map(e => e.toLowerCase()).filter(e => e !== 'br' || supportsBrotli())
+    : getDefaultSupportedEncodings();
+
+  const cacheKey = `${acceptEncoding}|${supported.join(',')}`;
+  const cached = selectEncodingCache.get(cacheKey);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const clientPreferences = parseAcceptEncoding(acceptEncoding);
+  if (clientPreferences.length === 0) {
+    if (selectEncodingCache.size < MAX_ENCODING_CACHE_SIZE) {
+      selectEncodingCache.set(cacheKey, 'identity');
+    }
+    return 'identity';
+  }
+
+  // Create lookup for explicit preferences
+  const prefMap = new Map();
+  let wildcardQ = null;
+
+  for (const item of clientPreferences) {
+    if (item.encoding === '*') {
+      wildcardQ = item.q;
+    } else {
+      prefMap.set(item.encoding, item.q);
+    }
+  }
+
+  // If identity is explicitly forbidden (q=0) and no other encoding matches, we must handle carefully
+  const identityQ = prefMap.has('identity') ? prefMap.get('identity') : (wildcardQ !== null ? wildcardQ : 1.0);
+
+  // Score candidate encodings
+  let bestEncoding = null;
+  let bestQ = 0;
+  let bestServerPriority = Infinity;
+
+  for (let priority = 0; priority < supported.length; priority++) {
+    const candidate = supported[priority];
+    let q = 0;
+
+    if (prefMap.has(candidate)) {
+      q = prefMap.get(candidate);
+    } else if (wildcardQ !== null) {
+      q = wildcardQ;
+    }
+
+    // Must have positive q-value to be considered
+    if (q > 0) {
+      if (q > bestQ || (q === bestQ && priority < bestServerPriority)) {
+        bestQ = q;
+        bestEncoding = candidate;
+        bestServerPriority = priority;
+      }
+    }
+  }
+
+  let result = null;
+  if (bestEncoding && bestQ > 0) {
+    result = bestEncoding;
+  } else if (prefMap.has('identity')) {
+    result = prefMap.get('identity') > 0 ? 'identity' : null;
+  } else if (wildcardQ !== null) {
+    result = wildcardQ > 0 ? 'identity' : null;
+  }
+
+  if (selectEncodingCache.size < MAX_ENCODING_CACHE_SIZE) {
+    selectEncodingCache.set(cacheKey, result);
+  }
+
+  return result;
+}
+
+module.exports = {
+  supportsBrotli,
+  getDefaultSupportedEncodings,
+  parseAcceptEncoding,
+  selectEncoding,
+};

package/core/errors/base.js

@@ -0,0 +1,31 @@
+/**
+ * Base Webspresso Error Class
+ * @module core/errors/base
+ */
+
+class WebspressoError extends Error {
+  /**
+   * @param {string} 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 {number} [options.status] - Optional HTTP status code mapping
+   */
+  constructor(message, options = {}) {
+    super(message, {
+      cause: options.cause,
+    });
+
+    this.name = this.constructor.name;
+    this.code = options.code;
+    this.details = options.details;
+    if (typeof options.status === 'number') {
+      this.status = options.status;
+    }
+  }
+}
+
+module.exports = {
+  WebspressoError,
+};

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