@fluojs/websockets 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/deno/deno-service.js

@@ -11,6 +11,7 @@ import { WEBSOCKET_OPTIONS_INTERNAL } from '../options-token.internal.js';
 const DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET = 256;
 const DEFAULT_MAX_WEBSOCKET_CONNECTIONS = 1_000;
 const DEFAULT_MAX_WEBSOCKET_PAYLOAD_BYTES = 1_048_576;
+const DEFAULT_WEBSOCKET_SHUTDOWN_TIMEOUT_MS = 5_000;
 const LIFECYCLE_LOG_CONTEXT = 'WebSocketGatewayLifecycleService';
 const WEBSOCKET_OPEN_READY_STATE = 1;
 function hasDenoWebSocketBindingHost(adapter) {
@@ -37,10 +38,20 @@ function isHttpExceptionLike(error) {
 }
 function resolveMessageByteLength(message) {
   if (typeof message === 'string') {
-    return Buffer.byteLength(message);
+    return new TextEncoder().encode(message).byteLength;
   }
   return message.size;
 }
+function createCompletionSignal() {
+  let resolve;
+  const promise = new Promise(res => {
+    resolve = res;
+  });
+  return {
+    promise,
+    resolve
+  };
+}
 
 /**
  * Boots Deno-backed websocket gateways and manages their room lifecycle state.
@@ -50,11 +61,14 @@ class DenoWebSocketGatewayLifecycleService {
   static {
     [_DenoWebSocketGateway, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, HTTP_APPLICATION_ADAPTER, WEBSOCKET_OPTIONS_INTERNAL)], []).c;
   }
+  isShuttingDown = false;
+  pendingUpgradeOperations = new Set();
   pendingUpgradeReservations = 0;
   roomSockets = new Map();
   shutdownPromise;
   socketRegistry = new Map();
   socketRooms = new Map();
+  socketStates = new Map();
   constructor(runtimeContainer, compiledModules, logger, adapter, moduleOptions) {
     this.runtimeContainer = runtimeContainer;
     this.compiledModules = compiledModules;
@@ -90,53 +104,60 @@ class DenoWebSocketGatewayLifecycleService {
   createBinding(descriptors) {
     const descriptorsByPath = this.groupDescriptorsByPath(descriptors);
     return {
-      fetch: async (request, host) => {
-        if (!isWebSocketUpgradeRequest(request)) {
-          return new Response(null, {
-            status: 426
-          });
-        }
-        let targetPath;
-        try {
-          targetPath = normalizeGatewayPath(new URL(request.url).pathname);
-        } catch {
-          return new Response(null, {
-            status: 400
-          });
-        }
-        const descriptors = descriptorsByPath.get(targetPath);
-        if (!descriptors) {
-          return new Response(null, {
-            status: 404
-          });
-        }
-        const rejection = await this.resolveUpgradeRejection(request, targetPath);
-        if (rejection) {
-          return new Response(rejection.body ?? null, {
-            headers: rejection.headers,
-            status: rejection.status
-          });
-        }
-        let response;
-        let socket;
-        try {
-          ({
-            response,
-            socket
-          } = host.upgrade(request));
-        } catch (error) {
-          this.releaseUpgradeReservation();
-          throw error;
-        }
-        void this.bindConnectionHandlers(socket, request, descriptors).catch(error => {
-          this.unregisterSocket(this.findSocketId(socket));
-          this.logger.error('WebSocket gateway open lifecycle failed.', error, LIFECYCLE_LOG_CONTEXT);
-          socket.close(1011, 'Internal server error');
-        });
-        return response;
-      }
+      fetch: (request, host) => this.trackPendingUpgradeOperation(this.handleUpgradeRequest(request, host, descriptorsByPath))
     };
   }
+  async handleUpgradeRequest(request, host, descriptorsByPath) {
+    if (!isWebSocketUpgradeRequest(request)) {
+      return new Response(null, {
+        status: 426
+      });
+    }
+    let targetPath;
+    try {
+      targetPath = normalizeGatewayPath(new URL(request.url).pathname);
+    } catch {
+      return new Response(null, {
+        status: 400
+      });
+    }
+    const descriptors = descriptorsByPath.get(targetPath);
+    if (!descriptors) {
+      return new Response(null, {
+        status: 404
+      });
+    }
+    const rejection = await this.resolveUpgradeRejection(request, targetPath);
+    if (rejection) {
+      return new Response(rejection.body ?? null, {
+        headers: rejection.headers,
+        status: rejection.status
+      });
+    }
+    if (this.isShuttingDown) {
+      this.releaseUpgradeReservation();
+      return new Response('WebSocket server is shutting down.', {
+        status: 503
+      });
+    }
+    let response;
+    let socket;
+    try {
+      ({
+        response,
+        socket
+      } = host.upgrade(request));
+    } catch (error) {
+      this.releaseUpgradeReservation();
+      throw error;
+    }
+    void this.trackPendingUpgradeOperation(this.bindConnectionHandlers(socket, request, descriptors)).catch(error => {
+      this.unregisterSocket(this.findSocketId(socket));
+      this.logger.error('WebSocket gateway open lifecycle failed.', error, LIFECYCLE_LOG_CONTEXT);
+      socket.close(1011, 'Internal server error');
+    });
+    return response;
+  }
   groupDescriptorsByPath(descriptors) {
     const descriptorsByPath = new Map();
     for (const descriptor of descriptors) {
@@ -153,17 +174,35 @@ class DenoWebSocketGatewayLifecycleService {
     const state = this.createConnectionHandlerState(request, descriptors);
     this.releaseUpgradeReservation();
     this.socketRegistry.set(state.socketId, socket);
+    this.socketStates.set(state.socketId, state);
     this.attachConnectionListeners(state, socket, request);
-    await this.resolveConnectionGateways(state);
-    await this.runConnectHandlers(state, socket);
-    await this.finalizeConnectionBinding(state, socket, request);
+    try {
+      await this.resolveConnectionGateways(state);
+      await this.runConnectHandlers(state, socket);
+      await this.finalizeConnectionBinding(state, socket, request);
+      if (this.isShuttingDown && socket.readyState === WEBSOCKET_OPEN_READY_STATE) {
+        socket.close(1001, 'Server shutting down');
+        await state.disconnectLifecyclePromise;
+      }
+    } finally {
+      if (!state.handlersReady && state.bufferedDisconnect) {
+        this.settleDisconnectLifecycle(state);
+      }
+      this.settleConnectLifecycle(state);
+    }
   }
   createConnectionHandlerState(request, descriptors) {
+    const connectLifecycle = createCompletionSignal();
+    const disconnectLifecycle = createCompletionSignal();
     return {
       bufferedDisconnect: undefined,
       bufferedMessages: [],
       bufferedMessagesStartIndex: 0,
+      connectLifecycleSettled: false,
+      connectLifecyclePromise: connectLifecycle.promise,
       descriptors,
+      disconnectLifecycleSettled: false,
+      disconnectLifecyclePromise: disconnectLifecycle.promise,
       enqueuedMessageCount: 0,
       handlerQueue: Promise.resolve(),
       handlersReady: false,
@@ -171,10 +210,26 @@ class DenoWebSocketGatewayLifecycleService {
       queuedMessages: [],
       queuedMessagesStartIndex: 0,
       request,
+      resolveConnectLifecycle: connectLifecycle.resolve,
+      resolveDisconnectLifecycle: disconnectLifecycle.resolve,
       resolved: [],
       socketId: crypto.randomUUID()
     };
   }
+  settleConnectLifecycle(state) {
+    if (state.connectLifecycleSettled) {
+      return;
+    }
+    state.connectLifecycleSettled = true;
+    state.resolveConnectLifecycle();
+  }
+  settleDisconnectLifecycle(state) {
+    if (state.disconnectLifecycleSettled) {
+      return;
+    }
+    state.disconnectLifecycleSettled = true;
+    state.resolveDisconnectLifecycle();
+  }
   attachConnectionListeners(state, socket, request) {
     socket.addEventListener('message', event => {
       if (this.closeOversizedPayload(state.socketId, socket, event.data)) {
@@ -311,6 +366,8 @@ class DenoWebSocketGatewayLifecycleService {
       await dispatchGatewayDisconnect(state.resolved, socket, disconnectEvent.code, disconnectEvent.reason, state.socketId, this.logger, LIFECYCLE_LOG_CONTEXT);
     }).catch(error => {
       this.logger.error('WebSocket gateway disconnect dispatch failed.', error, LIFECYCLE_LOG_CONTEXT);
+    }).finally(() => {
+      this.settleDisconnectLifecycle(state);
     });
   }
   async resolveConnectionGateways(state) {
@@ -361,6 +418,12 @@ class DenoWebSocketGatewayLifecycleService {
     return '';
   }
   async resolveUpgradeRejection(request, path) {
+    if (this.isShuttingDown) {
+      return {
+        body: 'WebSocket server is shutting down.',
+        status: 503
+      };
+    }
     if (!this.tryReserveUpgradeSlot()) {
       return {
         body: 'WebSocket connection limit exceeded.',
@@ -437,6 +500,13 @@ class DenoWebSocketGatewayLifecycleService {
     }
     return configured;
   }
+  resolveShutdownTimeoutMs() {
+    const configured = this.moduleOptions.shutdown?.timeoutMs;
+    if (typeof configured !== 'number' || !Number.isFinite(configured) || configured <= 0) {
+      return DEFAULT_WEBSOCKET_SHUTDOWN_TIMEOUT_MS;
+    }
+    return Math.floor(configured);
+  }
   async shutdown() {
     if (this.shutdownPromise) {
       await this.shutdownPromise;
@@ -446,14 +516,112 @@ class DenoWebSocketGatewayLifecycleService {
     await this.shutdownPromise;
   }
   async runShutdownLifecycle() {
+    this.isShuttingDown = true;
     if (hasDenoWebSocketBindingHost(this.adapter)) {
       this.adapter.configureWebSocketBinding(undefined);
     }
+    const shutdownTimeoutMs = this.resolveShutdownTimeoutMs();
+    await this.awaitPendingUpgradeOperations(shutdownTimeoutMs);
+    await this.closeActiveSockets(shutdownTimeoutMs);
     this.pendingUpgradeReservations = 0;
     this.socketRegistry.clear();
     this.socketRooms.clear();
+    this.socketStates.clear();
     this.roomSockets.clear();
   }
+  trackPendingUpgradeOperation(operation) {
+    if (typeof operation === 'function') {
+      return (...args) => this.trackPendingUpgradeOperation(operation(...args));
+    }
+    let trackedOperation;
+    trackedOperation = operation.then(() => undefined, () => undefined).finally(() => {
+      if (trackedOperation) {
+        this.pendingUpgradeOperations.delete(trackedOperation);
+      }
+    });
+    this.pendingUpgradeOperations.add(trackedOperation);
+    return operation;
+  }
+  async awaitPendingUpgradeOperations(timeoutMs) {
+    if (this.pendingUpgradeOperations.size === 0) {
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const timeout = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        reject(new Error(`Timed out while waiting for in-flight Deno websocket upgrades after ${String(timeoutMs)}ms.`));
+      }, timeoutMs);
+      Promise.all([...this.pendingUpgradeOperations]).then(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        resolve();
+      }).catch(error => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        reject(error);
+      });
+    }).catch(error => {
+      this.logger.error(`Failed to wait for in-flight Deno websocket upgrades within ${String(timeoutMs)}ms.`, error, LIFECYCLE_LOG_CONTEXT);
+    });
+  }
+  async closeActiveSockets(timeoutMs) {
+    const activeSockets = [...this.socketRegistry.entries()];
+    if (activeSockets.length === 0) {
+      return;
+    }
+    const activeStates = activeSockets.map(([socketId]) => this.socketStates.get(socketId)).filter(state => state !== undefined);
+    for (const [, socket] of activeSockets) {
+      if (socket.readyState === WEBSOCKET_OPEN_READY_STATE) {
+        socket.close(1001, 'Server shutting down');
+      }
+    }
+    await this.awaitHandlerQueueDrain(activeStates, timeoutMs);
+  }
+  async awaitHandlerQueueDrain(states, timeoutMs) {
+    if (states.length === 0) {
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const timeout = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        reject(new Error(`Timed out while closing Deno websocket connections after ${String(timeoutMs)}ms.`));
+      }, timeoutMs);
+      Promise.all(states.map(async state => {
+        await state.connectLifecyclePromise;
+        await state.disconnectLifecyclePromise;
+      })).then(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        resolve();
+      }).catch(error => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        reject(error);
+      });
+    }).catch(error => {
+      this.logger.error(`Failed to close Deno websocket connections within ${String(timeoutMs)}ms.`, error, LIFECYCLE_LOG_CONTEXT);
+    });
+  }
   joinRoom(socketId, room) {
     let rooms = this.socketRooms.get(socketId);
     if (!rooms) {
@@ -514,6 +682,7 @@ class DenoWebSocketGatewayLifecycleService {
       return;
     }
     this.socketRegistry.delete(socketId);
+    this.socketStates.delete(socketId);
     const rooms = this.socketRooms.get(socketId);
     if (rooms) {
       for (const room of rooms) {

package/dist/deno/deno-types.d.ts

@@ -1,25 +1,52 @@
 import type { WebSocketModuleOptions as SharedWebSocketModuleOptions } from '../types.js';
+/**
+ * Defines the deno web socket message type.
+ */
 export type DenoWebSocketMessage = Blob | string;
+/**
+ * Describes the deno server web socket contract.
+ */
 export interface DenoServerWebSocket extends Pick<WebSocket, 'addEventListener' | 'close' | 'removeEventListener' | 'send'> {
     readonly readyState: number;
 }
+/**
+ * Describes the deno web socket upgrade result contract.
+ */
 export interface DenoWebSocketUpgradeResult<TSocket extends DenoServerWebSocket = DenoServerWebSocket> {
     response: Response;
     socket: TSocket;
 }
+/**
+ * Describes the deno web socket upgrade host contract.
+ */
 export interface DenoWebSocketUpgradeHost<TSocket extends DenoServerWebSocket = DenoServerWebSocket> {
     upgrade(request: Request): DenoWebSocketUpgradeResult<TSocket>;
 }
+/**
+ * Describes the deno web socket binding contract.
+ */
 export interface DenoWebSocketBinding<TSocket extends DenoServerWebSocket = DenoServerWebSocket> {
     fetch(request: Request, host: DenoWebSocketUpgradeHost<TSocket>): Response | Promise<Response>;
 }
+/**
+ * Describes the deno web socket binding host contract.
+ */
 export interface DenoWebSocketBindingHost<TSocket extends DenoServerWebSocket = DenoServerWebSocket> {
     configureWebSocketBinding(binding: DenoWebSocketBinding<TSocket> | undefined): void;
 }
+/**
+ * Defines the typed on message handler type.
+ */
 export type TypedOnMessageHandler<TEvents extends Record<string, unknown>, K extends keyof TEvents> = (payload: TEvents[K], socket: DenoServerWebSocket, request: Request) => void | Promise<void>;
+/**
+ * Describes the web socket gateway context contract.
+ */
 export interface WebSocketGatewayContext {
     request: Request;
     socket: DenoServerWebSocket;
 }
+/**
+ * Defines the web socket module options type.
+ */
 export type WebSocketModuleOptions = SharedWebSocketModuleOptions;
 //# sourceMappingURL=deno-types.d.ts.map

package/dist/deno/deno-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deno-types.d.ts","sourceRoot":"","sources":["../../src/deno/deno-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,IAAI,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAE1F,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,GAAG,qBAAqB,GAAG,MAAM,CAAC;IACzH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IACnG,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IACjG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IAC7F,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,wBAAwB,CAAC,OAAO,CAAC,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChG;AAED,MAAM,WAAW,wBAAwB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IACjG,yBAAyB,CAAC,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;CACrF;AAED,MAAM,MAAM,qBAAqB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,OAAO,IAAI,CACpG,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,OAAO,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,CAAC"}
+{"version":3,"file":"deno-types.d.ts","sourceRoot":"","sources":["../../src/deno/deno-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,IAAI,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAE1F;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,MAAM,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,GAAG,qBAAqB,GAAG,MAAM,CAAC;IACzH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IACnG,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IACjG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;CAChE;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IAC7F,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,wBAAwB,CAAC,OAAO,CAAC,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChG;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IACjG,yBAAyB,CAAC,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;CACrF;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,OAAO,IAAI,CACpG,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,OAAO,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,CAAC"}

package/dist/internal/shared.d.ts

@@ -2,27 +2,108 @@ import type { Token } from '@fluojs/core';
 import type { Container } from '@fluojs/di';
 import type { ApplicationLogger, CompiledModule } from '@fluojs/runtime';
 import type { WebSocketGatewayDescriptor, WebSocketGatewayHandlerDescriptor } from '../types.js';
+/**
+ * Describes the discovery candidate contract.
+ */
 export interface DiscoveryCandidate {
     moduleName: string;
     scope: 'request' | 'singleton' | 'transient';
     targetType: Function;
     token: Token;
 }
+/**
+ * Describes the resolved gateway instance contract.
+ */
 export interface ResolvedGatewayInstance {
     descriptor: WebSocketGatewayDescriptor;
     instance: unknown;
 }
+/**
+ * Defines the parsed web socket message type.
+ */
 export type ParsedWebSocketMessage = {
     event?: string;
     payload: unknown;
 };
+/**
+ * Defines the shared web socket incoming message type.
+ */
 export type SharedWebSocketIncomingMessage = ArrayBuffer | ArrayBufferView | Uint8Array[] | string;
+/**
+ * Is finite positive integer.
+ *
+ * @param value The value.
+ * @returns The is finite positive integer result.
+ */
 export declare function isFinitePositiveInteger(value: unknown): value is number;
+/**
+ * Normalize gateway path.
+ *
+ * @param path The path.
+ * @returns The normalize gateway path result.
+ */
 export declare function normalizeGatewayPath(path: string): string;
+/**
+ * Parse incoming message.
+ *
+ * @param data The data.
+ * @returns The parse incoming message result.
+ */
 export declare function parseIncomingMessage(data: SharedWebSocketIncomingMessage): ParsedWebSocketMessage;
+/**
+ * Discover gateway descriptors.
+ *
+ * @param compiledModules The compiled modules.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The discover gateway descriptors result.
+ */
 export declare function discoverGatewayDescriptors(compiledModules: readonly CompiledModule[], logger: ApplicationLogger, loggerContext: string): WebSocketGatewayDescriptor[];
+/**
+ * Resolve gateway instance.
+ *
+ * @param runtimeContainer The runtime container.
+ * @param descriptor The descriptor.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The resolve gateway instance result.
+ */
 export declare function resolveGatewayInstance(runtimeContainer: Container, descriptor: WebSocketGatewayDescriptor, logger: ApplicationLogger, loggerContext: string): Promise<unknown | undefined>;
+/**
+ * Dispatch gateway message.
+ *
+ * @param resolved The resolved.
+ * @param socket The socket.
+ * @param request The request.
+ * @param data The data.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The dispatch gateway message result.
+ */
 export declare function dispatchGatewayMessage<TSocket, TRequest>(resolved: readonly ResolvedGatewayInstance[], socket: TSocket, request: TRequest, data: SharedWebSocketIncomingMessage, logger: ApplicationLogger, loggerContext: string): Promise<void>;
+/**
+ * Dispatch gateway disconnect.
+ *
+ * @param resolved The resolved.
+ * @param socket The socket.
+ * @param code The code.
+ * @param reason The reason.
+ * @param socketId The socket id.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The dispatch gateway disconnect result.
+ */
 export declare function dispatchGatewayDisconnect<TSocket>(resolved: readonly ResolvedGatewayInstance[], socket: TSocket, code: number, reason: string, socketId: string, logger: ApplicationLogger, loggerContext: string): Promise<void>;
+/**
+ * Run gateway handlers.
+ *
+ * @param instance The instance.
+ * @param descriptor The descriptor.
+ * @param type The type.
+ * @param args The args.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The run gateway handlers result.
+ */
 export declare function runGatewayHandlers(instance: unknown, descriptor: WebSocketGatewayDescriptor, type: WebSocketGatewayHandlerDescriptor['type'], args: unknown[], logger: ApplicationLogger, loggerContext: string): Promise<void>;
 //# sourceMappingURL=shared.d.ts.map

package/dist/internal/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/internal/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,KAAK,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGzE,OAAO,KAAK,EACV,0BAA0B,EAC1B,iCAAiC,EAClC,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;IAC7C,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;CACd;AAQD,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,0BAA0B,CAAC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,8BAA8B,GACtC,WAAW,GACX,eAAe,GACf,UAAU,EAAE,GACZ,MAAM,CAAC;AAEX,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEvE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,8BAA8B,GAAG,sBAAsB,CA4CjG;AAED,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,0BAA0B,EAAE,CA4B9B;AAED,wBAAsB,sBAAsB,CAC1C,gBAAgB,EAAE,SAAS,EAC3B,UAAU,EAAE,0BAA0B,EACtC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAW9B;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,EAC5D,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,8BAA8B,EACpC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED,wBAAsB,yBAAyB,CAAC,OAAO,EACrD,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,0BAA0B,EACtC,IAAI,EAAE,iCAAiC,CAAC,MAAM,CAAC,EAC/C,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/internal/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,KAAK,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGzE,OAAO,KAAK,EACV,0BAA0B,EAC1B,iCAAiC,EAClC,MAAM,aAAa,CAAC;AAIrB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;IAC7C,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;CACd;AAQD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,0BAA0B,CAAC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8BAA8B,GACtC,WAAW,GACX,eAAe,GACf,UAAU,EAAE,GACZ,MAAM,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,8BAA8B,GAAG,sBAAsB,CA4CjG;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,0BAA0B,EAAE,CA4B9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,gBAAgB,EAAE,SAAS,EAC3B,UAAU,EAAE,0BAA0B,EACtC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAW9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,EAC5D,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,8BAA8B,EACpC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EACrD,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,0BAA0B,EACtC,IAAI,EAAE,iCAAiC,CAAC,MAAM,CAAC,EAC/C,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/internal/shared.js

@@ -1,9 +1,39 @@
 import { getClassDiMetadata } from '@fluojs/core/internal';
 import { getWebSocketGatewayMetadata, getWebSocketHandlerMetadataEntries } from '../metadata.js';
 const textDecoder = new TextDecoder();
+
+/**
+ * Describes the discovery candidate contract.
+ */
+
+/**
+ * Describes the resolved gateway instance contract.
+ */
+
+/**
+ * Defines the parsed web socket message type.
+ */
+
+/**
+ * Defines the shared web socket incoming message type.
+ */
+
+/**
+ * Is finite positive integer.
+ *
+ * @param value The value.
+ * @returns The is finite positive integer result.
+ */
 export function isFinitePositiveInteger(value) {
   return typeof value === 'number' && Number.isFinite(value) && value > 0 && Number.isInteger(value);
 }
+
+/**
+ * Normalize gateway path.
+ *
+ * @param path The path.
+ * @returns The normalize gateway path result.
+ */
 export function normalizeGatewayPath(path) {
   if (path === '/') {
     return '/';
@@ -11,6 +41,13 @@ export function normalizeGatewayPath(path) {
   const normalized = `/${path.replace(/^\/+/, '').replace(/\/+$/, '')}`;
   return normalized === '' ? '/' : normalized;
 }
+
+/**
+ * Parse incoming message.
+ *
+ * @param data The data.
+ * @returns The parse incoming message result.
+ */
 export function parseIncomingMessage(data) {
   let text;
   if (typeof data === 'string') {
@@ -50,6 +87,15 @@ export function parseIncomingMessage(data) {
     payload: parsed
   };
 }
+
+/**
+ * Discover gateway descriptors.
+ *
+ * @param compiledModules The compiled modules.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The discover gateway descriptors result.
+ */
 export function discoverGatewayDescriptors(compiledModules, logger, loggerContext) {
   const seenTargets = new Set();
   const descriptors = [];
@@ -70,6 +116,16 @@ export function discoverGatewayDescriptors(compiledModules, logger, loggerContex
   }
   return descriptors;
 }
+
+/**
+ * Resolve gateway instance.
+ *
+ * @param runtimeContainer The runtime container.
+ * @param descriptor The descriptor.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The resolve gateway instance result.
+ */
 export async function resolveGatewayInstance(runtimeContainer, descriptor, logger, loggerContext) {
   try {
     return await runtimeContainer.resolve(descriptor.token);
@@ -78,6 +134,18 @@ export async function resolveGatewayInstance(runtimeContainer, descriptor, logge
     return undefined;
   }
 }
+
+/**
+ * Dispatch gateway message.
+ *
+ * @param resolved The resolved.
+ * @param socket The socket.
+ * @param request The request.
+ * @param data The data.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The dispatch gateway message result.
+ */
 export async function dispatchGatewayMessage(resolved, socket, request, data, logger, loggerContext) {
   const parsed = parseIncomingMessage(data);
   for (const {
@@ -90,6 +158,19 @@ export async function dispatchGatewayMessage(resolved, socket, request, data, lo
     }
   }
 }
+
+/**
+ * Dispatch gateway disconnect.
+ *
+ * @param resolved The resolved.
+ * @param socket The socket.
+ * @param code The code.
+ * @param reason The reason.
+ * @param socketId The socket id.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The dispatch gateway disconnect result.
+ */
 export async function dispatchGatewayDisconnect(resolved, socket, code, reason, socketId, logger, loggerContext) {
   for (const {
     descriptor,
@@ -98,6 +179,18 @@ export async function dispatchGatewayDisconnect(resolved, socket, code, reason,
     await runGatewayHandlers(instance, descriptor, 'disconnect', [socket, code, reason, socketId], logger, loggerContext);
   }
 }
+
+/**
+ * Run gateway handlers.
+ *
+ * @param instance The instance.
+ * @param descriptor The descriptor.
+ * @param type The type.
+ * @param args The args.
+ * @param logger The logger.
+ * @param loggerContext The logger context.
+ * @returns The run gateway handlers result.
+ */
 export async function runGatewayHandlers(instance, descriptor, type, args, logger, loggerContext) {
   const handlers = descriptor.handlers.filter(handler => handler.type === type);
   for (const handler of handlers) {