webspresso 0.0.90 → 0.0.91

package/core/compression/compression-stream.js

@@ -0,0 +1,59 @@
+/**
+ * Compression Stream Factory
+ * Instantiates native node:zlib transform streams (brotli, gzip, deflate).
+ * @module core/compression/compression-stream
+ */
+
+const zlib = require('zlib');
+const { supportsBrotli } = require('./negotiate');
+
+/**
+ * Create a zlib compression transform stream based on encoding
+ * @param {'br'|'gzip'|'deflate'} encoding
+ * @param {Object} [options]
+ * @param {number} [options.level=6] - Default compression level (0-9 for gzip/deflate, 0-11 for brotli)
+ * @param {Object} [options.brotli] - Custom options for zlib.createBrotliCompress
+ * @param {Object} [options.gzip] - Custom options for zlib.createGzip
+ * @param {Object} [options.deflate] - Custom options for zlib.createDeflate
+ * @returns {import('stream').Transform|null}
+ */
+function createCompressionStream(encoding, options = {}) {
+  const enc = (encoding || '').toLowerCase();
+  const level = typeof options.level === 'number' ? options.level : 6;
+
+  switch (enc) {
+    case 'br': {
+      if (!supportsBrotli()) {
+        return null;
+      }
+      const brotliOpts = { ...(options.brotli || {}) };
+      if (!brotliOpts.params) {
+        brotliOpts.params = {};
+      }
+      if (brotliOpts.params[zlib.constants.BROTLI_PARAM_QUALITY] === undefined) {
+        // Brotli quality 4 is standard for dynamic HTTP compression (fast & high ratio)
+        brotliOpts.params[zlib.constants.BROTLI_PARAM_QUALITY] = typeof options.brotli?.quality === 'number'
+          ? options.brotli.quality
+          : (options.level !== undefined ? options.level : 4);
+      }
+      return zlib.createBrotliCompress(brotliOpts);
+    }
+
+    case 'gzip': {
+      const gzipOpts = { level, ...(options.gzip || {}) };
+      return zlib.createGzip(gzipOpts);
+    }
+
+    case 'deflate': {
+      const deflateOpts = { level, ...(options.deflate || {}) };
+      return zlib.createDeflate(deflateOpts);
+    }
+
+    default:
+      return null;
+  }
+}
+
+module.exports = {
+  createCompressionStream,
+};

package/core/compression/index.js

@@ -0,0 +1,25 @@
+/**
+ * Webspresso HTTP Response Compression Module
+ * @module core/compression
+ */
+
+const {
+  supportsBrotli,
+  getDefaultSupportedEncodings,
+  parseAcceptEncoding,
+  selectEncoding,
+} = require('./negotiate');
+const { isCompressible } = require('./compressible');
+const { createCompressionStream } = require('./compression-stream');
+const { createCompressionMiddleware, appendVary } = require('./middleware');
+
+module.exports = {
+  supportsBrotli,
+  getDefaultSupportedEncodings,
+  parseAcceptEncoding,
+  selectEncoding,
+  isCompressible,
+  createCompressionStream,
+  createCompressionMiddleware,
+  appendVary,
+};

package/core/compression/middleware.js

@@ -0,0 +1,301 @@
+/**
+ * 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();
+          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,153 @@
+/**
+ * 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;
+}
+
+/**
+ * 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) {
+  const supported = Array.isArray(supportedEncodings) && supportedEncodings.length > 0
+    ? supportedEncodings.map(e => e.toLowerCase()).filter(e => e !== 'br' || supportsBrotli())
+    : getDefaultSupportedEncodings();
+
+  if (!acceptEncoding) {
+    return 'identity';
+  }
+
+  const clientPreferences = parseAcceptEncoding(acceptEncoding);
+  if (clientPreferences.length === 0) {
+    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;
+      }
+    }
+  }
+
+  if (bestEncoding && bestQ > 0) {
+    return bestEncoding;
+  }
+
+  // If no compressed encoding was chosen:
+  // If identity or wildcard was explicitly specified, check their q values
+  if (prefMap.has('identity')) {
+    return prefMap.get('identity') > 0 ? 'identity' : null;
+  }
+  if (wildcardQ !== null) {
+    return wildcardQ > 0 ? 'identity' : null;
+  }
+
+  return null;
+}
+
+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,
+};