webhoster 0.1.0 → 0.3.0

package/test/templates/starter.js

@@ -0,0 +1,93 @@
+import test from 'ava';
+import http from 'node:http';
+import HttpListener from '../../helpers/HttpListener.js';
+import HttpHandler from '../../lib/HttpHandler.js';
+import * as starter from '../../templates/starter.js';
+
+test.serial('examples/starter starts singleton listener and responds', async (t) => {
+  // Import the example. It applies middleware and starts the singleton listener.
+  await import('../../examples/starter.js');
+
+  const listener = HttpListener.defaultInstance;
+  const server = listener.httpServer;
+  t.truthy(server, 'singleton server started');
+
+  const addr = server.address();
+  t.truthy(addr && addr.port, 'server bound to a port');
+
+  const result = await new Promise((resolve, reject) => {
+    const request = http.get({ port: addr.port, path: '/' }, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+    });
+    request.on('error', reject);
+  });
+
+  t.is(result.status, 200);
+  t.true(typeof result.body === 'string');
+  t.true(result.body.length > 0, 'response body present');
+
+  await listener.stopHttpServer();
+});
+
+test.serial('starter.start applies default error handler and middleware when none provided', async (t) => {
+  const handler = HttpHandler.defaultInstance;
+  const listener = HttpListener.defaultInstance;
+
+  const mwLength = handler.middleware.length;
+  const ehLength = handler.errorHandlers.length;
+
+  // Start with empty options to exercise the default-error-handler branch
+  // Use port 0 and loopback host to avoid port collisions in CI.
+  await starter.start({ host: '127.0.0.1', port: 0 });
+
+  t.truthy(listener.httpServer, 'httpServer started');
+
+  t.true(handler.middleware.length >= mwLength + 8, 'starter middleware applied');
+  t.true(handler.errorHandlers.length > ehLength, 'default error handler added');
+
+  const lastError = handler.errorHandlers.at(-1);
+  t.is(typeof lastError.onError, 'function');
+
+  // Invoke the default onError to exercise its code path (logging + 500).
+  const result = lastError.onError({ request: { url: '/x' }, error: new Error('boom') });
+  t.is(result, 500);
+
+  await listener.stopHttpServer();
+
+  // restore handler arrays to previous lengths
+  handler.middleware.splice(mwLength);
+  handler.errorHandlers.splice(ehLength);
+});
+
+test.serial('starter.start respects provided errorHandlers and pushes middleware by reference', async (t) => {
+  const handler = HttpHandler.defaultInstance;
+  const listener = HttpListener.defaultInstance;
+
+  const mwLength = handler.middleware.length;
+  const ehLength = handler.errorHandlers.length;
+
+  const customHandlers = [{ onError: () => 418 }];
+  const customMiddleware = [() => 'custom'];
+
+  await starter.start({
+    middleware: customMiddleware, errorHandlers: customHandlers, host: '127.0.0.1', port: 0,
+  });
+
+  t.truthy(listener.httpServer, 'httpServer started');
+
+  // The supplied middleware array should be pushed as a single entry (by reference)
+  const lastMw = handler.middleware.at(-1);
+  t.is(lastMw, customMiddleware);
+
+  // The implementation does not automatically append provided `errorHandlers`;
+  // it only avoids adding the default when `options.errorHandlers` is supplied.
+  t.is(handler.errorHandlers.length, ehLength);
+
+  await listener.stopHttpServer();
+
+  handler.middleware.splice(mwLength);
+  handler.errorHandlers.splice(ehLength);
+});

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "checkJs": true,
+    "noImplicitAny": true,
+    "target": "es2022",
+    "module": "esnext",
+    "moduleResolution": "node"
+  },
+  "exclude": [
+    "**/node_modules/*"
+  ]
+}

package/types/index.js

@@ -1,55 +1,82 @@
-/** @typedef {import('../lib/HttpRequest').default} HttpRequest */
-/** @typedef {import('../lib/HttpResponse').default} HttpResponse */
+/**
+ * @template {any} [T=any]
+ * @typedef {import('../lib/HttpTransaction.js').default<T>} HttpTransaction<T>
+ */
+/** @typedef {import('../lib/HttpRequest.js').default} HttpRequest */
+/** @typedef {import('../lib/HttpResponse.js').default} HttpResponse */
+
+/**
+ * @typedef {Object} MediaType
+ * @prop {string} type
+ * @prop {string} tree
+ * @prop {string} subtype
+ * @prop {string} suffix
+ * @prop {Record<string, string>} parameters
+ */
+
+/** @typedef {import('node:stream').Duplex} Duplex */
 
 /** @typedef {import('./typings').Middleware} Middleware */
 
+/** @typedef {true|false|0} MiddlewareFlowInstruction */
+
 /** @typedef {'GET'|'HEAD'|'POST'|'PUT'|'DELETE'|'CONNECT'|'OPTIONS'|'TRACE'|'PATCH'} RequestMethod */
 
-/** @typedef {'end'|'break'|'continue'|boolean|null|undefined|void} MiddlewareFunctionResultType */
+/** @typedef {0|true|false|null|undefined|void} MiddlewareFunctionResultType */
+
 /** @typedef {Promise<Middleware>|Middleware} MiddlewareFunctionResult */
-/** @typedef {true|false} MiddlewareContinueBoolean */
+
+/** @typedef {Record<string,any>|number|import('stream').Readable|Buffer|string} MiddlewareContent */
 
 /**
- * @typedef {Object} IMiddleware
- * @prop {MiddlewareFunction} execute
- * @prop {MiddlewareErrorHandlerFunction} [onError]
+ * @template {any} [T=any]
+ * @callback MiddlewareFunction
+ * @param {!HttpTransaction<T>} transaction
+ * @return {MiddlewareFunctionResult}
  */
 
 /**
- * @typedef {Object} HandlerState
- * @prop {number[]} treeIndex Middleware level
+ * @template {any} [T=any]
+ * @callback MiddlewareResponseFunction
+ * @param {{ response: HttpTransaction<T>['response'] }} transaction
+ * @return {MiddlewareFunctionResult}
  */
 
 /**
- * @typedef {Object} MiddlewareFunctionParams
- * @prop {HttpRequest} req
- * @prop {HttpResponse} res
- * @prop {HandlerState} state
+ * @this {undefined}
+ * @callback StaticMiddlewareFunction
+ * @param {!HttpTransaction} transaction
+ * @return {MiddlewareFunctionResult}
  */
 
 /**
- * @typedef {Object} MiddlewareErrorHandlerParams
- * @prop {HttpRequest} req
- * @prop {HttpResponse} res
- * @prop {HandlerState} state
- * @prop {any} [err]
+ * @callback ResponseFinalizer
+ * @param {!HttpResponse} response
+ * @return {void|null|boolean|Promise<void|null|boolean>}
  */
 
 /**
- * @callback MiddlewareFunction
- * @param {!MiddlewareFunctionParams} params
- * @return {MiddlewareFunctionResult}
+ * @typedef MiddlewareExecutor
+ * @prop {MiddlewareFunction} execute
  */
 
 /**
- * @callback MiddlewareErrorHandlerFunction
- * @param {MiddlewareErrorHandlerParams} params
- * @return {MiddlewareFunctionResult}
+ * @typedef {Object} MiddlewareStaticExecutor
+ * @prop {StaticMiddlewareFunction} Execute
+ */
+
+/**
+ * @typedef {Object} MiddlewareStaticErrorHandler
+ * @prop {StaticMiddlewareFunction} OnError
+ */
+
+/**
+ * @typedef MiddlewareErrorHandler
+ * @prop {MiddlewareFunction} onError
  */
 
 /**
- * @typedef {Object} MiddlewareErrorHandler
- * @prop {MiddlewareErrorHandlerFunction} onError
+ * @typedef {MiddlewareExecutor|MiddlewareStaticExecutor|MiddlewareErrorHandler|MiddlewareStaticErrorHandler|MiddlewareStaticExecutor} IMiddleware
  */
 
 /**
@@ -57,8 +84,8 @@
  * @prop {string} [name='']
  * A cookie name can be any US-ASCII characters, except control characters, spaces, or tabs.
  * It also must not contain a separator character like the following:( ) < > &#64; , ; : \ " / [ ] ? = { }.
- *   * __Secure- prefix: Cookies names starting with __Secure- (dash is part of the prefix) must be set with the secure flag from a secure page (HTTPS).
- *   * __Host- prefix: Cookies with names starting with __Host- must be set with the secure flag, must be from a secure page (HTTPS), must not have a domain specified (and therefore aren't sent to subdomains) and the path must be /.
+ *   - __Secure- prefix: Cookies names starting with __Secure- (dash is part of the prefix) must be set with the secure flag from a secure page (HTTPS).
+ *   - __Host- prefix: Cookies with names starting with __Host- must be set with the secure flag, must be from a secure page (HTTPS), must not have a domain specified (and therefore aren't sent to subdomains) and the path must be /.
  * @prop {string} [value='']
  * A cookie value can optionally be wrapped in double quotes and include any US-ASCII characters excluding
  * control characters, Whitespace, double quotes, comma, semicolon, and backslash.
@@ -76,9 +103,9 @@
  * If both Expires and Max-Age are set, Max-Age has precedence.
  * @prop {string} [domain]
  * Host to which the cookie will be sent.
- *   * If omitted, defaults to the host of the current document URL, not including subdomains.
- *   * Contrary to earlier specifications, leading dots in domain names (.example.com) are ignored.
- *   * Multiple host/domain values are not allowed, but if a domain is specified, then subdomains are always included.
+ *   - If omitted, defaults to the host of the current document URL, not including subdomains.
+ *   - Contrary to earlier specifications, leading dots in domain names (.example.com) are ignored.
+ *   - Multiple host/domain values are not allowed, but if a domain is specified, then subdomains are always included.
  * @prop {string} [path]
  * A path that must exist in the requested URL, or the browser won't send the Cookie header.
  *
@@ -96,13 +123,13 @@
  * @prop {'Strict'|'Lax'|'None'} [sameSite]
  * Asserts that a cookie must not be sent with cross-origin requests,
  * providing some protection against cross-site request forgery attacks (CSRF).
- *   * Strict: The browser sends the cookie only for same-site requests
+ *   - Strict: The browser sends the cookie only for same-site requests
  *     (that is, requests originating from the same site that set the cookie).
  *     If the request originated from a different URL than the current one,
  *     no cookies with the SameSite=Strict attribute are sent.
- *   * Lax: The cookie is withheld on cross-site subrequests, such as calls to load images or frames,
+ *   - Lax: The cookie is withheld on cross-site subrequests, such as calls to load images or frames,
  *     but is sent when a user navigates to the URL from an external site, such as by following a link.
- *   * None: The browser sends the cookie with both cross-site and same-site requests.
+ *   - None: The browser sends the cookie with both cross-site and same-site requests.
  */
 
 export default {};

package/types/typings.d.ts

@@ -1,15 +1,14 @@
 import {
   IMiddleware,
+  MiddlewareContent,
   MiddlewareFunction,
-  MiddlewareErrorHandler,
-  MiddlewareContinueBoolean,
+  MiddlewareFunctionResultType,
 } from './index.js';
 
-export type Middleware = MiddlewareFunction
+export type Middleware =
   | IMiddleware
-  | MiddlewareErrorHandler
-  | Iterable<Middleware>
-  | Map<any, Middleware>
-  | {[key:string]: Middleware, onError?: undefined}
-  | MiddlewareContinueBoolean
-  | 'end'|'break'|'continue'|null|undefined|void;
+  | MiddlewareFunction
+  | Middleware[]
+  | MiddlewareContent
+  | Set<Middleware>
+  | MiddlewareFunctionResultType

package/utils/AsyncObject.js

@@ -32,7 +32,7 @@ export default class AsyncObject {
 
   /**
    * @param {T} [value]
-   * @return {Promise<T>}
+   * @return {T}
    */
   set(value) {
     this.value = value;
@@ -41,7 +41,7 @@ export default class AsyncObject {
     while (this.pendingPromises.length) {
       this.pendingPromises.shift().resolve(value);
     }
-    return Promise.resolve(value);
+    return value;
   }
 
   /**
@@ -57,7 +57,10 @@ export default class AsyncObject {
     }
   }
 
-  /** @return {void} */
+  /**
+   * Clear value and mark busy
+   * @return {void}
+   */
   prepare() {
     this.value = undefined;
     this.busy = true;

package/utils/CaseInsensitiveObject.js

@@ -7,10 +7,10 @@ export default class CaseInsensitiveObject {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const instance = this;
     const proxy = new Proxy(instance, CaseInsensitiveObject.defaultProxyHandler);
-    Object.entries(object).forEach(([key, value]) => {
+    for (const [key, value] of Object.entries(object)) {
       // @ts-ignore Coerce
       this[key] = value;
-    });
+    }
     return proxy;
   }
 }
@@ -30,4 +30,3 @@ CaseInsensitiveObject.defaultProxyHandler = {
     return Reflect.deleteProperty(target, typeof p === 'string' ? p.toLowerCase() : p);
   },
 };
-

package/utils/function.js

@@ -1,7 +1 @@
-// eslint-disable-next-line jsdoc/require-returns-check
-/**
- * @param {any} [args]
- * @return {any}
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-function, @typescript-eslint/no-unused-vars
-export function noop(...args) {}
+export const noop = () => {};

package/utils/headers.js

@@ -0,0 +1,42 @@
+/**
+ *
+ * @param {?string} contentType
+ * @return {import('../types/index.js').MediaType}
+ */
+export function parseContentType(contentType) {
+  let type;
+  let tree;
+  let subtype;
+  let suffix;
+  /** @type {Record<string,string>} */
+  const parameters = {};
+  if (contentType) {
+    for (const directive of contentType.split(';')) {
+      let [key, value] = directive.split('=');
+      key = key.trim().toLowerCase();
+      if (value === undefined) {
+        let rest;
+        [type, rest] = key.split('/');
+        const treeEntries = rest.split('.');
+        const subtypeSuffix = treeEntries.pop();
+        tree = treeEntries.join('.');
+        [subtype, suffix] = subtypeSuffix.split('+');
+        continue;
+      }
+
+      value = value.trim();
+      const firstQuote = value.indexOf('"');
+      const lastQuote = value.lastIndexOf('"');
+      if (firstQuote !== -1 && lastQuote !== -1) {
+        if (firstQuote === lastQuote) {
+          throw new Error('ERR_CONTENT_TYPE');
+        }
+        value = value.slice(firstQuote + 1, lastQuote);
+      }
+      parameters[key] = value;
+    }
+  }
+  return {
+    type, subtype, suffix, tree, parameters,
+  };
+}

package/utils/qualityValues.js

@@ -20,7 +20,7 @@ export function parseQualityValues(input) {
             const trimmedSpec = specifier?.trim();
             const trimmedSValue = sValue?.trim();
             if (trimmedSpec === 'q') {
-              const parsedQ = parseFloat(trimmedSValue);
+              const parsedQ = Number.parseFloat(trimmedSValue);
               return { q: Number.isNaN(parsedQ) ? 1 : parsedQ };
             }
             return { [trimmedSpec]: trimmedSValue };

package/utils/stream.js

@@ -1,23 +1,7 @@
-/** @typedef {import('stream').Readable} Readable */
-
 /**
- * @param {Readable} readable
- * @return {Promise<any>}
+ * @param {import('node:stream').Writable|import('node:http').ServerResponse} writableLike
+ * @return {boolean}
  */
-export async function readStreamChunk(readable) {
-  return new Promise((resolve, reject) => readable.once('data', resolve).once('error', reject));
-}
-
-/**
- * @param {Readable} readable
- * @return {Promise<any[]>}
- */
-export async function readAllChunks(readable) {
-  return new Promise((resolve, reject) => {
-    /** @type {any[]} */
-    const chunks = [];
-    readable.on('data', chunks.push);
-    readable.on('end', () => resolve(chunks));
-    readable.on('error', reject);
-  });
+export function isWritable(writableLike) {
+  return (!writableLike.destroyed && !writableLike.writableEnded);
 }