webhoster 0.1.1 → 0.3.1

package/middleware/HashMiddleware.js

@@ -1,81 +1,109 @@
-import crypto from 'crypto';
-import { Transform } from 'stream';
+import { createHash } from 'node:crypto';
+import { Transform } from 'node:stream';
 
-/** @typedef {import('../types').IMiddleware} IMiddleware */
-/** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
-/** @typedef {import('../types').MiddlewareFunctionParams} MiddlewareFunctionParams */
-/** @typedef {import('../types').MiddlewareFunctionResult} MiddlewareFunctionResult */
+/** @typedef {import('node:crypto').BinaryToTextEncoding} BinaryToTextEncoding */
+/** @typedef {import('../lib/HttpRequest.js').default} HttpRequest */
+/** @typedef {import('../lib/HttpResponse.js').default} HttpResponse */
+/** @typedef {import('../types/index.js').MiddlewareFunction} MiddlewareFunction */
+/** @typedef {import('../types/index.js').ResponseFinalizer} ResponseFinalizer */
 
 const DEFAULT_ALGORITHM = 'sha1';
-/** @type {crypto.HexBase64Latin1Encoding} */
+/** @type {BinaryToTextEncoding} */
 const DEFAULT_DIGEST = 'base64';
 
 /**
  * @typedef {Object} HashMiddlewareOptions
  * @prop {'md5'|'sha1'|'sha256'|'sha512'} [algorithm=DEFAULT_ALGORITHM]
- * @prop {crypto.HexBase64Latin1Encoding} [digest=DEFAULT_DIGEST]
+ * @prop {BinaryToTextEncoding} [digest=DEFAULT_DIGEST]
  */
 
-/** @implements {IMiddleware} */
 export default class HashMiddleware {
   /** @param {HashMiddlewareOptions} options */
   constructor(options = {}) {
     this.algorithm = options.algorithm || DEFAULT_ALGORITHM;
     this.digest = options.digest || DEFAULT_DIGEST;
+    this.finalizeResponse = this.finalizeResponse.bind(this);
   }
 
   /**
-   * @param {MiddlewareFunctionParams} params
-   * @return {MiddlewareFunctionResult}
+   * @param {HttpResponse} response
+   * @return {void}
    */
-  execute({ res }) {
+  addTransformStream(response) {
+    if (response.headers.etag != null || response.headers.digest != null) return;
+
     const { algorithm, digest } = this;
     let hasData = false;
     let length = 0;
     let abort = false;
-    const hashStream = crypto.createHash(algorithm);
-    const newWritable = new Transform({
+    const hashStream = createHash(algorithm);
+    response.pipes.push(new Transform({
+      objectMode: true,
       transform(chunk, encoding, callback) {
         length += chunk.length;
         hasData = true;
-        if (!abort && res.headersSent) {
-          abort = true;
-          hashStream.destroy();
-        }
-        if (abort) {
-          callback(null, chunk);
-          return;
-        }
-        // Manually pipe
-        const needsDrain = !hashStream.write(chunk);
-        if (needsDrain) {
-          hashStream.once('drain', () => {
-            callback(null, chunk);
-          });
-        } else {
-          callback(null, chunk);
+
+        if (!abort) {
+          if (response.headersSent) {
+            abort = true;
+            hashStream.destroy();
+          } else {
+            // Manually pipe
+            const isSync = hashStream.write(chunk, (error) => {
+              if (!isSync) {
+                callback(error, chunk);
+              }
+            });
+            if (!isSync) return;
+          }
         }
+        callback(null, chunk);
       },
-      flush(callback) {
-        if (!abort && hasData && res.status !== 206 && !res.headersSent) {
+      final(callback) {
+        if (!abort && hasData && response.status !== 206 && !response.headersSent) {
           const hash = hashStream.digest(digest);
           // https://tools.ietf.org/html/rfc7232#section-2.3
-          if (res.headers.etag == null) {
-            res.headers.etag = `${algorithm === 'md5' ? 'W/' : ''}"${length.toString(16)}-${hash}"`;
+          if (response.headers.etag == null) {
+            response.headers.etag = `${algorithm === 'md5' ? 'W/' : ''}"${length.toString(16)}-${hash}"`;
           }
           if (digest === 'base64') {
-            res.headers.digest = `${algorithm}=${hash}`;
+            response.headers.digest = `${algorithm}=${hash}`;
             if ((algorithm === 'md5')) {
-              res.headers['content-md5'] = hash;
+              response.headers['content-md5'] = hash;
             }
           }
         }
         callback();
       },
-    });
+    }));
+  }
+
+  /** @type {ResponseFinalizer} */
+  finalizeResponse(response) {
+    if (response.status === 206 || response.body == null) return;
+    if (response.isStreaming) {
+      this.addTransformStream(response);
+      return;
+    }
+    if (!Buffer.isBuffer(response.body) || response.body.byteLength === 0) return;
+
+    const { algorithm, digest } = this;
+    const hash = createHash(algorithm).update(response.body).digest(digest);
+
+    // https://tools.ietf.org/html/rfc7232#section-2.3
+    if (response.headers.etag == null) {
+      response.headers.etag = `${algorithm === 'md5' ? 'W/' : ''}"${response.body.byteLength.toString(16)}-${hash}"`;
+    }
+    if (digest === 'base64') {
+      response.headers.digest = `${algorithm}=${hash}`;
+      if ((algorithm === 'md5')) {
+        response.headers['content-md5'] = hash;
+      }
+    }
+  }
 
-    const destination = res.replaceStream(newWritable);
-    newWritable.pipe(destination);
-    return 'continue';
+  /** @type {MiddlewareFunction} */
+  execute({ response }) {
+    response.finalizers.push(this.finalizeResponse);
   }
 }

package/middleware/HeadMethodMiddleware.js

@@ -1,29 +1,32 @@
-import { PassThrough } from 'stream';
+/** @typedef {import('../types/index.js').HttpTransaction} HttpTransaction */
+/** @typedef {import('../types/index.js').MiddlewareFunction} MiddlewareFunction */
+/** @typedef {import('../types/index.js').ResponseFinalizer} ResponseFinalizer */
 
-/** @typedef {import('../types').IMiddleware} IMiddleware */
-/** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
-/** @typedef {import('../types').MiddlewareFunctionParams} MiddlewareFunctionParams */
-/** @typedef {import('../types').MiddlewareFunctionResult} MiddlewareFunctionResult */
+import { Transform } from 'node:stream';
 
-/** @implements {IMiddleware} */
 export default class HeadMethodMiddleware {
   constructor() {
-    this.execute = HeadMethodMiddleware.execute.bind(this);
+    this.execute = HeadMethodMiddleware.Execute.bind(this);
   }
 
-  /**
-   * @param {MiddlewareFunctionParams} params
-   * @return {MiddlewareFunctionResult}
-   */
-  static execute({ req, res }) {
-    if (req.method !== 'HEAD') {
-      return 'continue';
+  /** @type {ConstructorParameters<typeof Transform>[0]} */
+  static DEFAULT_TRANSFORM_OPTIONS = {
+    objectMode: true,
+    transform(chunk, encoding, callback) { callback(); },
+  };
+
+  /** @type {ResponseFinalizer} */
+  static FinalizeResponse(response) {
+    if (response.isStreaming) {
+      response.pipes.push(new Transform(HeadMethodMiddleware.DEFAULT_TRANSFORM_OPTIONS));
+      return;
     }
-    const newWritable = new PassThrough({});
-    const destination = res.replaceStream(newWritable);
-    newWritable.on('end', () => {
-      destination.end();
-    });
-    return 'continue';
+    response.body = null;
+  }
+
+  /** @type {MiddlewareFunction} */
+  static Execute({ request, response }) {
+    if (request.method !== 'HEAD') return;
+    response.finalizers.push(HeadMethodMiddleware.FinalizeResponse);
   }
-}
+}

package/middleware/MethodMiddleware.js

@@ -1,8 +1,5 @@
-/** @typedef {import('../lib').HttpRequest} HttpRequest */
-/** @typedef {import('../types').IMiddleware} IMiddleware */
+/** @typedef {import('../types').HttpTransaction} HttpTransaction */
 /** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
-/** @typedef {import('../types').MiddlewareFunctionParams} MiddlewareFunctionParams */
-/** @typedef {import('../types').MiddlewareFunctionResult} MiddlewareFunctionResult */
 /** @typedef {import('../types').RequestMethod} RequestMethod */
 
 /** @typedef {RegExp|RequestMethod} MethodEntry */
@@ -12,7 +9,6 @@
  * @prop {MethodEntry|MethodEntry[]} method
  */
 
-/** @implements {IMiddleware} */
 export default class MethodMiddleware {
   /** @param {MethodMiddlewareOptions|MethodEntry|MethodEntry[]} options */
   constructor(options) {
@@ -25,21 +21,9 @@ export default class MethodMiddleware {
     }
   }
 
-  /** @type {Map<RequestMethod, MethodMiddleware>} */
+  /** @type {Map<MethodEntry, MethodMiddleware>} */
   static cache = new Map();
 
-  /**
-   * @param {RequestMethod} name
-   * @return {MethodMiddleware}
-   */
-  static byMethod(name) {
-    let m = MethodMiddleware.cache.get(name);
-    if (m) return m;
-    m = new MethodMiddleware(name);
-    MethodMiddleware.cache.set(name, m);
-    return m;
-  }
-
   /**
    * @param {RequestMethod} method
    * @param {RegExp | string} input
@@ -52,34 +36,43 @@ export default class MethodMiddleware {
     return input.test(method) === true;
   }
 
-  /**
-   * @param {MiddlewareFunctionParams} params
-   * @return {MiddlewareFunctionResult}
-   */
-  execute({ req }) {
-    for (let i = 0; i < this.method.length; i++) {
-      if (MethodMiddleware.test(req.method, this.method[i])) {
-        return 'continue';
+  /** @type {MiddlewareFunction} */
+  execute({ request }) {
+    for (const method of this.method) {
+      if (MethodMiddleware.test(request.method, method)) {
+        return true;
       }
     }
-    return 'break';
+    return false;
   }
 
-  static get CONNECT() { return MethodMiddleware.byMethod('CONNECT'); }
+  /** @type {MiddlewareFunction} */
+  static CONNECT({ request }) { return request.method === 'CONNECT'; }
+
+  /** @type {MiddlewareFunction} */
+  static DELETE({ request }) { return request.method === 'DELETE'; }
 
-  static get DELETE() { return MethodMiddleware.byMethod('DELETE'); }
+  /** @type {MiddlewareFunction} */
+  static HEADORGET({ request }) { return request.method === 'HEAD' || request.method === 'GET'; }
 
-  static get GET() { return MethodMiddleware.byMethod('GET'); }
+  /** @type {MiddlewareFunction} */
+  static GET({ request }) { return request.method === 'GET'; }
 
-  static get OPTIONS() { return MethodMiddleware.byMethod('OPTIONS'); }
+  /** @type {MiddlewareFunction} */
+  static OPTIONS({ request }) { return request.method === 'OPTIONS'; }
 
-  static get HEAD() { return MethodMiddleware.byMethod('HEAD'); }
+  /** @type {MiddlewareFunction} */
+  static HEAD({ request }) { return request.method === 'HEAD'; }
 
-  static get PATCH() { return MethodMiddleware.byMethod('PATCH'); }
+  /** @type {MiddlewareFunction} */
+  static PATCH({ request }) { return request.method === 'PATCH'; }
 
-  static get POST() { return MethodMiddleware.byMethod('POST'); }
+  /** @type {MiddlewareFunction} */
+  static POST({ request }) { return request.method === 'POST'; }
 
-  static get PUT() { return MethodMiddleware.byMethod('PUT'); }
+  /** @type {MiddlewareFunction} */
+  static PUT({ request }) { return request.method === 'PUT'; }
 
-  static get TRACE() { return MethodMiddleware.byMethod('TRACE'); }
+  /** @type {MiddlewareFunction} */
+  static TRACE({ request }) { return request.method === 'TRACE'; }
 }

package/middleware/PathMiddleware.js

@@ -1,10 +1,8 @@
-import { join as joinPath, relative as relativePath } from 'path';
+import { posix } from 'node:path';
 
-/** @typedef {import('../types').HttpRequest} HttpRequest */
+/** @typedef {import('../types').HttpTransaction} HttpTransaction */
 /** @typedef {import('../types').IMiddleware} IMiddleware */
 /** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
-/** @typedef {import('../types').MiddlewareFunctionParams} MiddlewareFunctionParams */
-/** @typedef {import('../types').MiddlewareFunctionResult} MiddlewareFunctionResult */
 /** @typedef {import('../types').RequestMethod} RequestMethod */
 
 /** @typedef {RegExp|string} PathEntry */
@@ -24,42 +22,20 @@ import { join as joinPath, relative as relativePath } from 'path';
 /**
  * @typedef {Object} PathMiddlewareOptions
  * @prop {PathEntry|PathEntry[]} [path]
- * @prop {string} [key='path']
  * @prop {boolean} [absolute=false]
  * Path is not relative to previous PathMiddleware. Defaults to `false`.
  * @prop {boolean} [subPath=false]
  * Path values are subpaths. Default to `false`;
  */
 
-/** @implements {IMiddleware} */
 export default class PathMiddleware {
-  /** @param {PathMiddlewareOptions|PathEntry|PathEntry[]} options */
-  constructor(options) {
-    if (Array.isArray(options)) {
-      this.path = options;
-      this.key = 'path';
-      this.absolute = false;
-      this.subPath = false;
-    } else if (typeof options === 'string' || options instanceof RegExp) {
-      this.path = [options];
-      this.key = 'path';
-      this.absolute = false;
-      this.subPath = false;
-    } else {
-      this.path = Array.isArray(options.path) ? options.path : [options.path];
-      this.key = options.key || 'path';
-      this.absolute = options.absolute === true;
-      this.subPath = options.subPath === true;
-    }
-  }
-
   /**
    * @param {PathEntry|PathEntry[]} entry
    */
   static SUBPATH(entry) {
     const path = Array.isArray(entry) ? entry : [entry];
     return new PathMiddleware({
-      path: path.map((p) => (typeof p === 'string' ? RegExp(`^(${p})/*.*$`) : p)),
+      path: path.map((p) => (typeof p === 'string' ? new RegExp(`^(${p})($|(/.*$))`) : p)),
       subPath: true,
     });
   }
@@ -82,78 +58,85 @@ export default class PathMiddleware {
   }
 
   /**
-   * @param {HttpRequest} req
+   * @param {HttpTransaction} transaction
    * @param {string} base new base subpath
-   * @param {number[]} treeIndex this node's treeIndex
    * @param {string} currentPath
    * @return {void}
    */
-  writePathState(req, base, treeIndex, currentPath) {
-    /** @type {PathState} */
-    let state = req.locals[this.key];
-    if (!state) {
-      state = { history: [], currentPath };
-      req.locals[this.key] = state;
-    } else if (!state.history) {
-      state.history = [];
+  static WritePathState(transaction, base, currentPath) {
+    const { state } = transaction;
+    if (!state.path) {
+      state.path = { history: [], currentPath };
+    } else if (!state.path.history) {
+      state.path.history = [];
     }
-    state.history.push({ base, treeIndex: [...treeIndex] });
-    state.currentPath = currentPath;
+    state.path.history.push({ base, treeIndex: [...state.treeIndex] });
+    state.path.currentPath = currentPath;
   }
 
   /**
-   * @param {HttpRequest} req
-   * @param {number[]} treeIndex this node's treeIndex
+   * @param {HttpTransaction} transaction
    * @return {string} joined base path
    */
-  readPathState(req, treeIndex) {
-    /** @type {PathState} */
-    const state = req.locals[this.key];
-    if (!state || !state.history || !state.history.length) {
+  static ReadPathState(transaction) {
+    const { path, treeIndex } = transaction.state;
+    if (!path || !path.history || !path.history.length) {
       return '/';
     }
     const paths = [];
     let newLength = 0;
-    /* eslint-disable no-labels, no-restricted-syntax */
+    /* eslint-disable no-labels */
     historyLoop: {
-      for (let i = 0; i < state.history.length; i++) {
-        const item = state.history[i];
+      for (const item of path.history) {
         if (item.treeIndex.length >= treeIndex.length) break;
-        for (let j = 0; j < item.treeIndex.length - 1; j++) {
-          if (item.treeIndex[j] !== treeIndex[j]) break historyLoop;
+        // TODO: Confirm length-1
+        for (let index = 0; index < item.treeIndex.length - 1; index++) {
+          if (item.treeIndex[index] !== treeIndex[index]) break historyLoop;
         }
         paths.push(item.base);
         newLength++;
       }
     }
-    if (state.history.length !== newLength) {
-      state.history.length = newLength;
+    if (path.history.length !== newLength) {
+      path.history.length = newLength;
     }
     if (!paths.length) {
       return '/';
     }
-    return joinPath(...paths);
+    return posix.join(...paths);
   }
 
-  /**
-   * @param {MiddlewareFunctionParams} params
-   * @return {MiddlewareFunctionResult}
-   */
-  execute({ req, state }) {
-    const currentPath = this.absolute ? '' : this.readPathState(req, state.treeIndex);
-    const comparison = this.absolute ? req.url.pathname : `/${relativePath(currentPath, req.url.pathname)}`;
+  /** @param {PathMiddlewareOptions|PathEntry|PathEntry[]} options */
+  constructor(options) {
+    if (Array.isArray(options)) {
+      this.path = options;
+      this.absolute = false;
+      this.subPath = false;
+    } else if (typeof options === 'string' || options instanceof RegExp) {
+      this.path = [options];
+      this.absolute = false;
+      this.subPath = false;
+    } else {
+      this.path = Array.isArray(options.path) ? options.path : [options.path];
+      this.absolute = options.absolute === true;
+      this.subPath = options.subPath === true;
+    }
+  }
 
-    for (let i = 0; i < this.path.length; i++) {
-      const path = this.path[i];
+  /** @type {MiddlewareFunction} */
+  execute(transaction) {
+    const currentPath = this.absolute ? '' : PathMiddleware.ReadPathState(transaction);
+    const comparison = this.absolute ? transaction.request.pathname : `/${posix.relative(currentPath, transaction.request.pathname)}`;
+
+    for (const path of this.path) {
       const result = PathMiddleware.test(comparison, path);
       if (result) {
         if (this.subPath) {
-          this.writePathState(req, result, state.treeIndex, joinPath(currentPath, result));
+          PathMiddleware.WritePathState(transaction, result, posix.join(currentPath, result));
         }
-        return 'continue';
+        return true;
       }
     }
-
-    return 'break';
+    return false;
   }
 }

package/middleware/ReadFormData.js

@@ -0,0 +1,99 @@
+/** @typedef {import('../lib/HttpRequest.js').default} HttpRequest */
+/** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
+
+/**
+ * The application/x-www-form-urlencoded format is in many ways an aberrant monstrosity,
+ * the result of many years of implementation accidents and compromises leading to a set of
+ * requirements necessary for interoperability, but in no way representing good design practices.
+ * In particular, readers are cautioned to pay close attention to the twisted details
+ * involving repeated (and in some cases nested) conversions between character encodings and byte sequences.
+ * Unfortunately the format is in widespread use due to the prevalence of HTML forms. [HTML]
+ * @see https://url.spec.whatwg.org/#urlencoded-parsing
+ * @param {HttpRequest} request
+ * @return {Promise<FormData>}
+ */
+async function parseFormUrlEncoded(request) {
+  const output = new FormData();
+  // https://url.spec.whatwg.org/#urlencoded-parsing
+
+  const buffer = await request.buffer();
+  const { bufferEncoding } = request;
+
+  const sequences = [];
+  let startIndex = 0;
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (buffer[index] === 0x26) {
+      sequences.push(buffer.subarray(startIndex, index));
+      startIndex = index + 1;
+    }
+    if (index === buffer.length - 1) {
+      sequences.push(buffer.subarray(startIndex, index + 1));
+      break;
+    }
+  }
+
+  for (const bytes of sequences) {
+    if (!bytes.length) continue;
+
+    // Find 0x3D and replace 0x2B in one loop for better performance
+    let indexOf0x3D = -1;
+    for (let index = 0; index < bytes.length; index += 1) {
+      switch (bytes[index]) {
+        case 0x3D:
+          if (indexOf0x3D === -1) {
+            indexOf0x3D = index;
+          }
+          break;
+        case 0x2B:
+          // Replace bytes on original stream for memory conservation
+          bytes[index] = 0x20;
+          break;
+        default:
+      }
+    }
+    let name;
+    let value;
+    if (indexOf0x3D === -1) {
+      name = bytes;
+      value = bytes.subarray(bytes.length, 0);
+    } else {
+      name = bytes.subarray(0, indexOf0x3D);
+      value = bytes.subarray(indexOf0x3D + 1);
+    }
+    const nameString = decodeURIComponent(name.toString(bufferEncoding));
+    const valueString = decodeURIComponent(value.toString(bufferEncoding));
+    output.append(nameString, valueString);
+  }
+  return output;
+}
+
+const CONTENT_READER = {
+  type: 'application',
+  subtype: 'x-www-form-urlencoded',
+  parse: async (/** @type {HttpRequest} */ request) => Object.fromEntries(
+    await parseFormUrlEncoded(request),
+  ),
+};
+
+/**
+ * @this {HttpRequest}
+ * @return {Promise<FormData>}
+ */
+async function formData() {
+  if (this.mediaType.type === 'application' && this.mediaType.subtype === 'x-www-form-urlencoded') {
+    return await parseFormUrlEncoded(this);
+  }
+  throw new Error('UNSUPPORTED');
+}
+
+export default class ReadFormData {
+  constructor() {
+    this.execute = ReadFormData.Execute.bind(this);
+  }
+
+  /** @type {MiddlewareFunction} */
+  static Execute({ request }) {
+    request.formData = formData.bind(request);
+    request.contentReaders.push(CONTENT_READER);
+  }
+}