@boo-labs/server 0.0.0-stage → 1.0.1

package/source/application/resolvers/TransportResolver/index.mjs

@@ -0,0 +1,119 @@
+// @ts-check
+/**
+ * @file Defines the transport resolver.
+ *
+ * @description Resolves the transport adapter constructor associated with a
+ * supported transport identifier.
+ *
+ * @module TransportResolver
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import HttpAdapter from '#adapters/HttpAdapter';
+import HttpsAdapter from '#adapters/HttpsAdapter';
+import Http2Adapter from '#adapters/Http2Adapter';
+import Http2CleartextAdapter from '#adapters/Http2CleartextAdapter';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Maps each transport identifier to its concrete adapter type.
+ *
+ * @typedef  {object}                TransportRegistry
+ * @property {HttpAdapter}           h1                - HTTP/1.1 over cleartext TCP.
+ * @property {HttpsAdapter}          h1s               - HTTP/1.1 over TLS.
+ * @property {Http2Adapter}          h2                - HTTP/2 over TLS.
+ * @property {Http2CleartextAdapter} h2c               - HTTP/2 over cleartext TCP.
+ */
+
+/**
+ * Identifies the transport implementation handled by an adapter.
+ *
+ * @typedef {keyof TransportRegistry} Transport
+ */
+
+/**
+ * Generic contract satisfied by every concrete adapter in the registry.
+ *
+ * @typedef {TransportRegistry[Transport]} TransportAdapterContract
+ */
+
+/**
+ * Represents a transport adapter capable of managing a permitted transport.
+ *
+ * @typedef {import('#configurations/ServerConfiguration').ServerConfigurationIdentity} ServerConfigurationIdentity
+ */
+
+/**
+ * Represents a transport adapter capable of managing a permitted transport.
+ *
+ * @typedef {import('#configurations/ServerConfiguration').default<ServerConfigurationIdentity>} ServerConfiguration
+ */
+
+/**
+ * Constructor for a transport adapter that accepts optional transport
+ * configuration.
+ *
+ * @template {Transport} T
+ * @typedef {new (options: object|undefined) => TransportRegistry[T]} TransportAdapterConstructor
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Resolves transport adapter constructors from transport identifiers.
+ *
+ * @class
+ */
+class TransportResolver {
+  /**
+   * Prevents direct instantiation of the resolver.
+   *
+   * @abstract
+   * @throws {Error} Always thrown because `TransportResolver` exposes only static behavior.
+   */
+  constructor() {
+    throw new Error('TransportResolver is a static class and cannot be instantiated');
+  }
+
+  /**
+   * Resolves the adapter constructor associated with a transport.
+   *
+   * @param {Transport} transport - Identifier of the transport to resolve.
+   * @returns {TransportAdapterConstructor<Transport>} The transport adapter constructor.
+   * @throws {Error} When the transport is not supported by this implementation.
+   * @example
+   * ```js
+   * const Adapter = TransportResolver.resolve('h1');
+   * const adapter = new Adapter(configuration);
+   * ```
+   */
+  static resolve(transport) {
+    const Adapter = TransportResolver.#adapters.get(transport);
+
+    if (!Adapter) {
+      throw new Error(`Unsupported transport: ${transport}`);
+    }
+
+    return Adapter;
+  }
+
+  /**
+   * @type {Array<[Transport, TransportAdapterConstructor<Transport>]>}
+   */
+  static #ADAPTERS = [
+    ['h1', HttpAdapter],
+    ['h1s', HttpsAdapter],
+    ['h2', Http2Adapter],
+    ['h2c', Http2CleartextAdapter],
+  ];
+
+  /**
+   * Transport adapter constructors indexed by transport identifier.
+   *
+   * @type {Map<Transport, TransportAdapterConstructor<Transport>>}
+   */
+  static #adapters = new Map(TransportResolver.#ADAPTERS);
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default TransportResolver;

package/source/application/use-cases/CloseServer/index.mjs

@@ -0,0 +1,85 @@
+// @ts-check
+/**
+ * @file Defines the CloseServer application use case.
+ *
+ * @description CloseServer is responsible for executing the server shutdown
+ * operation through an injected server.
+ *
+ * It delegates the underlying shutdown process to the server and remains
+ * independent from any concrete transport implementation.
+ *
+ * @module CloseServer
+ */
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a permitted transport identity.
+ *
+ * @typedef {import('#adapters/TransportAdapter').TransportIdentity} TransportIdentity
+ */
+
+/**
+ * Represents a transport adapter capable of managing a permitted transport.
+ *
+ * @typedef {import('#adapters/TransportAdapter').default<TransportIdentity>} TransportAdapter
+ */
+
+/**
+ * Callback invoked after the server has closed.
+ *
+ * @callback OnCloseHandler
+ * @param {Error} [error] - Error reported if the server could not be closed.
+ * @returns {void}
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Application use case for stopping the server.
+ *
+ * @classdesc Executes the server shutdown operation through an injected server.
+ *
+ * This class does not manage server state transitions or depend on any
+ * concrete transport implementation.
+ */
+class CloseServer {
+  /**
+   * The server instance whose shutdown operation this use case executes.
+   *
+   * @type {TransportAdapter}
+   */
+  #server;
+
+  /**
+   * Creates a new CloseServer use case.
+   *
+   * @param {TransportAdapter} server - The server used to execute the shutdown operation.
+   * @example
+   * ```js
+   * const closeServer = new CloseServer(new HttpAdapter({
+   *   keepAliveTimeout: 65000
+   * }));
+   * ```
+   */
+  constructor(server) {
+    this.#server = server;
+  }
+
+  /**
+   * Executes the server shutdown operation.
+   *
+   * Delegates the shutdown operation to the configured server.
+   *
+   * @param {OnCloseHandler} [onCloseHandler] - Callback invoked by Node.js once the server has been successfully closed.
+   * @returns {Promise<void>} Resolves once the shutdown operation has completed.
+   * @example
+   * ```js
+   * await closeServer.execute(onCloseHandler);
+   * ```
+   */
+  async execute(onCloseHandler) {
+    await this.#server.close(onCloseHandler);
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default CloseServer;

package/source/application/use-cases/ListenServer/index.mjs

@@ -0,0 +1,98 @@
+// @ts-check
+/**
+ * @file Defines the ListenServer application use case.
+ *
+ * @description ListenServer is responsible for executing the server listening
+ * operation through an injected server.
+ *
+ * It delegates the underlying network binding process to the server and
+ * remains independent from any concrete transport implementation.
+ *
+ * @module ListenServer
+ */
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a permitted transport identity.
+ *
+ * @typedef {import('#adapters/TransportAdapter').TransportIdentity} TransportIdentity
+ */
+
+/**
+ * Represents a transport adapter capable of managing a permitted transport.
+ *
+ * @typedef {import('#adapters/TransportAdapter').default<TransportIdentity>} TransportAdapter
+ */
+
+/**
+ * Network configuration used to start the server.
+ *
+ * @typedef  {object} ListenOptions
+ * @property {number} [port]        - The TCP port on which the server listens.
+ * @property {string} [host]        - The hostname or IP address on which the server listens.
+ * @property {number} [backlog]     - The maximum number of pending connections that may be queued while the operating system is waiting to accept them.
+ */
+
+/**
+ * Callback invoked when the server has successfully started listening.
+ *
+ * @callback OnListenHandler
+ * @returns {void}
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Application use case for starting the server.
+ *
+ * @classdesc Executes the server listening operation through an injected server.
+ *
+ * This class does not manage server state transitions or depend on any
+ * concrete transport implementation.
+ */
+class ListenServer {
+  /**
+   * The server instance whose listening operation.
+   *
+   * @type {TransportAdapter}
+   */
+  #server;
+
+  /**
+   * Creates a new ListenServer use case.
+   *
+   * @param {TransportAdapter} server - The server responsible for executing the underlying listening operation.
+   * @example
+   * ```js
+   * const listenServer = new ListenServer(new HttpAdapter({
+   *   keepAliveTimeout: 65000
+   * }));
+   * ```
+   */
+  constructor(server) {
+    this.#server = server;
+  }
+
+  /**
+   * Executes the server listening operation.
+   *
+   * Delegates the listening operation to the configured server.
+   *
+   * @param {ListenOptions} [options] - Network configuration used to start the server.
+   * @param {OnListenHandler} [onListenHandler] - Callback invoked once the server has successfully started listening.
+   * @returns {Promise<void>} Resolves once the listening operation has been initiated.
+   * @example
+   * ```js
+   * await listenServer.execute({
+   *   port: process.env.PORT || 8080,
+   *   host: '0.0.0.0',
+   *   backlog: 511,
+   * }, onListenHandler);
+   * ```
+   */
+  async execute(options, onListenHandler) {
+    await this.#server.listen(options, onListenHandler);
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default ListenServer;

package/source/core/EventSystem/index.mjs

@@ -0,0 +1,110 @@
+// @ts-check
+/**
+ * @file Defines the server event system.
+ *
+ * @description Provides the event bus used by the application runtime to
+ * register listeners and emit server lifecycle and exchange events.
+ *
+ * @module EventSystem
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import EventEmitter from 'node:events';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Identifies an event by its string or symbol name.
+ *
+ * @typedef {string|symbol} EventName
+ */
+
+/**
+ * Represents a listener registered for a kernel event.
+ *
+ * @typedef {(data?: any) => void} EventListener
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Provides event management for the server runtime.
+ *
+ * @classdesc EventSystem encapsulates the underlying event emitter and exposes
+ * the event operations required by the application layer.
+ */
+class EventSystem {
+  #events = new EventEmitter();
+
+  /**
+   * Registers a listener for a server event.
+   *
+   * @param {EventName} event - Event name.
+   * @param {EventListener} listener - Function invoked when the event is emitted.
+   * @returns {EventSystem} The current event system instance.
+   * @example
+   * ```js
+   * eventSystem.on('listen', ({ endpoint }) => {
+   *   console.log(`Server listening at ${endpoint}`);
+   * });
+   * ```
+   */
+  on(event, listener) {
+    this.#events.on(event, listener);
+
+    return this;
+  }
+
+  /**
+   * Registers a listener that is invoked only once for a server event.
+   *
+   * @param {EventName} event - Event name.
+   * @param {EventListener} listener - Function invoked when the event is emitted.
+   * @returns {EventSystem} The current event system instance.
+   * @example
+   * ```js
+   * eventSystem.once('close', () => {
+   *   console.log('Server closed');
+   * });
+   * ```
+   */
+  once(event, listener) {
+    this.#events.once(event, listener);
+
+    return this;
+  }
+
+  /**
+   * Removes a listener from a server event.
+   *
+   * @param {EventName} event - Event name.
+   * @param {EventListener} listener - Listener to remove.
+   * @returns {EventSystem} The current event system instance.
+   * @example
+   * ```js
+   * eventSystem.off('error', handleError);
+   * ```
+   */
+  off(event, listener) {
+    this.#events.off(event, listener);
+
+    return this;
+  }
+
+  /**
+   * Emits a server event.
+   *
+   * @param {EventName} event - Event name.
+   * @param {unknown} [eventData] - Optional data associated with the event.
+   * @returns {boolean} True if the event had listeners, false otherwise.
+   * @example
+   * ```js
+   * eventSystem.emit('exchange', exchange);
+   * ```
+   */
+  emit(event, eventData) {
+    return this.#events.emit(event, eventData);
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default EventSystem;

package/source/core/Exchange/ExchangeContext.mjs

@@ -0,0 +1,291 @@
+// @ts-check
+/**
+ * @file Defines the internal execution context of an HTTP exchange.
+ *
+ * @description The context groups runtime-only data associated with a
+ * single transaction: telemetry, cancellation signal, and correlation
+ * identifiers. It is private to `Exchange` and is never exposed to the
+ * consumer.
+ *
+ * The context does not access the native HTTP message. Any HTTP-derived
+ * information it needs (currently only the W3C `traceparent` header) is
+ * extracted by `Exchange` and passed in at construction time.
+ *
+ * The outgoing `traceparent` represents the server's own span: the incoming
+ * `traceId` is preserved when present, a new `spanId` is generated, and the
+ * incoming `trace-flags` are preserved to avoid altering the sampling
+ * decision taken upstream.
+ *
+ * @module ExchangeContext
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import { randomBytes } from 'node:crypto';
+
+// » IMPORT LOCAL MODULES
+import Telemetry from './Telemetry.mjs';
+import UUIDV7 from '#shared/domain/UUIDV7';
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * W3C Trace Context version supported by this implementation.
+ *
+ * @type {string}
+ */
+const TRACEPARENT_VERSION = '00';
+
+/**
+ * Default trace flags used when no incoming `traceparent` is available.
+ *
+ * @type {string}
+ */
+const DEFAULT_TRACE_FLAGS = '01';
+
+/**
+ * Pattern matching a W3C `traceparent` header value.
+ *
+ * @type {RegExp}
+ */
+const TRACEPARENT_PATTERN = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
+
+/**
+ * Represents an all-zero trace identifier, which is invalid per W3C.
+ *
+ * @type {string}
+ */
+const INVALID_TRACE_ID = '0'.repeat(32);
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Options used to construct an exchange context.
+ *
+ * @typedef  {object} ExchangeContextOptions
+ * @property {string} [traceparent]          - W3C `traceparent` header value received with the request.
+ */
+
+/**
+ * Represents the trace information extracted from a W3C `traceparent`.
+ *
+ * @typedef  {object} TraceContext
+ * @property {string} traceId      - The 32-character hexadecimal trace identifier.
+ * @property {string} traceFlags   - The 2-character hexadecimal trace flags.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Groups runtime-only data associated with a single HTTP exchange.
+ *
+ * @classdesc The context holds telemetry, cancellation signal, and
+ * correlation identifiers. It is created by `Exchange` and never exposed
+ * to the consumer.
+ */
+class ExchangeContext {
+  /**
+   * Cancellation controller for the transaction.
+   *
+   * @type {AbortController}
+   */
+  #controller;
+
+  /**
+   * Telemetry tracker for the transaction.
+   *
+   * @type {Telemetry}
+   */
+  #telemetry;
+
+  /**
+   * Unique identifier for the transaction.
+   *
+   * @type {string}
+   */
+  #id;
+
+  /**
+   * W3C trace identifier.
+   *
+   * @type {string}
+   */
+  #traceId;
+
+  /**
+   * W3C span identifier.
+   *
+   * @type {string}
+   */
+  #spanId;
+
+  /**
+   * W3C trace flags.
+   *
+   * @type {string}
+   */
+  #traceFlags;
+
+  /**
+   * Creates an exchange context.
+   *
+   * @param {ExchangeContextOptions} [options] - The context options.
+   * @example
+   * ```js
+   * const context = new ExchangeContext({ traceparent: '00-...-...-01' });
+   * ```
+   */
+  constructor(options = {}) {
+    this.#controller = new AbortController();
+    this.#telemetry = new Telemetry();
+    this.#id = UUIDV7.create();
+
+    const trace = ExchangeContext.#extractTrace(options.traceparent);
+
+    this.#traceId = trace?.traceId ?? ExchangeContext.#generateTraceId();
+    this.#traceFlags = trace?.traceFlags ?? DEFAULT_TRACE_FLAGS;
+    this.#spanId = ExchangeContext.#generateSpanId();
+  }
+
+  /**
+   * The cancellation signal for the transaction.
+   *
+   * @type {AbortSignal}
+   */
+  get signal() {
+    return this.#controller.signal;
+  }
+
+  /**
+   * The telemetry tracker for the transaction.
+   *
+   * @type {Telemetry}
+   */
+  get telemetry() {
+    return this.#telemetry;
+  }
+
+  /**
+   * The unique identifier for the transaction.
+   *
+   * @type {string}
+   */
+  get id() {
+    return this.#id;
+  }
+
+  /**
+   * The W3C trace identifier for the transaction.
+   *
+   * @type {string}
+   */
+  get traceId() {
+    return this.#traceId;
+  }
+
+  /**
+   * The W3C span identifier for the transaction.
+   *
+   * @type {string}
+   */
+  get spanId() {
+    return this.#spanId;
+  }
+
+  /**
+   * Monotonic timestamp captured when the exchange processing context was created.
+   *
+   * @type {number}
+   */
+  get startedAt() {
+    return this.#telemetry.startedAt;
+  }
+
+  /**
+   * Aborts the transaction.
+   *
+   * Signals the associated cancellation signal. Callers of `signal` will
+   * receive the `abort` event. Subsequent calls have no effect.
+   *
+   * @returns {void}
+   * @example
+   * ```js
+   * context.abort();
+   * ```
+   */
+  abort() {
+    this.#controller.abort();
+  }
+
+  /**
+   * Returns the W3C `traceparent` header value for this transaction.
+   *
+   * The value represents the server's own span: it preserves the incoming
+   * `traceId` and `trace-flags` when present, and always carries a new
+   * `spanId`.
+   *
+   * @returns {string} The formatted `traceparent` header value.
+   * @example
+   * ```js
+   * response.setHeader('traceparent', context.traceparent());
+   * ```
+   */
+  traceparent() {
+    return `${TRACEPARENT_VERSION}-${this.#traceId}-${this.#spanId}-${this.#traceFlags}`;
+  }
+
+  /**
+   * Extracts the trace information from a W3C `traceparent` header value.
+   *
+   * Returns `null` when the value is missing, malformed, uses a version
+   * not supported by this implementation, or carries an all-zero trace
+   * identifier.
+   *
+   * @param {string|undefined} value - The `traceparent` header value.
+   * @returns {TraceContext|null} The extracted trace information, or `null`.
+   */
+  static #extractTrace(value) {
+    if (typeof value !== 'string') {
+      return null;
+    }
+
+    const match = value.match(TRACEPARENT_PATTERN);
+
+    if (!match) {
+      return null;
+    }
+
+    if (match[1].toLowerCase() !== TRACEPARENT_VERSION) {
+      return null;
+    }
+
+    const traceId = match[2].toLowerCase();
+
+    if (traceId === INVALID_TRACE_ID) {
+      return null;
+    }
+
+    return {
+      traceId,
+      traceFlags: match[4].toLowerCase(),
+    };
+  }
+
+  /**
+   * Generates a 32-character lowercase hexadecimal trace identifier.
+   *
+   * @returns {string} The generated trace identifier.
+   */
+  static #generateTraceId() {
+    return randomBytes(16).toString('hex');
+  }
+
+  /**
+   * Generates a 16-character lowercase hexadecimal span identifier.
+   *
+   * @returns {string} The generated span identifier.
+   */
+  static #generateSpanId() {
+    return randomBytes(8).toString('hex');
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default ExchangeContext;