@boo-labs/server 0.0.0-stage → 1.0.0

package/source/core/IPCMain/IPCServerChannel.mjs

@@ -0,0 +1,331 @@
+// @ts-check
+/**
+ * @file Orchestrates IPC request processing for one WebSocket connection.
+ *
+ * @description
+ * IPCServerChannel binds one established WebSocket connection to the IPCMain
+ * dispatch capability. It owns request decoding, response serialization,
+ * connection-local state, and transport writes.
+ *
+ * IPCServerChannel does not own IPC handlers, event listeners, or application
+ * dispatch rules. Those responsibilities remain with IPCMain.
+ *
+ * @module IPCServerChannel
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import IPCProtocol from './IPCProtocol.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents an established WebSocket connection contract.
+ *
+ * @typedef {import('#adapters/TransportAdapter').WebSocketConnection} WebSocketConnection
+ */
+
+/**
+ * Represents a decoded IPC request.
+ *
+ * @typedef {import('./IPCProtocol.mjs').IPCRequest} IPCRequest
+ */
+
+/**
+ * Represents the normalized IPC wire error.
+ *
+ * @typedef {import('./IPCProtocol.mjs').IPCError} IPCError
+ */
+
+/**
+ * Represents a successful response payload supplied by the IPC host.
+ *
+ * @typedef  {object}  IPCSuccessPayload
+ * @property {unknown} result            - Handler result returned to the IPC caller.
+ */
+
+/**
+ * Represents an error response payload supplied by the IPC host.
+ *
+ * @typedef  {object}  IPCErrorPayload
+ * @property {unknown} error           - Error value produced while handling the request.
+ */
+
+/**
+ * Represents a response payload supplied by the IPC host.
+ *
+ * @typedef {IPCSuccessPayload|IPCErrorPayload} IPCResponsePayload
+ */
+
+/**
+ * Dispatches a decoded IPC request and provides a callback for its response.
+ *
+ * @typedef {(request: IPCRequest, respond: (payload: IPCResponsePayload) => void) => Promise<void>} DispatchFunction
+ */
+
+/**
+ * Represents the internal capability supplied by IPCMain to dispatch IPC requests.
+ *
+ * @typedef  {object}           IPCChannelHost
+ * @property {DispatchFunction} dispatch       - Dispatches an IPC request and reports its response through the supplied callback.
+ */
+
+// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Determines whether a value is a non-null plain object.
+ *
+ * @private
+ * @param {unknown} value - Value to inspect.
+ * @returns {value is Record<string, unknown>} `true` if the value is a plain object.
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Orchestrates IPC request processing for one WebSocket connection.
+ *
+ * @classdesc IPCServerChannel binds one established WebSocket connection to the
+ * IPCMain dispatch capability. It owns request decoding, response
+ * serialization, connection-local state, and transport writes.
+ *
+ * IPCServerChannel does not own IPC handlers, event listeners, or application
+ * dispatch rules. Those responsibilities remain with IPCMain.
+ */
+class IPCServerChannel {
+  /**
+   * Established WebSocket connection owned by this IPC channel.
+   *
+   * @type {WebSocketConnection}
+   */
+  #connection;
+
+  /**
+   * Internal IPC host used to dispatch requests.
+   *
+   * @type {IPCChannelHost}
+   */
+  #host;
+
+  /**
+   * IPC wire protocol used to decode requests and serialize responses.
+   *
+   * @type {IPCProtocol}
+   */
+  #protocol = new IPCProtocol();
+
+  /**
+   * Indicates whether this IPC channel is closed.
+   *
+   * @type {boolean}
+   */
+  #closed = false;
+
+  /**
+   * Creates an IPC channel bound to a WebSocket connection and an IPC host.
+   *
+   * Registers message, close, and error handlers on the connection. The
+   * channel is considered closed once the connection emits either `close`
+   * or `error`.
+   *
+   * @param {WebSocketConnection} connection - Established WebSocket connection.
+   * @param {IPCChannelHost} host - IPC host providing the dispatch capability.
+   * @example
+   * ```js
+   * const channel = new IPCServerChannel(connection, {
+   *   dispatch: async (request, respond) => {
+   *     respond({ result: { ok: true } });
+   *   },
+   * });
+   * ```
+   */
+  constructor(connection, host) {
+    this.#connection = connection;
+    this.#host = host;
+
+    connection.on('message', raw => {
+      void this.#onMessage(raw);
+    });
+
+    connection.on('close', () => {
+      this.#closed = true;
+    });
+
+    connection.on('error', () => {
+      this.#closed = true;
+    });
+  }
+
+  /**
+   * Decodes and dispatches one incoming WebSocket message.
+   *
+   * @param {string|Buffer} raw - Raw WebSocket message received from the connection.
+   * @returns {Promise<void>} Resolves once the message has been dispatched.
+   */
+  async #onMessage(raw) {
+    if (!this.#closed) {
+      const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+      const request = this.#decodeOrHandleFailure(text);
+
+      if (request !== null) {
+        await this.#dispatchRequest(request);
+      }
+    }
+  }
+
+  /**
+   * Decodes an IPC request and handles decoding failures.
+   *
+   * @param {string} text - Raw IPC payload to decode.
+   * @returns {IPCRequest|null} Decoded IPC request, or null when decoding fails.
+   */
+  #decodeOrHandleFailure(text) {
+    try {
+      return this.#protocol.decode(text);
+    } catch (error) {
+      this.#handleDecodeFailure(text, error);
+      return null;
+    }
+  }
+
+  /**
+   * Dispatches a decoded IPC request to the IPC host.
+   *
+   * @param {IPCRequest} request - Decoded IPC request to dispatch.
+   * @returns {Promise<void>} Resolves once the request has been dispatched.
+   */
+  async #dispatchRequest(request) {
+    if (request.type === 'event') {
+      try {
+        await this.#host.dispatch(request, () => {});
+      } catch {
+        // Event dispatch errors are intentionally isolated from the connection.
+      }
+    } else {
+      const id = request.id;
+      let responded = false;
+
+      /**
+       * Responds to the current invocation once.
+       *
+       * Subsequent invocations are ignored to preserve the one-response
+       * contract of IPC invocations.
+       *
+       * @param {IPCResponsePayload} payload - Response payload supplied by the IPC host.
+       */
+      const respond = payload => {
+        if (!responded) {
+          responded = true;
+          this.#sendResponse(id, payload);
+        }
+      };
+
+      try {
+        await this.#host.dispatch(request, respond);
+      } catch (error) {
+        respond({ error });
+      }
+    }
+  }
+
+  /**
+   * Handles a message that could not be decoded as a valid IPC request.
+   *
+   * A second lightweight parse is intentionally used to recover an invocation
+   * identifier when possible, allowing the peer to correlate the protocol
+   * error with its original request.
+   *
+   * @param {string} text - Raw IPC payload that failed to decode.
+   * @param {unknown} error - Error raised while decoding the payload.
+   */
+  #handleDecodeFailure(text, error) {
+    const id = this.#peekInvokeId(text);
+
+    if (id !== null) {
+      const reason = error instanceof Error ? error.message : 'Invalid IPC message';
+
+      this.#sendRaw(this.#protocol.badMessage(id, reason));
+    }
+  }
+
+  /**
+   * Attempts to recover an invocation identifier without validating the full
+   * IPC request a second time.
+   *
+   * @param {string} text - Raw IPC payload to inspect.
+   * @returns {string|null} Recovered invocation identifier, or null when absent.
+   */
+  #peekInvokeId(text) {
+    try {
+      const value = JSON.parse(text);
+
+      if (
+        isPlainObject(value) &&
+        value.type === 'invoke' &&
+        typeof value.id === 'string' &&
+        value.id.length > 0
+      ) {
+        return value.id;
+      }
+    } catch {
+      // Ignore recovery failures.
+    }
+
+    return null;
+  }
+
+  /**
+   * Encodes and sends an IPC response.
+   *
+   * Raw errors are deliberately forwarded to IPCProtocol, which owns their
+   * normalization into the IPC wire representation.
+   *
+   * @param {string} id - Invocation identifier associated with the request.
+   * @param {IPCResponsePayload} payload - Response payload supplied by the IPC host.
+   */
+  #sendResponse(id, payload) {
+    if (!this.#closed) {
+      const encoded =
+        'error' in payload
+          ? this.#protocol.error(id, payload.error)
+          : this.#protocol.success(id, payload.result);
+
+      this.#sendRaw(encoded);
+    }
+  }
+
+  /**
+   * Sends an already encoded IPC message through the WebSocket connection.
+   *
+   * @param {string} encoded - Encoded IPC message to send.
+   */
+  #sendRaw(encoded) {
+    if (!this.#closed) {
+      try {
+        this.#connection.send(encoded);
+      } catch {
+        this.#forceClose();
+      }
+    }
+  }
+
+  /**
+   * Marks the channel closed and attempts to close its transport connection.
+   *
+   * Invoked when the transport reports a failure that prevents further
+   * writes. Errors thrown while closing the connection are ignored, since
+   * the channel is already considered closed.
+   */
+  #forceClose() {
+    this.#closed = true;
+
+    try {
+      this.#connection.close();
+    } catch {
+      // Ignore transport close failures.
+    }
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default IPCServerChannel;

package/source/core/IPCMain/WebSocketAdapter.mjs

@@ -0,0 +1,189 @@
+// @ts-check
+/**
+ * @file Adapts transport-level WebSocket upgrades to connection listeners.
+ *
+ * @description WebSocketAdapter bridges the TransportAdapter WebSocket upgrade
+ * capability with consumers that need established WebSocket connections.
+ *
+ * The adapter does not own active connections. It only owns the subscription
+ * to the transport upgrade source and the current connection listener.
+ *
+ * @module WebSocketAdapter
+ */
+
+// ━━ 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
+ */
+
+/**
+ * Represents an established WebSocket connection contract.
+ *
+ * @typedef {import('#adapters/TransportAdapter').WebSocketConnection} WebSocketConnection
+ */
+
+/**
+ * Transport-level request used to accept or reject a WebSocket handshake.
+ *
+ * @typedef {import('#adapters/TransportAdapter').WebSocketOpenRequest} WebSocketOpenRequest
+ */
+
+/**
+ * Receives an established WebSocket connection.
+ *
+ * @callback WebSocketConnectionListener
+ * @param {WebSocketConnection} connection - Established WebSocket connection.
+ * @returns {void}
+ */
+
+/**
+ * Configuration for WebSocketAdapter.
+ *
+ * @typedef  {object}                   WebSocketAdapterOptions
+ * @property {(url: string) => boolean} [accept]                - Optional predicate used to accept or reject WebSocket upgrade URLs.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+class WebSocketAdapter {
+  /**
+   * Underlying transport adapter responsible for WebSocket upgrade handling.
+   *
+   * @type {TransportAdapter}
+   */
+  #transport;
+
+  /**
+   * Optional predicate used to determine whether a WebSocket URL is accepted.
+   *
+   * @type {((url: string) => boolean)|null}
+   */
+  #accept;
+
+  /**
+   * Current listener that receives accepted WebSocket connections.
+   *
+   * @type {WebSocketConnectionListener|null}
+   */
+  #listener = null;
+
+  /**
+   * Indicates whether the adapter has subscribed to transport WebSocket upgrades.
+   *
+   * @type {boolean}
+   */
+  #subscribed = false;
+
+  /**
+   * Initializes the WebSocket adapter with a transport adapter.
+   *
+   * @param {TransportAdapter} transport - Transport adapter responsible for handling WebSocket upgrade requests.
+   * @param {WebSocketAdapterOptions} [options] - Optional WebSocket adapter configuration.
+   *
+   * @example
+   * ```js
+   * const adapter = new WebSocketAdapter(transport, {
+   *   accept: url => url.startsWith('/ws/')
+   * });
+   * ```
+   */
+  constructor(transport, options = {}) {
+    this.#transport = transport;
+    this.#accept = typeof options.accept === 'function' ? options.accept : null;
+  }
+
+  /**
+   * Registers the current listener that receives accepted WebSocket connections.
+   *
+   * Calling this method again replaces the previously registered listener.
+   * The underlying transport is subscribed only once, regardless of how many
+   * times this method is called.
+   *
+   * @param {WebSocketConnectionListener} listener - Callback invoked when a WebSocket connection is established.
+   * @throws {TypeError} If listener is not a function.
+   *
+   * @example
+   * ```js
+   * adapter.onConnection(connection => {
+   *   connection.on('message', data => {
+   *     connection.send(`Echo: ${data}`);
+   *   });
+   * });
+   * ```
+   */
+  onConnection(listener) {
+    if (typeof listener !== 'function') {
+      throw new TypeError('listener must be a function');
+    }
+
+    this.#listener = listener;
+
+    if (!this.#subscribed) {
+      this.#subscribed = true;
+
+      this.#transport.onWebSocket(openRequest => {
+        this.#handleOpen(openRequest);
+      });
+    }
+  }
+
+  /**
+   * Stops delivering newly accepted connections to the current listener.
+   *
+   * After `close()` is called, incoming WebSocket upgrade requests are
+   * rejected with `503 WebSocket unavailable`. The adapter cannot be
+   * reopened once closed.
+   *
+   * Existing connections remain owned by their consumer.
+   *
+   * @example
+   * ```js
+   * adapter.close();
+   * ```
+   */
+  close() {
+    this.#listener = null;
+  }
+
+  /**
+   * Processes one transport-level WebSocket upgrade request.
+   *
+   * @param {WebSocketOpenRequest} openRequest - Transport-level request used to accept or reject the WebSocket handshake.
+   */
+  #handleOpen(openRequest) {
+    if (this.#listener === null) {
+      openRequest.reject(503, 'WebSocket unavailable');
+    } else if (this.#accept && !this.#accept(openRequest.url)) {
+      openRequest.reject(404, 'Not Found');
+    } else {
+      Promise.resolve()
+        .then(() => openRequest.accept())
+        .then(
+          connection => {
+            if (this.#listener !== null) {
+              this.#listener(connection);
+            } else {
+              try {
+                connection.close();
+              } catch {
+                // Ignore transport close failures during cleanup.
+              }
+            }
+          },
+          () => {
+            openRequest.reject(500, 'WebSocket accept failed');
+          },
+        );
+    }
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default WebSocketAdapter;

package/source/core/Request/BodyParser/BodyParser.mjs

@@ -0,0 +1,197 @@
+// @ts-check
+/**
+ * @file Defines the base abstraction for parsing incoming request bodies.
+ *
+ * @description Provides the common functionality required by concrete body
+ * parsers to consume an incoming request stream while enforcing the
+ * configured maximum body size.
+ *
+ * When the body limit is exceeded, the underlying request is destroyed so
+ * that the socket is not left consuming bytes. As a consequence, the
+ * connection may be closed abruptly instead of producing a normal `413`
+ * response.
+ *
+ * @module BodyParser
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import RequestError from '#shared/errors/RequestError';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents an incoming HTTP/1.1 or HTTPS/1.1 request message from Node.js.
+ *
+ * @typedef {import('node:http').IncomingMessage} HttpIncomingMessage
+ */
+
+/**
+ * Represents an incoming HTTP/2 request message from Node.js.
+ *
+ * @typedef {import('node:http2').Http2ServerRequest} Http2IncomingMessage
+ */
+
+/**
+ * Represents an incoming request message supported by the server.
+ *
+ * @typedef {HttpIncomingMessage|Http2IncomingMessage} IncomingRequest
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Provides the base abstraction for parsing incoming request bodies.
+ *
+ * @classdesc BodyParser provides common functionality for safely consuming
+ * an incoming request stream while enforcing the configured maximum body
+ * size. Concrete parsers implement `parse()` to transform the request body
+ * into the appropriate representation.
+ */
+class BodyParser {
+  /**
+   * Underlying Node.js incoming request message.
+   *
+   * @type {IncomingRequest}
+   */
+  #incomingMessage;
+
+  /**
+   * Maximum number of bytes allowed for the request body.
+   *
+   * @type {number}
+   */
+  #bodyLimit;
+
+  /**
+   * Creates a body parser.
+   *
+   * @param {IncomingRequest} incomingMessage - Incoming HTTP request message.
+   * @param {number} bodyLimit - Maximum number of bytes allowed for the body.
+   * @throws {Error} Thrown when attempting to instantiate `BodyParser` directly.
+   */
+  constructor(incomingMessage, bodyLimit) {
+    if (new.target === BodyParser) {
+      throw new Error('BodyParser is abstract and cannot be instantiated directly');
+    }
+
+    this.#incomingMessage = incomingMessage;
+    this.#bodyLimit = bodyLimit;
+  }
+
+  /**
+   * Returns the underlying Node.js incoming request message.
+   *
+   * Concrete parsers use this stream to consume the request body.
+   *
+   * @type {IncomingRequest}
+   */
+  get incomingMessage() {
+    return this.#incomingMessage;
+  }
+
+  /**
+   * Parses the incoming request body.
+   *
+   * Concrete parsers must implement this method and return the parsed
+   * representation appropriate for their media type.
+   *
+   * @abstract
+   * @returns {Promise<unknown>} Parsed request body.
+   * @throws {Error} If the method is not implemented.
+   */
+  async parse() {
+    throw new Error('BodyParser.parse() must be implemented.');
+  }
+
+  /**
+   * Reads the complete request body from the underlying stream.
+   *
+   * When `Content-Length` is present, its value is validated before the
+   * stream is consumed. The actual number of bytes received is tracked to
+   * enforce the configured body size limit. When the limit is exceeded, the
+   * underlying request is destroyed so the socket is not left consuming
+   * further bytes.
+   *
+   * Stream-level failures (such as client disconnections) are normalized
+   * into `RequestError` instances. `RequestError` instances produced by
+   * this method are preserved as-is.
+   *
+   * @returns {Promise<Buffer>} The complete request body as a Buffer.
+   * @throws {RequestError} If `Content-Length` is invalid.
+   * @throws {RequestError} If the request body exceeds the configured limit.
+   * @throws {RequestError} If the underlying stream fails while being read.
+   * @example
+   * ```js
+   * const buffer = await bodyParser.readBody();
+   * ```
+   */
+  async readBody() {
+    const contentLength = this.#incomingMessage.headers['content-length'];
+
+    if (contentLength !== undefined) {
+      const length = Number(contentLength);
+
+      if (!Number.isSafeInteger(length) || length < 0) {
+        throw new RequestError('INVALID_CONTENT_LENGTH');
+      }
+
+      if (length > this.#bodyLimit) {
+        this.#incomingMessage.destroy();
+        throw new RequestError('BODY_LIMIT_EXCEEDED', {
+          values: {
+            bodySize: length,
+            bodyLimit: this.#bodyLimit,
+          },
+        });
+      }
+    }
+
+    let bytesRead = 0;
+    const chunks = [];
+
+    try {
+      for await (const chunk of this.#incomingMessage) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytesRead += buffer.length;
+
+        if (bytesRead > this.#bodyLimit) {
+          this.#incomingMessage.destroy();
+          throw new RequestError('BODY_LIMIT_EXCEEDED', {
+            values: {
+              bodySize: bytesRead,
+              bodyLimit: this.#bodyLimit,
+            },
+          });
+        }
+
+        chunks.push(buffer);
+      }
+
+      return Buffer.concat(chunks);
+    } catch (error) {
+      throw this.#normalizeStreamError(error);
+    }
+  }
+
+  /**
+   * Normalizes a thrown value from a stream read operation.
+   *
+   * Preserves existing `RequestError` instances (for example
+   * `BODY_LIMIT_EXCEEDED`) and wraps everything else, including native
+   * stream errors such as `ECONNRESET`, in a `RequestError`.
+   *
+   * @param {unknown} error - The value thrown by the stream.
+   * @returns {RequestError} The normalized error.
+   */
+  #normalizeStreamError(error) {
+    if (error instanceof RequestError) {
+      return error;
+    }
+
+    return new RequestError('BODY_STREAM_ERROR', {
+      cause: error instanceof Error ? error : new Error(String(error)),
+    });
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default BodyParser;