webhoster 0.1.1 → 0.3.0

package/middleware/ContentEncoderMiddleware.js

@@ -1,44 +1,56 @@
-import { Transform } from 'stream';
-import { createBrotliCompress, createDeflate, createGzip } from 'zlib';
+import { promisify } from 'node:util';
+import {
+  // @ts-expect-error Bad types
+  BrotliCompress, Deflate, Gzip,
+  constants as ZlibContants,
+  brotliCompress, brotliCompressSync,
+  deflate, deflateSync,
+  gzip, gzipSync,
+} from 'node:zlib';
 
 import { parseQualityValues } from '../utils/qualityValues.js';
 
-/** @typedef {import('../types').IMiddleware} IMiddleware */
+const { BROTLI_OPERATION_FLUSH, Z_SYNC_FLUSH } = ZlibContants;
+
+/** @typedef {import('http').IncomingHttpHeaders} IncomingHttpHeaders */
+/** @typedef {import('../lib/HttpRequest.js').default} HttpRequest */
+/** @typedef {import('../lib/HttpResponse.js').default} HttpResponse */
 /** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
-/** @typedef {import('../types').MiddlewareFunctionParams} MiddlewareFunctionParams */
-/** @typedef {import('../types').MiddlewareFunctionResult} MiddlewareFunctionResult */
+/** @typedef {import('../types').ResponseFinalizer} ResponseFinalizer */
 
 /** @typedef {'br'|'gzip'|'deflate'|'identity'|'*'} COMPATIBLE_ENCODING */
 
 const DEFAULT_MINIMUM_SIZE = 256;
 
+const DEFAULT_ASYNC_THRESHOLD = 64 * 1024;
+
 /**
  * @typedef ContentEncoderMiddlewareOptions
  * @prop {number} [chunkSize]
  * @prop {boolean} [respondNotAcceptable=false]
  * @prop {'br'|'gzip'|'deflate'|'identity'} [preferredEncoding='identity']
+ * Minimum content size before using any compression
  * @prop {number} [minimumSize=DEFAULT_MINIMUM_SIZE]
+ * Minimum content size before using async compression
+ * @prop {number} [asyncThreshold=DEFAULT_ASYNC_THRESHOLD]
  */
 
 /** @type {COMPATIBLE_ENCODING[]} */
 const COMPATIBLE_ENCODINGS = ['br', 'gzip', 'deflate', 'identity', '*'];
 
-/** @implements {IMiddleware} */
 export default class ContentEncoderMiddleware {
-  /** @param {ContentEncoderMiddlewareOptions} [options] */
-  constructor(options = {}) {
-    this.chunkSize = options.chunkSize;
-    this.respondNotAcceptable = options.respondNotAcceptable === true;
-    this.preferredEncoding = options.preferredEncoding ?? 'identity';
-    this.minimumSize = options.minimumSize ?? DEFAULT_MINIMUM_SIZE;
-  }
+  static BrotliCompressAsync = promisify(brotliCompress);
+
+  static GzipAsync = promisify(gzip);
+
+  static DeflateAsync = promisify(deflate);
 
   /**
-   * @param {import('../types/index.js').HttpRequest} req
+   * @param {IncomingHttpHeaders} headers
    * @throws {NotAcceptableException} Error with `NOT_ACCEPTIBLE` message
    * @return {COMPATIBLE_ENCODING}
    */
-  static chooseEncoding(req) {
+  static chooseEncoding(headers) {
   /**
    * A request without an Accept-Encoding header field implies that the
    * user agent has no preferences regarding content-codings.  Although
@@ -46,12 +58,11 @@ export default class ContentEncoderMiddleware {
    * does not imply that the user agent will be able to correctly process
    * all encodings.
    */
-    if ('accept-encoding' in req.headers === false) {
+    if ('accept-encoding' in headers === false) {
       return '*';
     }
 
-    /** @type {string} */
-    const acceptString = (req.headers['accept-encoding']);
+    const acceptString = /** @type {string} */ (headers['accept-encoding']);
     const encodings = parseQualityValues(acceptString?.toLowerCase());
     if (!encodings.size) {
     /**
@@ -64,18 +75,18 @@ export default class ContentEncoderMiddleware {
     let encoding = COMPATIBLE_ENCODINGS[0];
     const allowWildcards = (encodings.get('*')?.q !== 0);
     const encodingEntries = [...encodings.entries()];
-    // @ts-ignore Cannot cast to COMPATIBLE_ENCODINGS
+    // @ts-expect-error Cannot cast to COMPATIBLE_ENCODINGS
     encoding = (encodingEntries.find(([value, spec]) => spec.q !== 0 && COMPATIBLE_ENCODINGS.includes(value))?.[0]);
     if (allowWildcards && (encoding === '*' || !encoding)) {
-    // Server preference
-    // Get first compatible encoding not specified
+      // Server preference
+      // Get first compatible encoding not specified
       encoding = COMPATIBLE_ENCODINGS.find((value) => !encodings.has(value));
     }
     if (allowWildcards && !encoding) {
-    // Get highest q'd compatible encoding not q=0 or '*'
-    // @ts-ignore Cannot cast to COMPATIBLE_ENCODINGS
-      encoding = encodingEntries
-      // @ts-ignore Cannot cast to COMPATIBLE_ENCODINGS
+      // Get highest q'd compatible encoding not q=0 or '*'
+      // @ts-expect-error Cannot cast to COMPATIBLE_ENCODINGS
+      encoding = /** @type {COMPATIBLE_ENCODINGS} */ encodingEntries
+      // @ts-expect-error Cannot cast to COMPATIBLE_ENCODINGS
         .find(([value, spec]) => spec.q !== 0 && value !== '*' && COMPATIBLE_ENCODINGS.includes(value))?.[0];
     }
     if (!encoding) {
@@ -84,28 +95,32 @@ export default class ContentEncoderMiddleware {
     return encoding;
   }
 
+  /** @param {ContentEncoderMiddlewareOptions} [options] */
+  constructor(options = {}) {
+    this.chunkSize = options.chunkSize;
+    this.respondNotAcceptable = options.respondNotAcceptable === true;
+    this.preferredEncoding = options.preferredEncoding ?? 'identity';
+    this.minimumSize = options.minimumSize ?? DEFAULT_MINIMUM_SIZE;
+    this.asyncThreshold = options.asyncThreshold ?? DEFAULT_ASYNC_THRESHOLD;
+    this.finalizeResponse = this.finalizeResponse.bind(this);
+  }
+
   /**
-   * Implements `Accept-Encoding`
-   * https://tools.ietf.org/html/rfc7231#section-5.3.4
-   * @param {MiddlewareFunctionParams} params
-   * @return {MiddlewareFunctionResult}
+   * @param {HttpResponse} response
+   * @return {void}
    */
-  execute({ req, res }) {
-    if (req.method === 'HEAD') {
-    // Never needs content-encoding
-      return 'continue';
-    }
-
+  addTransformStream(response) {
     /** @type {COMPATIBLE_ENCODING} */
     let parsedEncoding;
     if (this.respondNotAcceptable) {
-    // Parse now to catch the error;
+      // Parse now to catch the error;
       try {
-        parsedEncoding = ContentEncoderMiddleware.chooseEncoding(req);
+        parsedEncoding = ContentEncoderMiddleware.chooseEncoding(response.request.headers);
       } catch (error) {
         if (error?.message === 'NOT_ACCEPTABLE') {
-          res.status = 406;
-          return 'end';
+          response.status = 406;
+          response.end();
+          throw new Error('NOT_ACCEPTABLE');
         }
         // Unknown error
         throw error;
@@ -116,7 +131,7 @@ export default class ContentEncoderMiddleware {
     const getContentEncoding = () => {
       if (!parsedEncoding) {
         try {
-          parsedEncoding = ContentEncoderMiddleware.chooseEncoding(req);
+          parsedEncoding = ContentEncoderMiddleware.chooseEncoding(response.request.headers);
         } catch (error) {
           if (error?.message !== 'NOT_ACCEPTABLE') {
             throw error;
@@ -126,118 +141,150 @@ export default class ContentEncoderMiddleware {
       if (!parsedEncoding || parsedEncoding === '*') {
         parsedEncoding = this.preferredEncoding || 'identity';
       }
-      res.headers['content-encoding'] = parsedEncoding;
+      response.headers['content-encoding'] = parsedEncoding;
       return parsedEncoding;
     };
 
-    let finalCalled = false;
-    let transformCount = 0;
-    let inputLength = 0;
-    const newStream = new Transform({
-      transform(chunk, encoding, callback) {
-        transformCount += 1;
-        inputLength += chunk.length;
-        // Stall to see if more chunks are in transit
-        process.nextTick(() => {
-          this.push(chunk);
+    let encoding = response.request.headers['content-encoding'];
+    // Only continue if unset (missing header). Blank is still considered set.
+    // This allows forced encoding (eg: use gzip regardless of size; always identity)
+
+    // Unset means server preference
+    if (encoding == null) {
+      encoding = getContentEncoding().toLowerCase?.();
+    }
+
+    const isEventStream = response.headers['content-type']?.includes('text/event-stream');
+
+    let newStream;
+    switch (encoding) {
+      case 'br':
+        // @ts-expect-error Bad types
+        newStream = new BrotliCompress({
+          chunkSize: this.chunkSize,
+          flush: isEventStream ? BROTLI_OPERATION_FLUSH : undefined,
         });
-        callback();
-      },
-      final(callback) {
-        finalCalled = true;
-        callback();
-      },
-    });
-    const destination = res.replaceStream(newStream);
+        break;
+      case 'gzip':
+        // @ts-expect-error Bad types
+        newStream = new Gzip({
+          chunkSize: this.chunkSize,
+          flush: isEventStream ? Z_SYNC_FLUSH : undefined,
+        });
+        break;
+      case 'deflate':
+        // @ts-expect-error Bad types
+        newStream = new Deflate({
+          chunkSize: this.chunkSize,
+          flush: isEventStream ? Z_SYNC_FLUSH : undefined,
+        });
+        break;
+      default:
+        return;
+    }
+    response.pipes.push(newStream);
+  }
 
-    /**
-     * @param {'br'|'gzip'|'deflate'} encoding
-     * @return {import("zlib").Gzip}
-     */
-    const buildGzipStream = (encoding) => {
-      /** @type {import("zlib").Gzip} */
-      let gzipStream;
-      switch (encoding) {
-        case 'deflate':
-          gzipStream = createDeflate({ chunkSize: this.chunkSize });
-          break;
-        case 'gzip':
-          gzipStream = createGzip({ chunkSize: this.chunkSize });
-          break;
-        case 'br':
-          gzipStream = createBrotliCompress({ chunkSize: this.chunkSize });
-          break;
-        default:
-          throw new Error('UNKNOWN_ENCODING');
-      }
+  /** @type {ResponseFinalizer} */
+  finalizeResponse(response) {
+    if (response.isStreaming) {
+      this.addTransformStream(response);
+      return true;
+    }
 
-      /** @type {Buffer[]} */
-      const pendingChunks = [];
-
-      gzipStream.on('data', (chunk) => {
-        if (finalCalled) {
-          pendingChunks.push(chunk);
-        } else {
-          let previousChunk;
-          // eslint-disable-next-line no-cond-assign
-          while (previousChunk = pendingChunks.shift()) {
-            destination.write(previousChunk);
-          }
-          destination.write(chunk);
-        }
-      });
-      gzipStream.on('end', () => {
-        let chunk;
-        // eslint-disable-next-line no-cond-assign
-        while (chunk = pendingChunks.shift()) {
-          destination.write(chunk);
+    if (response.body == null) return true;
+
+    /** @type {COMPATIBLE_ENCODING} */
+    let parsedEncoding;
+    if (this.respondNotAcceptable) {
+      // Parse now to catch the error;
+      try {
+        parsedEncoding = ContentEncoderMiddleware.chooseEncoding(response.request.headers);
+      } catch (error) {
+        if (error?.message === 'NOT_ACCEPTABLE') {
+          // Strip content
+          response.body = null;
+          response.status = 206;
+          return false;
         }
-        destination.end();
-      });
+        // Unknown error
+        throw error;
+      }
+    }
 
-      return gzipStream;
-    };
+    if (!Buffer.isBuffer(response.body)) return true;
 
-    // Don't do any work until first chunk is received (if at all).
-    // This allows middleware to set `Content-Encoding` manually,
-    // prevents allocation memory for a gzip stream unnecessarily, and
-    // prevents polluting 204 responses.
-
-    const onEnd = () => destination.end();
-    newStream.once('data', (chunk) => {
-    // Will be handled by .pipe() or .end() call
-      newStream.off('end', onEnd);
-
-      /** @type {string} */
-      let encoding = (res.headers['content-encoding']);
-      if (encoding == null) {
-      // Only continue if unset. Blank is still considered set.
-      // This allows forced encoding (eg: use gzip regardless of size; always identity)
-        if (inputLength > (this.minimumSize ?? DEFAULT_MINIMUM_SIZE) || transformCount > 1) {
-        // If we're getting data in chunks, assume larger than minimum
-          encoding = getContentEncoding().toLowerCase?.();
-        } else {
-          encoding = 'identity';
+    /** @return {string} */
+    const getContentEncoding = () => {
+      if (!parsedEncoding) {
+        try {
+          parsedEncoding = ContentEncoderMiddleware.chooseEncoding(response.request.headers);
+        } catch (error) {
+          if (error?.message !== 'NOT_ACCEPTABLE') {
+            throw error;
+          }
         }
       }
+      if (!parsedEncoding || parsedEncoding === '*') {
+        parsedEncoding = this.preferredEncoding || 'identity';
+      }
+      response.headers['content-encoding'] = parsedEncoding;
+      return parsedEncoding;
+    };
 
-      let next;
+    let encoding = /** @type {string} */ (response.headers['content-encoding']);
+    // Only continue if unset (missing header). Blank is still considered set.
+    // This allows forced encoding (eg: use gzip regardless of size; always identity)
+
+    // Unset means server preference
+    if (encoding == null) {
+      encoding = (response.body.length < this.minimumSize) ? 'identity' : getContentEncoding().toLowerCase?.();
+    }
+
+    const options = { chunkSize: this.chunkSize };
+
+    if (response.body.length < this.asyncThreshold) {
       switch (encoding) {
         case 'br':
+          response.body = brotliCompressSync(response.body, options);
+          break;
         case 'gzip':
+          response.body = gzipSync(response.body, options);
+          break;
         case 'deflate':
-          next = buildGzipStream(encoding);
+          response.body = deflateSync(response.body, options);
           break;
         default:
-          next = destination;
       }
-      next.write(chunk);
-      newStream.pipe(next);
-    });
+      return true;
+    }
 
-    // In case no data is passed
-    newStream.on('end', onEnd);
+    let promise;
+    switch (encoding) {
+      case 'br':
+        promise = ContentEncoderMiddleware.BrotliCompressAsync(response.body, options);
+        break;
+      case 'gzip':
+        promise = ContentEncoderMiddleware.GzipAsync(response.body, options);
+        break;
+      case 'deflate':
+        promise = ContentEncoderMiddleware.DeflateAsync(response.body, options);
+        break;
+      default:
+        return true;
+    }
+    return promise.then((result) => {
+      response.body = result;
+      return true;
+    });
+  }
 
-    return 'continue';
+  /**
+   * Implements `Accept-Encoding`
+   * https://tools.ietf.org/html/rfc7231#section-5.3.4
+   * @type {MiddlewareFunction}
+   */
+  execute({ response }) {
+    response.finalizers.push(this.finalizeResponse);
   }
 }

package/middleware/ContentLengthMiddleware.js

@@ -1,65 +1,67 @@
-import { Transform } from 'stream';
-
-/** @typedef {import('../types').IMiddleware} IMiddleware */
+/** @typedef {import('../lib/HttpResponse.js').default} HttpResponse */
 /** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
-/** @typedef {import('../types').MiddlewareFunctionParams} MiddlewareFunctionParams */
-/** @typedef {import('../types').MiddlewareFunctionResult} MiddlewareFunctionResult */
+/** @typedef {import('../types').ResponseFinalizer} ResponseFinalizer */
+
+import { Transform } from 'node:stream';
 
 /**
  * @typedef {Object} ContentLengthMiddlewareOptions
- * @prop {boolean} [delayCycle=true]
- * Delays writing to stream by one I/O cycle.
+ * @prop {number} [delayCycles=2]
+ * Delays writing to stream by setTimeout cycles when piping.
  * If `.end()` is called on the same event loop as write, then the
  * content length can be still calculated despite receiving data in chunks.
- * Compared to no delay, chunks are held in memory for two event loops instead
- * of just one.
  * @prop {boolean} [overrideHeader=false]
  * Always replace `Content-Length` header
  */
 
-/** @implements {IMiddleware} */
 export default class ContentLengthMiddleware {
   /** @param {ContentLengthMiddlewareOptions} [options] */
   constructor(options = {}) {
-    this.delayCycle = options.delayCycle !== false;
+    this.delayCycles = options.delayCycles ?? 2;
     this.overrideHeader = options.overrideHeader !== true;
+    this.finalizeResponse = this.finalizeResponse.bind(this);
   }
 
   /**
-   * @param {MiddlewareFunctionParams} params
-   * @return {MiddlewareFunctionResult}
+   * @param {HttpResponse} response
+   * @return {void}
    */
-  execute({ req, res }) {
-    if (req.method === 'HEAD') {
-      return 'continue';
-    }
-
+  addTransformStream(response) {
+    if (response.headersSent) return;
+    let { delayCycles } = this;
+    const { overrideHeader } = this;
+    if (response.headers['content-length'] && !overrideHeader) return;
     let length = 0;
     /** @type {Buffer[]} */
     const pendingChunks = [];
-    let delayPending = false;
-    const { delayCycle, overrideHeader } = this;
-    const newWritable = new Transform({
+    response.pipes.push(new Transform({
+      objectMode: true,
       transform(chunk, encoding, callback) {
         length += chunk.length;
-        if (delayCycle === false) {
+        if (!delayCycles) {
           callback(null, chunk);
           return;
         }
 
         pendingChunks.push(chunk);
-        if (!delayPending) {
-          delayPending = true;
-          process.nextTick(() => setImmediate(() => {
-            delayPending = false;
-            pendingChunks.splice(0, pendingChunks.length)
-              .forEach((buffer) => this.push(buffer));
-          }));
+        // eslint-disable-next-line no-underscore-dangle, unicorn/consistent-function-scoping
+        let fn = () => this._flush(() => { /** noop */ });
+        for (let i = 0; i < delayCycles; i++) {
+          const prev = fn;
+          fn = () => setTimeout(prev);
         }
+        fn();
         callback();
       },
       flush(callback) {
-        if (!res.headersSent) {
+        for (const buffer of pendingChunks.splice(0, pendingChunks.length)) {
+          this.push(buffer);
+        }
+        delayCycles = 0;
+        callback?.();
+      },
+      final(callback) {
+        if (!response.headersSent) {
         /**
          * Any response message which "MUST NOT" include a message-body
          * (such as the 1xx, 204, and 304 responses and any response to a HEAD request)
@@ -67,23 +69,46 @@ export default class ContentLengthMiddleware {
          * regardless of the entity-header fields present in the message.
          * https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.4
          */
-          if ((res.status >= 100 && res.status < 200) || res.status === 204 || res.status === 304) {
+          if ((response.status >= 100 && response.status < 200) || response.status === 204 || response.status === 304) {
             if (overrideHeader) {
-              delete res.headers['content-length'];
+              delete response.headers['content-length'];
             }
-          } else if (overrideHeader === true || res.headers['content-length'] == null) {
-            res.headers['content-length'] = length;
+          } else if (overrideHeader === true || response.headers['content-length'] == null) {
+            response.headers['content-length'] = length;
           }
         }
-        pendingChunks.splice(0, pendingChunks.length)
-          .forEach((buffer) => this.push(buffer));
-        callback();
+        callback?.();
       },
-    });
+    }));
+  }
 
-    const destination = res.replaceStream(newWritable);
-    newWritable.pipe(destination);
+  /** @type {ResponseFinalizer} */
+  finalizeResponse(response) {
+    if (response.headersSent) return;
+    if (response.isStreaming) {
+      this.addTransformStream(response);
+      return;
+    }
+    if (!Buffer.isBuffer(response.body)) return;
+    if (!response.body.byteLength) return;
+    /**
+     * Any response message which "MUST NOT" include a message-body
+     * (such as the 1xx, 204, and 304 responses and any response to a HEAD request)
+     * is always terminated by the first empty line after the header fields,
+     * regardless of the entity-header fields present in the message.
+     * https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.4
+     */
+    if (response.status === 204 || response.status === 304 || (response.status >= 100 && response.status < 200)) {
+      if (this.overrideHeader) {
+        delete response.headers['content-length'];
+      }
+    } else if (this.overrideHeader === true || response.headers['content-length'] == null) {
+      response.headers['content-length'] = response.body.byteLength;
+    }
+  }
 
-    return 'continue';
+  /** @type {MiddlewareFunction} */
+  execute({ response }) {
+    response.finalizers.push(this.finalizeResponse);
   }
 }

package/middleware/ContentWriterMiddleware.js

@@ -1,4 +1,4 @@
-import { Transform } from 'stream';
+import { Transform } from 'node:stream';
 
 /** @typedef {import('../types').IMiddleware} IMiddleware */
 /** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
@@ -42,13 +42,13 @@ export default class ContentWriterMiddleware {
       case 'ucs2':
       case 'utf16le':
         return 'utf16le';
-      default:
-      case 'utf-8':
-      case 'utf8':
-        return 'utf-8';
       case 'base64':
       case 'hex':
         return /** @type {BufferEncoding} */ (charset);
+      case 'utf-8':
+      case 'utf8':
+      default:
+        return 'utf-8';
     }
   }