@boo-labs/server 0.0.0-stage → 1.0.0

package/source/infrastructure/adapters/Http2Adapter/index.mjs

@@ -0,0 +1,144 @@
+//@ts-check
+/**
+ * @file Defines the Node.js `HTTP/2` secure transport adapter.
+ *
+ * @description Provides the concrete `HTTP/2` secure transport adapter for Node.js.
+ *
+ * `Http2Adapter` implements the `TransportAdapter` contract using Node.js'
+ * built-in `node:http2` module. It creates and manages the native
+ * `Http2SecureServer` instance and translates the transport operations defined
+ * by the application into operations provided by the Node.js HTTP/2 server.
+ *
+ * This adapter belongs to the infrastructure layer and isolates the rest
+ * of the application from the Node.js HTTP/2 server implementation.
+ *
+ * @module Http2Adapter
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import http2 from 'node:http2';
+
+// » IMPORT LOCAL MODULES
+import TransportAdapter from '../TransportAdapter/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the underlying Node.js secure HTTP/2 server.
+ *
+ * @typedef {import('node:http2').Http2SecureServer} Http2SecureServer
+ */
+
+/**
+ * Configuration options passed to the underlying Node.js HTTP/2 server.
+ *
+ * This type is provided by the native `node:http2` module and is used to
+ * configure the server created by {@link Http2Adapter}.
+ *
+ * @typedef {import('node:http2').SecureServerOptions} ServerOptions
+ */
+
+/**
+ * Represents an incoming HTTP/1.1 request message from Node.js.
+ *
+ * @typedef {import('node:http').IncomingMessage} IncomingMessage
+ */
+
+/**
+ * Represents a Node.js HTTP/1.1 response.
+ *
+ * @typedef {import('node:http').ServerResponse} ServerResponse
+ */
+
+/**
+ * Represents an incoming HTTP/2 request.
+ *
+ * @typedef {import('node:http2').Http2ServerRequest} Http2ServerRequest
+ */
+
+/**
+ * Represents an HTTP/2 server response.
+ *
+ * @typedef {import('node:http2').Http2ServerResponse} Http2ServerResponse
+ */
+
+/**
+ * Callback that handles an incoming HTTP/1.1 request.
+ *
+ * @callback Http1Handler
+ * @param {IncomingMessage} request - The incoming HTTP/1.1 request message.
+ * @param {ServerResponse} response - The HTTP/1.1 server response.
+ * @returns {void}
+ */
+
+/**
+ * Callback that handles an incoming HTTP/2 request.
+ *
+ * @callback Http2Handler
+ * @param {Http2ServerRequest} request - The incoming HTTP/2 request message.
+ * @param {Http2ServerResponse} response - The HTTP/2 server response.
+ * @returns {void}
+ */
+
+/**
+ * Identity for a secure HTTP/2 server (h2).
+ *
+ * Represents a permitted transport identity for a Node.js HTTP/2 server
+ * operating over TLS.
+ *
+ * @typedef  {object}                      TransportIdentityH2
+ * @property {Http2SecureServer}           server              - The underlying Node.js secure HTTP/2 server instance.
+ * @property {'https'}                     protocol            - The application-level protocol (`https`).
+ * @property {'h2'}                        transport           - The transport identifier for HTTP/2 over TLS (`h2`).
+ * @property {Http2Handler | Http1Handler} requestHandler      - Callback invoked for each incoming request.
+ */
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Node.js implementation of the {@link TransportAdapter} contract.
+ *
+ * @classdesc `Http2Adapter` adapts the native Node.js secure HTTP/2 server to
+ * the transport contract expected by the application. It owns the underlying
+ * `Http2SecureServer` instance and exposes transport-independent operations
+ * through the inherited `TransportAdapter` API.
+ *
+ * The adapter uses the `https` protocol and `h2` transport, while delegating
+ * server lifecycle operations to Node.js.
+ *
+ * @augments {TransportAdapter<TransportIdentityH2>}
+ */
+class Http2Adapter extends TransportAdapter {
+  /**
+   * Creates a Node.js secure HTTP/2 transport adapter.
+   *
+   * The constructor creates the underlying Node.js secure HTTP/2 server
+   * using the supplied server configuration.
+   *
+   * @param {ServerOptions} [options] - Configuration for the HTTP/2 server.
+   * @example
+   * ```js
+   * const adapter = new Http2Adapter({
+   *   key: privateKey,
+   *   cert: certificate
+   * });
+   * ```
+   */
+  constructor(options) {
+    const server = Http2Adapter.#createServer(options);
+    super(server, 'https', 'h2');
+  }
+
+  /**
+   * Creates the underlying Node.js secure HTTP/2 server.
+   *
+   * @param {ServerOptions} [options] - Configuration for the HTTP/2 server.
+   * @returns {Http2SecureServer} The created Node.js secure HTTP/2 server.
+   */
+  static #createServer(options) {
+    if (options === undefined) {
+      return http2.createSecureServer();
+    }
+    return http2.createSecureServer(options);
+  }
+}
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default Http2Adapter;

package/source/infrastructure/adapters/Http2CleartextAdapter/index.mjs

@@ -0,0 +1,147 @@
+// @ts-check
+/**
+ * @file Defines the Node.js `HTTP/2` cleartext transport adapter.
+ *
+ * @description Provides the concrete `HTTP/2` cleartext transport adapter for Node.js.
+ *
+ * `Http2CleartextAdapter` implements the `TransportAdapter` contract using Node.js'
+ * built-in `node:http2` module. It creates and manages the native
+ * `Http2Server` instance and translates the transport operations defined
+ * by the application into operations provided by the Node.js HTTP/2 server.
+ *
+ * This adapter belongs to the infrastructure layer and isolates the rest
+ * of the application from the Node.js HTTP/2 server implementation.
+ *
+ * @module Http2CleartextAdapter
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import http2 from 'node:http2';
+
+// » IMPORT LOCAL MODULES
+import TransportAdapter from '../TransportAdapter/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the underlying Node.js cleartext HTTP/2 server.
+ *
+ * @typedef {import('node:http2').Http2Server} Http2Server
+ */
+
+/**
+ * Configuration options passed to the underlying Node.js HTTP/2 server.
+ *
+ * This type is provided by the native `node:http2` module and is used to
+ * configure the server created by {@link Http2CleartextAdapter}.
+ *
+ * @typedef {import('node:http2').ServerOptions} ServerOptions
+ */
+
+/**
+ * Represents an incoming HTTP/1.1 request message from Node.js.
+ *
+ * @typedef {import('node:http').IncomingMessage} IncomingMessage
+ */
+
+/**
+ * Represents a Node.js HTTP/1.1 response.
+ *
+ * @typedef {import('node:http').ServerResponse} ServerResponse
+ */
+
+/**
+ * Represents an incoming HTTP/2 request.
+ *
+ * @typedef {import('node:http2').Http2ServerRequest} Http2ServerRequest
+ */
+
+/**
+ * Represents an HTTP/2 server response.
+ *
+ * @typedef {import('node:http2').Http2ServerResponse} Http2ServerResponse
+ */
+
+/**
+ * Callback that handles an incoming HTTP/1.1 request.
+ *
+ * @callback Http1Handler
+ * @param {IncomingMessage} request - The incoming HTTP/1.1 request message.
+ * @param {ServerResponse} response - The HTTP/1.1 server response.
+ * @returns {void}
+ */
+
+/**
+ * Callback that handles an incoming HTTP/2 request.
+ *
+ * @callback Http2Handler
+ * @param {Http2ServerRequest} request - The incoming HTTP/2 request message.
+ * @param {Http2ServerResponse} response - The HTTP/2 server response.
+ * @returns {void}
+ */
+
+/**
+ * Identity for a cleartext HTTP/2 server (h2c).
+ *
+ * Represents a permitted transport identity for a Node.js HTTP/2 server
+ * operating over cleartext.
+ *
+ * @typedef  {object}                      TransportIdentityH2C
+ * @property {Http2Server}                 server               - The underlying Node.js HTTP/2 cleartext server instance.
+ * @property {'http'}                      protocol             - The application-level protocol (`http`).
+ * @property {'h2c'}                       transport            - The transport identifier for HTTP/2 cleartext (`h2c`).
+ * @property {Http2Handler | Http1Handler} requestHandler       - Callback invoked for each incoming request.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Node.js implementation of the {@link TransportAdapter} contract.
+ *
+ * @classdesc `Http2CleartextAdapter` adapts the native Node.js cleartext HTTP/2
+ * server to the transport contract expected by the application. It owns the
+ * underlying `Http2Server` instance and exposes transport-independent
+ * operations through the inherited `TransportAdapter` API.
+ *
+ * The adapter uses the `http` protocol and `h2c` transport, while delegating
+ * server lifecycle operations to Node.js.
+ *
+ * @augments {TransportAdapter<TransportIdentityH2C>}
+ */
+class Http2CleartextAdapter extends TransportAdapter {
+  /**
+   * Creates a Node.js cleartext HTTP/2 transport adapter.
+   *
+   * The constructor creates the underlying Node.js cleartext HTTP/2 server
+   * using the supplied server configuration.
+   *
+   * @param {ServerOptions} [options] - Configuration for the HTTP/2 server.
+   * @example
+   * ```js
+   * const adapter = new Http2CleartextAdapter({
+   *   settings: {
+   *     enablePush: false
+   *   }
+   * });
+   * ```
+   */
+  constructor(options) {
+    const server = Http2CleartextAdapter.#createServer(options);
+    super(server, 'http', 'h2c');
+  }
+
+  /**
+   * Creates the underlying Node.js cleartext HTTP/2 server.
+   *
+   * @param {ServerOptions} [options] - Configuration for the HTTP/2 server.
+   * @returns {Http2Server} The created Node.js cleartext HTTP/2 server.
+   */
+  static #createServer(options) {
+    if (options === undefined) {
+      return http2.createServer();
+    }
+    return http2.createServer(options);
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default Http2CleartextAdapter;

package/source/infrastructure/adapters/HttpAdapter/index.mjs

@@ -0,0 +1,124 @@
+// @ts-check
+/**
+ * @file Defines the Node.js `HTTP` transport adapter.
+ *
+ * @description Provides the concrete `HTTP` transport adapter for Node.js.
+ *
+ * `HttpAdapter` implements the `TransportAdapter` contract using Node.js'
+ * built-in `node:http` module. It creates and manages the native
+ * `http.Server` instance and translates the transport operations defined
+ * by the application into operations provided by the Node.js HTTP server.
+ *
+ * This adapter belongs to the infrastructure layer and isolates the rest
+ * of the application from the Node.js HTTP server implementation.
+ *
+ * @module HttpAdapter
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import http from 'node:http';
+
+// » IMPORT LOCAL MODULES
+import TransportAdapter from '../TransportAdapter/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the underlying Node.js HTTP server.
+ *
+ * @typedef {import('node:http').Server} HttpServer
+ */
+
+/**
+ * Configuration options passed to the underlying Node.js HTTP server.
+ *
+ * This type is provided by the native `node:http` module and is used to
+ * configure the server created by {@link HttpAdapter}.
+ *
+ * @typedef {import('node:http').ServerOptions} ServerOptions
+ */
+
+/**
+ * Represents an incoming HTTP/1.1 request message from Node.js.
+ *
+ * @typedef {import('node:http').IncomingMessage} IncomingMessage
+ */
+
+/**
+ * Represents a Node.js HTTP/1.1 response.
+ *
+ * @typedef {import('node:http').ServerResponse} ServerResponse
+ */
+
+/**
+ * Callback that handles an incoming HTTP/1.1 request.
+ *
+ * @callback Http1Handler
+ * @param {IncomingMessage} request - The incoming HTTP/1.1 request message.
+ * @param {ServerResponse} response - The HTTP/1.1 server response.
+ * @returns {void}
+ */
+
+/**
+ * Identity for a plain HTTP/1.1 server.
+ *
+ * Represents a permitted transport identity for a Node.js HTTP server
+ * operating over HTTP/1.1 cleartext.
+ *
+ * @typedef  {object}       TransportIdentityH1
+ * @property {HttpServer}   server              - The underlying Node.js HTTP server instance.
+ * @property {'http'}       protocol            - The application-level protocol (`http`).
+ * @property {'h1'}         transport           - The transport identifier for HTTP/1.1 cleartext (`h1`).
+ * @property {Http1Handler} requestHandler      - Callback invoked for each incoming HTTP request.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Node.js implementation of the {@link TransportAdapter} contract.
+ *
+ * @classdesc `HttpAdapter` adapts the native Node.js HTTP server to the
+ * transport contract expected by the application. It owns the underlying
+ * `http.Server` instance and exposes transport-independent operations
+ * through the inherited `TransportAdapter` API.
+ *
+ * The adapter uses the `http` protocol and `h1` transport, while delegating
+ * server lifecycle operations to Node.js.
+ *
+ * @augments {TransportAdapter<TransportIdentityH1>}
+ */
+class HttpAdapter extends TransportAdapter {
+  /**
+   * Creates a Node.js HTTP transport adapter.
+   *
+   * The constructor creates the underlying Node.js HTTP server using the
+   * supplied server configuration.
+   *
+   * @param {ServerOptions} [options] - Configuration for the HTTP server.
+   * @example
+   * ```js
+   * const adapter = new HttpAdapter({
+   *   keepAliveTimeout: 65000
+   * });
+   * ```
+   */
+  constructor(options) {
+    const server = HttpAdapter.#createServer(options);
+    super(server, 'http', 'h1');
+  }
+
+  /**
+   * Creates the underlying Node.js HTTP server.
+   *
+   * @param {ServerOptions} [options] - Configuration for the HTTP server.
+   * @returns {HttpServer} The created Node.js HTTP server.
+   */
+  static #createServer(options) {
+    if (options === undefined) {
+      return http.createServer();
+    }
+
+    return http.createServer(options);
+  }
+}
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default HttpAdapter;

package/source/infrastructure/adapters/HttpsAdapter/index.mjs

@@ -0,0 +1,124 @@
+// @ts-check
+/**
+ * @file Defines the Node.js `HTTPS` transport adapter.
+ *
+ * @description Provides the concrete `HTTPS` transport adapter for Node.js.
+ *
+ * `HttpsAdapter` implements the `TransportAdapter` contract using Node.js'
+ * built-in `node:https` module. It creates and manages the native
+ * `https.Server` instance and translates the transport operations defined
+ * by the application into operations provided by the Node.js HTTP server.
+ *
+ * This adapter belongs to the infrastructure layer and isolates the rest
+ * of the application from the Node.js HTTP server implementation.
+ *
+ * @module HttpsAdapter
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import https from 'node:https';
+
+// » IMPORT LOCAL MODULES
+import TransportAdapter from '../TransportAdapter/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the underlying Node.js HTTPS server.
+ *
+ * @typedef {import('node:https').Server} HttpsServer
+ */
+
+/**
+ * Configuration options passed to the underlying Node.js HTTPS server.
+ *
+ * This type is provided by the native `node:https` module and is used to
+ * configure the server created by {@link HttpsAdapter}.
+ *
+ * @typedef {import('node:https').ServerOptions} ServerOptions
+ */
+
+/**
+ * Represents an incoming HTTP/1.1 request message from Node.js.
+ *
+ * @typedef {import('node:http').IncomingMessage} IncomingMessage
+ */
+
+/**
+ * Represents a Node.js HTTP/1.1 response.
+ *
+ * @typedef {import('node:http').ServerResponse} ServerResponse
+ */
+
+/**
+ * Callback that handles an incoming HTTP/1.1 request.
+ *
+ * @callback Http1Handler
+ * @param {IncomingMessage} request - The incoming HTTP/1.1 request message.
+ * @param {ServerResponse} response - The HTTP/1.1 server response.
+ * @returns {void}
+ */
+
+/**
+ * Identity for a secure HTTPS/1.1 server.
+ *
+ * Represents a valid combination of a Node.js HTTPS server instance
+ * with the corresponding protocol and transport identifiers.
+ *
+ * @typedef  {object}       TransportIdentityH1S
+ * @property {HttpsServer}  server               - The underlying Node.js HTTPS server instance.
+ * @property {'https'}      protocol             - The application-level protocol (`https`).
+ * @property {'h1s'}        transport            - The transport identifier for HTTP/1.1 over TLS (`h1s`).
+ * @property {Http1Handler} requestHandler       - Callback invoked for each incoming HTTP request.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Node.js implementation of the {@link TransportAdapter} contract.
+ *
+ * @classdesc `HttpsAdapter` adapts the native Node.js HTTPS server to the
+ * transport contract expected by the application. It owns the underlying
+ * `https.Server` instance and exposes transport-independent operations
+ * through the inherited `TransportAdapter` API.
+ *
+ * The adapter uses the `https` protocol and `h1s` transport, while delegating
+ * server lifecycle operations to Node.js.
+ *
+ * @augments {TransportAdapter<TransportIdentityH1S>}
+ */
+class HttpsAdapter extends TransportAdapter {
+  /**
+   * Creates a Node.js HTTPS transport adapter.
+   *
+   * The constructor creates the underlying Node.js HTTPS server using the
+   * supplied server configuration.
+   *
+   * @param {ServerOptions} [options] - Configuration for the HTTPS server.
+   * @example
+   * ```js
+   * const adapter = new HttpsAdapter({
+   *   keepAliveTimeout: 65000
+   * });
+   * ```
+   */
+  constructor(options) {
+    const server = HttpsAdapter.#createServer(options);
+    super(server, 'https', 'h1s');
+  }
+
+  /**
+   * Creates the underlying Node.js secure HTTP server.
+   *
+   * @param {ServerOptions} [options] - Configuration for the HTTPS server.
+   * @returns {HttpsServer} The created Node.js secure HTTP server.
+   */
+  static #createServer(options) {
+    if (options === undefined) {
+      return https.createServer();
+    }
+
+    return https.createServer(options);
+  }
+}
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default HttpsAdapter;