@boo-labs/server 0.0.0-stage → 1.0.0

package/source/application/configurations/ServerConfiguration/Options/MiddlewareOption.mjs

@@ -0,0 +1,102 @@
+// @ts-check
+/**
+ * @file Defines the abstract base for middleware configuration options.
+ *
+ * @description MiddlewareOption identifies configuration options that
+ * represent middlewares (cors, static, securityHeaders, rateLimit).
+ *
+ * @module MiddlewareOption
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Options from './Options.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a router HTTP method supported by the routing layer.
+ *
+ * @typedef {'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'DELETE'|'OPTIONS'|'QUERY'|'TRACE'} HTTPMethod
+ */
+/**
+ * Represents one middleware configuration consumed by the exchange layer builder.
+ *
+ * @typedef  {object}                            MiddlewareConfiguration
+ * @property {string}                            name                    - Middleware name.
+ * @property {Record<string, unknown>|undefined} options                 - Middleware configuration options.
+ * @property {string|undefined}                  pathnamePattern         - URL pathname pattern to match.
+ * @property {HTTPMethod|undefined}              method                  - HTTP method to match.
+ */
+
+/**
+ * Represents a value object wrapping a normalized configuration value.
+ *
+ * @template {Record<string, unknown>|undefined} TValue
+ * @typedef {import('./Options.mjs').ValueObject<TValue>} ValueObject
+ */
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Abstract base class for middleware configuration options.
+ *
+ * @abstract
+ * @template {Record<string, unknown>|undefined} TValue
+ * @augments Options<TValue>
+ */
+class MiddlewareOption extends Options {
+  /**
+   * Creates a server middleware configuration option instance.
+   *
+   * @abstract
+   * @param {string} name - Option name.
+   * @param {ValueObject<TValue>} value - Normalized option value.
+   * @throws {TypeError} If MiddlewareOption is instantiated directly.
+   */
+  constructor(name, value) {
+    if (new.target === MiddlewareOption) {
+      throw new TypeError('MiddlewareOption is an abstract class and cannot be instantiated');
+    }
+
+    super('middleware', name, value.value);
+  }
+
+  /**
+   * The URL pathname pattern the middleware is scoped to.
+   *
+   * Defaults to `undefined`, meaning the middleware applies to all paths.
+   *
+   * @readonly
+   * @type {string|undefined}
+   */
+  get pathnamePattern() {
+    return undefined;
+  }
+
+  /**
+   * The HTTP method the middleware is scoped to.
+   *
+   * Defaults to `undefined`, meaning the middleware applies to all methods.
+   *
+   * @readonly
+   * @type {HTTPMethod|undefined}
+   */
+  get method() {
+    return undefined;
+  }
+
+  /**
+   * Composes the middleware configuration consumed by the exchange layer
+   * builder.
+   *
+   * Subclasses must implement this method.
+   *
+   * @abstract
+   * @returns {MiddlewareConfiguration} The composed middleware configuration.
+   * @throws {TypeError} If the subclass does not implement `compose`.
+   */
+  compose() {
+    throw new TypeError('MiddlewareOption.compose must be implemented by subclasses');
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default MiddlewareOption;

package/source/application/configurations/ServerConfiguration/Options/Options.mjs

@@ -0,0 +1,105 @@
+// @ts-check
+/**
+ * @file Defines the abstract base for configuration options.
+ *
+ * @description Options provides the common contract shared by configuration
+ * option value objects. It cannot be instantiated directly.
+ *
+ * @module Options
+ */
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the kind of configuration option.
+ *
+ * @typedef {'server'|'middleware'} OptionType
+ */
+
+/**
+ * Represents a value object wrapping a normalized configuration value.
+ *
+ * @template {Record<string, unknown>|undefined} TValue
+ * @typedef {{ value: TValue }} ValueObject
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Abstract base class for configuration options.
+ *
+ * @template {Record<string, unknown>|undefined} TValue
+ * @abstract
+ */
+class Options {
+  /**
+   * The option kind.
+   *
+   * @type {OptionType}
+   */
+  #type;
+
+  /**
+   * The option name.
+   *
+   * @type {string}
+   */
+  #name;
+
+  /**
+   * The option value.
+   *
+   * @type {TValue}
+   */
+  #value;
+
+  /**
+   * Creates a configuration option instance.
+   *
+   * @abstract
+   * @param {OptionType} type - Option kind.
+   * @param {string} name - Option name.
+   * @param {TValue} value - Normalized option value.
+   * @throws {TypeError} If Options is instantiated directly.
+   */
+  constructor(type, name, value) {
+    if (new.target === Options) {
+      throw new TypeError('Options is an abstract class and cannot be instantiated');
+    }
+
+    this.#type = type;
+    this.#name = name;
+    this.#value = value;
+  }
+
+  /**
+   * The option kind.
+   *
+   * @readonly
+   * @type {OptionType}
+   */
+  get type() {
+    return this.#type;
+  }
+
+  /**
+   * The option name.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get name() {
+    return this.#name;
+  }
+
+  /**
+   * The option value.
+   *
+   * @readonly
+   * @type {TValue}
+   */
+  get value() {
+    return this.#value;
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default Options;

package/source/application/configurations/ServerConfiguration/Options/RateLimitOptions/RateLimitOptionsValue.mjs

@@ -0,0 +1,164 @@
+// @ts-check
+/**
+ * @file Defines the RateLimitOptionsValue value object.
+ *
+ * @description Normalizes and validates rate limit middleware configuration
+ * used by RateLimitMiddleware. When options are omitted, the value is
+ * undefined and the middleware is not registered.
+ *
+ * @module RateLimitOptionsValue
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import { assertRateLimitOptions } from '#shared/validations/ServerConfiguration/RateLimitOptions';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Domain error thrown by server configuration validation.
+ *
+ * @typedef {import('#shared/errors/ServerConfigurationError').default} ServerConfigurationError
+ */
+
+/**
+ * Represents the rate limit options accepted by the server configuration.
+ *
+ * @typedef  {object}                  RateLimitOptionsInput
+ * @property {number}                  [windowMs]            - Duration of the rate-limit window in milliseconds.
+ * @property {number}                  [max]                 - Maximum number of requests allowed per window per client.
+ * @property {number}                  [statusCode]          - HTTP status code returned when the limit is exceeded.
+ * @property {Record<string, unknown>} [message]             - JSON body sent when the limit is exceeded.
+ * @property {boolean}                 [standardHeaders]     - Whether to send the modern `RateLimit-*` headers.
+ * @property {boolean}                 [legacyHeaders]       - Whether to send the legacy `X-RateLimit-*` headers.
+ */
+
+/**
+ * Represents the normalized rate limit options.
+ *
+ * @typedef  {object}                            RateLimitOptionsData
+ * @property {number}                            windowMs             - Duration of the rate-limit window in milliseconds.
+ * @property {number}                            max                  - Maximum number of requests allowed per window per client.
+ * @property {number}                            statusCode           - HTTP status code returned when the limit is exceeded.
+ * @property {Readonly<Record<string, unknown>>} message              - JSON body sent when the limit is exceeded.
+ * @property {boolean}                           standardHeaders      - Whether to send the modern `RateLimit-*` headers.
+ * @property {boolean}                           legacyHeaders        - Whether to send the legacy `X-RateLimit-*` headers.
+ */
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Default duration of the rate-limit window in milliseconds.
+ *
+ * @type {number}
+ */
+const DEFAULT_WINDOW_MS = 60_000;
+
+/**
+ * Default maximum number of requests allowed per window per client.
+ *
+ * @type {number}
+ */
+const DEFAULT_MAX = 100;
+
+/**
+ * Default HTTP status code returned when the limit is exceeded.
+ *
+ * @type {number}
+ */
+const DEFAULT_STATUS_CODE = 429;
+
+/**
+ * Default JSON body sent when the limit is exceeded.
+ *
+ * @type {Readonly<Record<string, unknown>>}
+ */
+const DEFAULT_MESSAGE = Object.freeze({ error: 'Too Many Requests' });
+
+/**
+ * Default behavior for modern `RateLimit-*` headers.
+ *
+ * @type {boolean}
+ */
+const DEFAULT_STANDARD_HEADERS = true;
+
+/**
+ * Default behavior for legacy `X-RateLimit-*` headers.
+ *
+ * @type {boolean}
+ */
+const DEFAULT_LEGACY_HEADERS = false;
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Immutable value object representing normalized rate limit middleware
+ * options.
+ *
+ * @classdesc Validates and normalizes rate limit middleware options. When
+ * options are provided, defaults are applied for any omitted property. When
+ * options are omitted, the value is undefined.
+ *
+ * @example
+ * ```js
+ * const options = new RateLimitOptionsValue({ windowMs: 60_000, max: 100 });
+ *
+ * options.value;
+ * // => {
+ * //   windowMs: 60_000,
+ * //   max: 100,
+ * //   statusCode: 429,
+ * //   message: { error: 'Too Many Requests' },
+ * //   standardHeaders: true,
+ * //   legacyHeaders: false,
+ * // }
+ * ```
+ *
+ * @example
+ * ```js
+ * const options = new RateLimitOptionsValue();
+ *
+ * options.value;
+ * // => undefined
+ * ```
+ */
+class RateLimitOptionsValue {
+  /**
+   * The normalized rate limit options.
+   *
+   * @type {Readonly<RateLimitOptionsData>|undefined}
+   */
+  #value;
+
+  /**
+   * Creates a new {@link RateLimitOptionsValue}.
+   *
+   * @param {RateLimitOptionsInput} [options] - The rate limit middleware options.
+   * @throws {ServerConfigurationError} If `options` is invalid.
+   */
+  constructor(options) {
+    assertRateLimitOptions(options);
+
+    this.#value =
+      options === undefined
+        ? options
+        : Object.freeze({
+            windowMs: options.windowMs ?? DEFAULT_WINDOW_MS,
+            max: options.max ?? DEFAULT_MAX,
+            statusCode: options.statusCode ?? DEFAULT_STATUS_CODE,
+            message: Object.freeze({ ...(options.message ?? DEFAULT_MESSAGE) }),
+            standardHeaders: options.standardHeaders ?? DEFAULT_STANDARD_HEADERS,
+            legacyHeaders: options.legacyHeaders ?? DEFAULT_LEGACY_HEADERS,
+          });
+  }
+
+  /**
+   * The normalized rate limit options.
+   *
+   * @readonly
+   * @type {Readonly<RateLimitOptionsData>|undefined}
+   */
+  get value() {
+    return this.#value;
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default RateLimitOptionsValue;

package/source/application/configurations/ServerConfiguration/Options/RateLimitOptions/index.mjs

@@ -0,0 +1,84 @@
+// @ts-check
+/**
+ * @file Defines the RateLimitOptions middleware configuration option.
+ *
+ * @description RateLimitOptions wraps a normalized RateLimitOptionsValue into
+ * the middleware configuration option hierarchy.
+ *
+ * @module RateLimitOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import MiddlewareOption from '../MiddlewareOption.mjs';
+import RateLimitOptionsValue from './RateLimitOptionsValue.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the rate limit options accepted by the server configuration.
+ *
+ * @typedef {import('./RateLimitOptionsValue.mjs').RateLimitOptionsInput} RateLimitOptionsInput
+ */
+
+/**
+ * Represents the normalized rate limit options.
+ *
+ * @typedef {import('./RateLimitOptionsValue.mjs').RateLimitOptionsData} RateLimitOptionsData
+ */
+
+/**
+ * Represents one middleware configuration consumed by the exchange layer builder.
+ *
+ * @typedef {import('../MiddlewareOption.mjs').MiddlewareConfiguration} MiddlewareConfiguration
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Middleware configuration option wrapping a normalized rate limit
+ * configuration.
+ *
+ * @augments {MiddlewareOption<RateLimitOptionsData|undefined>}
+ */
+class RateLimitOptions extends MiddlewareOption {
+  /**
+   * Creates a new {@link RateLimitOptions}.
+   *
+   * @param {RateLimitOptionsInput} [options] - The rate limit middleware options.
+   * @example
+   * ```js
+   * const rateLimitOptions = new RateLimitOptions({
+   *   windowMs: 60_000,
+   *   max: 100,
+   * });
+   * ```
+   */
+  constructor(options) {
+    super('rateLimit', new RateLimitOptionsValue(options));
+  }
+
+  /**
+   * Composes the rate limit middleware configuration consumed by the
+   * exchange layer builder.
+   *
+   * Rate limiting is a cross-cutting concern applied to every request
+   * regardless of pathname or method, so both `pathnamePattern` and `method`
+   * are `undefined`.
+   *
+   * @returns {MiddlewareConfiguration} The composed middleware configuration.
+   * @example
+   * ```js
+   * const configuration = rateLimitOptions.compose();
+   * ```
+   */
+  compose() {
+    return {
+      name: this.name,
+      options: this.value,
+      pathnamePattern: undefined,
+      method: undefined,
+    };
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default RateLimitOptions;

package/source/application/configurations/ServerConfiguration/Options/RequestOptions/RequestOptionsValue.mjs

@@ -0,0 +1,108 @@
+// @ts-check
+/**
+ * @file Defines the RequestOptionsValue value object.
+ *
+ * @description Normalizes and validates request configuration used by
+ * ServerConfiguration. When options are omitted, the value is undefined.
+ *
+ * @module RequestOptionsValue
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import { assertRequestOptions } from '#shared/validations/ServerConfiguration/RequestOptions';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Domain error thrown by server configuration validation.
+ *
+ * @typedef {import('#shared/errors/ServerConfigurationError').default} ServerConfigurationError
+ */
+
+/**
+ * Whether (and how much) to trust proxy headers.
+ *
+ * @typedef {boolean|number} TrustProxyOption
+ */
+
+/**
+ * Represents the request options accepted by the server configuration.
+ *
+ * @typedef  {object}           RequestOptionsInput
+ * @property {number}           [bodyLimit]         - Maximum number of bytes allowed for the request body.
+ * @property {TrustProxyOption} [trustProxy]        - Whether (and how much) to trust proxy headers.
+ */
+
+/**
+ * Represents the normalized request options.
+ *
+ * @typedef  {object}           RequestOptionsData
+ * @property {number}           [bodyLimit]        - Maximum number of bytes allowed for the request body.
+ * @property {TrustProxyOption} [trustProxy]       - Whether (and how much) to trust proxy headers.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Immutable value object representing normalized request options.
+ *
+ * @classdesc Validates and normalizes request options for the server.
+ * When options are omitted, the value is undefined.
+ */
+class RequestOptionsValue {
+  /**
+   * Normalized request options.
+   *
+   * @type {Readonly<RequestOptionsData>|undefined}
+   */
+  #value;
+
+  /**
+   * Creates a new {@link RequestOptionsValue}.
+   *
+   * @param {RequestOptionsInput} [options] - The request options.
+   * @throws {ServerConfigurationError} If `options` is not a plain object.
+   * @throws {ServerConfigurationError} If `bodyLimit` is defined and is not a number.
+   * @throws {ServerConfigurationError} If `bodyLimit` is defined and is not a positive safe integer.
+   * @throws {ServerConfigurationError} If `trustProxy` is defined and is not a boolean or number.
+   * @throws {ServerConfigurationError} If numeric `trustProxy` is defined and is negative or not an integer.
+   * @example
+   * ```js
+   * const options = new RequestOptionsValue({ bodyLimit: 1_000_000, trustProxy: 1 });
+   *
+   * options.value;
+   * // => { bodyLimit: 1_000_000, trustProxy: 1 }
+   * ```
+   *
+   * @example
+   * ```js
+   * const options = new RequestOptionsValue();
+   *
+   * options.value;
+   * // => undefined
+   * ```
+   */
+  constructor(options) {
+    assertRequestOptions(options);
+
+    this.#value =
+      options === undefined
+        ? options
+        : Object.freeze({
+            bodyLimit: options.bodyLimit,
+            trustProxy: options.trustProxy,
+          });
+  }
+
+  /**
+   * The request options.
+   *
+   * @readonly
+   * @type {Readonly<RequestOptionsData>|undefined}
+   */
+  get value() {
+    return this.#value;
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default RequestOptionsValue;

package/source/application/configurations/ServerConfiguration/Options/RequestOptions/index.mjs

@@ -0,0 +1,47 @@
+// @ts-check
+/**
+ * @file Defines the RequestOptions server configuration option.
+ *
+ * @description RequestOptions wraps a normalized RequestOptionsValue into the
+ * server configuration option hierarchy.
+ *
+ * @module RequestOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import ServerOption from '../ServerOption.mjs';
+import RequestOptionsValue from './RequestOptionsValue.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the request options accepted by the server configuration.
+ *
+ * @typedef {import('./RequestOptionsValue.mjs').RequestOptionsInput} RequestOptionsInput
+ */
+
+/**
+ * Represents the normalized request options.
+ *
+ * @typedef {import('./RequestOptionsValue.mjs').RequestOptionsData} RequestOptionsData
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Server configuration option wrapping a normalized request configuration.
+ *
+ * @augments {ServerOption<RequestOptionsData|undefined>}
+ */
+class RequestOptions extends ServerOption {
+  /**
+   * Creates a new {@link RequestOptions}.
+   *
+   * @param {RequestOptionsInput} [options] - The request options.
+   */
+  constructor(options) {
+    super('request', new RequestOptionsValue(options));
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default RequestOptions;