underpost 2.8.884 → 2.8.885

package/src/ws/IoServer.js

@@ -1,39 +1,87 @@
+/**
+ * Module for creating and managing WebSocket servers.
+ * @module src/ws/IoServer
+ * @namespace SocketIoServer
+ */
+
 'use strict';
 
 import { Server } from 'socket.io';
 import { loggerFactory } from '../server/logger.js';
+import UnderpostStartUp from '../server/start.js';
 
-// https://socket.io/docs/v3/
+import http from 'http';
 
 const logger = loggerFactory(import.meta);
 
-const IoServer = (httpServer, options = {}, Connection = () => {}) => {
-  const wsOptions = {
-    cors: {
-      // origin: `http://localhost:${options.port}`,
-      origins: options.origins,
-      methods: ['GET', 'POST', 'DELETE', 'PUT'],
-      allowedHeaders: [
-        'Access-Control-Allow-Headers',
-        'Access-Control-Allow-Origin',
-        'X-Requested-With',
-        'X-Access-Token',
-        'Content-Type',
-        'Host',
-        'Accept',
-        'Connection',
-        'Cache-Control',
-        'Authorization',
-      ],
-      credentials: true,
-    },
-    path: options.path !== '/' ? `${options.path}/socket.io/` : '/socket.io',
-  };
-  return {
-    options: wsOptions,
-    meta: import.meta,
-    ioServer: new Server(httpServer, wsOptions).on('connection', Connection),
-  };
-};
-
-export { IoServer };
+/**
+ * @class
+ * @alias IoServerClass
+ * @memberof SocketIoServer
+ * @classdesc Provides a static factory method to create and configure a Socket.IO server,
+ * encapsulating WebSocket server initialization logic and CORS configuration.
+ */
+class IoServerClass {
+  /**
+   * Creates a new WebSocket server instance attached to an HTTP server.
+   *
+   * @static
+   * @param {http.Server} httpServer - The HTTP server instance to attach the WebSocket server to.
+   * @param {Object} options - Configuration options for the WebSocket server.
+   * @param {string[]} options.origins - List of allowed origins for Cross-Origin Resource Sharing (CORS).
+   * @param {string} options.path - The base path for the API. The WebSocket path ('/socket.io') will be appended to this.
+   * @param {function(import('socket.io').Socket): void} ConnectionHandler - The connection handler function to be executed on a new connection.
+   * @returns {Object} An object containing the final options and the server instance.
+   * @returns {import('socket.io').ServerOptions} return.options - The final options object used to create the WebSocket server.
+   * @returns {import('socket.io').Server} return.ioServer - The created and listening WebSocket server instance.
+   * @returns {object} return.meta - The module's import meta object (`import.meta`).
+   */
+  static create(httpServer, options = {}, ConnectionHandler = () => {}) {
+    const wsOptions = {
+      cors: {
+        origins: options.origins,
+        methods: ['GET', 'POST', 'DELETE', 'PUT'],
+        allowedHeaders: [
+          'Access-Control-Allow-Headers',
+          'Access-Control-Allow-Origin',
+          'X-Requested-With',
+          'X-Access-Token',
+          'Content-Type',
+          'Host',
+          'Accept',
+          'Connection',
+          'Cache-Control',
+          'Authorization',
+        ],
+        credentials: true,
+      },
+      // Ensure the path ends correctly, appending '/socket.io/'
+      path: options.path !== '/' ? `${options.path}/socket.io/` : '/socket.io/',
+    };
+
+    const ioServerInstance = UnderpostStartUp.API.listenServerFactory(() =>
+      new Server(httpServer, wsOptions).on('connection', ConnectionHandler),
+    );
+
+    logger.info('Socket.IO Server created and listening', { path: wsOptions.path });
+
+    return {
+      options: wsOptions,
+      meta: import.meta,
+      ioServer: ioServerInstance,
+    };
+  }
+}
+
+/**
+ * Backward compatibility export for the server creation function.
+ * @memberof SocketIoServer
+ * @function IoServer
+ * @param {http.Server} httpServer - The HTTP server instance.
+ * @param {Object} options - Configuration options.
+ * @param {function(import('socket.io').Socket): void} ConnectionHandler - The connection handler function.
+ * @returns {Object} The server configuration object.
+ */
+const IoServer = IoServerClass.create;
+
+export { IoServerClass, IoServer };

package/src/ws/core/core.ws.connection.js

@@ -1,28 +1,62 @@
+/**
+ * Module for handling new WebSocket connections and setting up channel listeners.
+ * @module ws/core.ws.connection
+ * @namespace CoreWsConnection
+ */
+
 import { loggerFactory } from '../../server/logger.js';
 import { CoreWsChatChannel } from './channels/core.ws.chat.js';
 import { CoreWsMailerChannel } from './channels/core.ws.mailer.js';
 import { CoreWsStreamChannel } from './channels/core.ws.stream.js';
+import { Socket } from 'socket.io'; // Added for JSDoc type hinting
 
 const logger = loggerFactory(import.meta);
 
-const CoreWsConnection = function (socket, wsManagementId) {
-  // const headers = socket.handshake.headers;
-  // const ip = socket.handshake.address;
-  // const { query, auth } = socket.handshake;
+/**
+ * @class
+ * @alias CoreWsConnectionManager
+ * @memberof CoreWsConnection
+ * @classdesc Manages the lifecycle of a new WebSocket connection, setting up listeners for
+ * all registered channels (Chat, Mailer, Stream) and handling disconnection by delegating to channel handlers.
+ */
+class CoreWsConnectionManager {
+  /**
+   * Handles a new WebSocket connection by subscribing it to all active channels
+   * and setting up the disconnect listener.
+   *
+   * @static
+   * @param {Socket} socket - The Socket.IO socket object representing the client connection.
+   * @param {string} wsManagementId - Unique identifier for the WebSocket management context.
+   * @returns {void}
+   */
+  static handleConnection(socket, wsManagementId) {
+    logger.info(`New connection established. Socket ID: ${socket.id}`);
 
-  logger.info(`CoreWsConnection ${socket.id}`);
+    // Subscribe socket to all channel connection handlers (assuming these channels are IoChannel instances)
+    CoreWsChatChannel.connection(socket, wsManagementId);
+    CoreWsMailerChannel.connection(socket, wsManagementId);
+    CoreWsStreamChannel.connection(socket, wsManagementId);
 
-  CoreWsChatChannel.connection(socket, wsManagementId);
-  CoreWsMailerChannel.connection(socket, wsManagementId);
-  CoreWsStreamChannel.connection(socket, wsManagementId);
+    // Set up the disconnect listener
+    socket.on('disconnect', (reason) => {
+      logger.info(`Connection disconnected. Socket ID: ${socket.id} due to reason: ${reason}`);
 
-  socket.on('disconnect', (reason) => {
-    logger.info(`CoreWsConnection ${socket.id} due to reason: ${reason}`);
+      // Notify all channels of the disconnection
+      CoreWsChatChannel.disconnect(socket, reason, wsManagementId);
+      CoreWsMailerChannel.disconnect(socket, reason, wsManagementId);
+      CoreWsStreamChannel.disconnect(socket, reason, wsManagementId);
+    });
+  }
+}
 
-    CoreWsChatChannel.disconnect(socket, reason, wsManagementId);
-    CoreWsMailerChannel.disconnect(socket, reason, wsManagementId);
-    CoreWsStreamChannel.disconnect(socket, reason, wsManagementId);
-  });
-};
+/**
+ * Backward compatibility export for the connection handler function.
+ * @memberof CoreWsConnection
+ * @function CoreWsConnection
+ * @param {Socket} socket - The Socket.IO socket object.
+ * @param {string} wsManagementId - Unique identifier for the WebSocket management context.
+ * @returns {void}
+ */
+const CoreWsConnection = CoreWsConnectionManager.handleConnection;
 
-export { CoreWsConnection };
+export { CoreWsConnectionManager, CoreWsConnection };

package/src/ws/core/core.ws.emit.js

@@ -1,14 +1,53 @@
+/**
+ * Module for standardized WebSocket message emission (sending).
+ * @module ws/core.ws.emit
+ * @namespace CoreWsEmitter
+ */
+
 import { loggerFactory } from '../../server/logger.js';
+import { Socket } from 'socket.io';
 
 const logger = loggerFactory(import.meta);
 
-const CoreWsEmit = (channel = '', client = {}, payload = {}) => {
-  try {
-    if (client && client.emit) client.emit(channel, JSON.stringify(payload));
-    else logger.error('Invalid client', { channel, client, payload });
-  } catch (error) {
-    logger.error(error, { channel, client, payload, stack: error.stack });
+/**
+ * @class
+ * @alias CoreWsEmitter
+ * @memberof CoreWsEmitter
+ * @classdesc Provides a static utility method for safely emitting messages over a WebSocket connection.
+ */
+class CoreWsEmitter {
+  /**
+   * Emits a payload to a specific client over a given channel.
+   * The payload is automatically JSON stringified.
+   *
+   * @static
+   * @param {string} [channel=''] - The name of the channel/event to emit on.
+   * @param {Socket | Object} [client={}] - The Socket.IO client/socket object. Must have an `emit` method.
+   * @param {Object} [payload={}] - The data object to send.
+   * @returns {void}
+   */
+  static emit(channel = '', client = {}, payload = {}) {
+    try {
+      if (client && typeof client.emit === 'function') {
+        client.emit(channel, JSON.stringify(payload));
+      } else {
+        logger.error('Invalid client: Cannot emit message.', { channel, client, payload });
+      }
+    } catch (error) {
+      logger.error(error, { channel, client, payload, stack: error.stack });
+    }
   }
-};
+}
+
+/**
+ * Backward compatibility export for the `emit` function.
+ * @memberof CoreWsEmitter
+ * @function CoreWsEmit
+ * @param {string} [channel=''] - The name of the channel/event to emit on.
+ * @param {Socket | Object} [client={}] - The Socket.IO client/socket object.
+ * @param {Object} [payload={}] - The data object to send.
+ * @returns {void}
+ */
+const CoreWsEmit = CoreWsEmitter.emit;
 
-export { CoreWsEmit };
+export { CoreWsEmitter, CoreWsEmit };

package/src/ws/core/core.ws.server.js

@@ -1,24 +1,76 @@
+/**
+ * Module for creating and initializing the main WebSocket server instance.
+ * @module ws/core.ws.server
+ * @namespace CoreWsServer
+ */
+
 'use strict';
 
-import { IoServer } from '../IoServer.js';
+import { IoServerClass } from '../IoServer.js';
 import { CoreWsConnection } from './core.ws.connection.js';
 import { CoreWsChatManagement } from './management/core.ws.chat.js';
 import { CoreWsMailerManagement } from './management/core.ws.mailer.js';
 import { CoreWsStreamManagement } from './management/core.ws.stream.js';
+import http from 'http'; // Added for JSDoc type hinting
 
 // https://socket.io/docs/v3/
 
-const createIoServer = async (httpServer, options) => {
-  const { host, path } = options;
-  const wsManagementId = `${host}${path}`;
+/**
+ * @class
+ * @alias CoreWsServerClass
+ * @memberof CoreWsServer
+ * @classdesc Manages the creation and initialization of the main WebSocket server,
+ * including setting up the management instances for all channels.
+ */
+class CoreWsServerClass {
+  /**
+   * Initializes channel management instances and creates the Socket.IO server.
+   *
+   * @static
+   * @async
+   * @param {http.Server} httpServer - The HTTP server instance to attach the WebSocket server to.
+   * @param {Object} options - Configuration options for the WebSocket server.
+   * @param {string} options.host - The host address.
+   * @param {string} options.path - The base path for the API.
+   * @returns {Promise<Object>} The result object from IoServer creation.
+   */
+  static async create(httpServer, options) {
+    const { host, path } = options;
+    if (!host || !path) {
+      throw new Error('Host and path must be provided in server options.');
+    }
+
+    // Create a unique identifier for this server instance's management context
+    const wsManagementId = `${host}${path}`;
+
+    // Initialize/Retrieve singleton management instances for all channels
+    CoreWsChatManagement.instance(wsManagementId);
+    CoreWsMailerManagement.instance(wsManagementId);
+    CoreWsStreamManagement.instance(wsManagementId);
 
-  CoreWsChatManagement.instance(wsManagementId);
-  CoreWsMailerManagement.instance(wsManagementId);
-  CoreWsStreamManagement.instance(wsManagementId);
+    // Use the IoServerClass factory to create the server, passing the connection handler
+    return IoServerClass.create(httpServer, options, (socket) => CoreWsConnection(socket, wsManagementId));
+  }
+}
 
-  return IoServer(httpServer, options, (socket) => CoreWsConnection(socket, wsManagementId));
-};
+/**
+ * Backward compatibility export for the server creation function.
+ * @memberof CoreWsServer
+ * @function createIoServer
+ * @param {http.Server} httpServer - The HTTP server instance.
+ * @param {Object} options - Configuration options.
+ * @returns {Promise<Object>} The server creation result.
+ */
+const createIoServer = CoreWsServerClass.create;
 
+/**
+ * Backward compatibility alias.
+ * @memberof CoreWsServer
+ * @function CoreWsServer
+ * @param {import('http').Server} httpServer - The HTTP server instance.
+ * @param {Object} options - Configuration options.
+ * @returns {Promise<Object>} The server creation result.
+ */
 const CoreWsServer = createIoServer;
 
-export { createIoServer, CoreWsServer };
+export { CoreWsServerClass, createIoServer, CoreWsServer };