underpost 2.8.883 → 2.8.885

package/src/ws/IoInterface.js

@@ -1,45 +1,138 @@
+/**
+ * Module for creating and managing WebSocket channels.
+ * @module src/ws/IoInterface.js
+ * @namespace SocketIoInterface
+ */
+
 import { loggerFactory } from '../server/logger.js';
+import { Socket } from 'socket.io';
 
 const logger = loggerFactory(import.meta);
 
-const IoCreateChannel = (
-  IoInterface = {
-    channel: '',
-    connection: (socket = {}, client = {}, wsManagementId = '') => {},
-    controller: (socket = {}, client = {}, args = '', wsManagementId = '') => {},
-    disconnect: (socket = {}, client = {}, reason = '', wsManagementId = '') => {},
-    stream: false,
-  },
-) => {
-  return {
-    channel: IoInterface.channel,
-    client: {},
-    connection: async function (socket, wsManagementId) {
-      try {
-        this.client[socket.id] = socket;
-        socket.on(IoInterface.channel, (...args) => this.controller(socket, args, wsManagementId));
-        await IoInterface.connection(socket, this.client, wsManagementId);
-      } catch (error) {
-        logger.error(error, { channel: IoInterface.channel, wsManagementId, stack: error.stack });
-      }
-    },
-    controller: async function (socket, args, wsManagementId) {
-      try {
-        const payload = IoInterface.stream ? args[0] : JSON.parse(args[0]);
-        await IoInterface.controller(socket, this.client, payload, wsManagementId, args);
-      } catch (error) {
-        logger.error(error, { channel: IoInterface.channel, wsManagementId, args, stack: error.stack });
-      }
-    },
-    disconnect: async function (socket, reason, wsManagementId) {
-      try {
-        await IoInterface.disconnect(socket, this.client, reason, wsManagementId);
-        delete this.client[socket.id];
-      } catch (error) {
-        logger.error(error, { channel: IoInterface.channel, wsManagementId, reason, stack: error.stack });
+/**
+ * Defines the structure for a WebSocket channel's behavior functions.
+ * @typedef {Object} ChannelInterface
+ * @property {string} channel - The name of the channel.
+ * @property {function(Socket, Object.<string, Socket>, string): Promise<void>} [connection] - Handler on client connection.
+ * @property {function(Socket, Object.<string, Socket>, any, string, any[]): Promise<void>} [controller] - Handler for incoming channel messages.
+ * @property {function(Socket, Object.<string, Socket>, string, string): Promise<void>} [disconnect] - Handler on client disconnection.
+ * @property {boolean} [stream=false] - Whether the channel should treat the message as a raw stream (no JSON parsing).
+ */
+
+/**
+ * @class
+ * @alias IoChannel
+ * @memberof SocketIoInterface
+ * @classdesc Manages the logic, client map, and event listeners for a specific WebSocket channel,
+ * ensuring robust message handling and lifecycle management.
+ */
+class IoChannel {
+  /**
+   * @private
+   * @type {ChannelInterface}
+   */
+  #IoInterface;
+
+  /**
+   * Map of connected sockets for this channel, keyed by socket ID.
+   * @type {Object.<string, Socket>}
+   */
+  client = {};
+
+  /**
+   * Creates an instance of IoChannel.
+   * @param {ChannelInterface} IoInterface - The interface object defining the channel's behavior.
+   */
+  constructor(IoInterface) {
+    this.#IoInterface = {
+      channel: '',
+      connection: async (socket = {}, client = {}, wsManagementId = '') => {},
+      controller: async (socket = {}, client = {}, payload = {}, wsManagementId = '', args = []) => {},
+      disconnect: async (socket = {}, client = {}, reason = '', wsManagementId = '') => {},
+      stream: false,
+      ...IoInterface,
+    };
+    logger.debug(`Channel instance created for: ${this.channel}`);
+  }
+
+  /**
+   * Gets the name of the channel.
+   * @returns {string} The channel name.
+   */
+  get channel() {
+    return this.#IoInterface.channel;
+  }
+
+  /**
+   * Handles a new socket connection for this channel.
+   * Sets up the listener for the channel message.
+   *
+   * @param {Socket} socket - The Socket.IO socket object.
+   * @param {string} wsManagementId - Unique identifier for the WebSocket management context.
+   * @returns {Promise<void>}
+   */
+  async connection(socket, wsManagementId) {
+    try {
+      this.client[socket.id] = socket;
+      // Use bind/arrow function to maintain 'this' context for the controller
+      socket.on(this.channel, (...args) => this.controller(socket, args, wsManagementId));
+      await this.#IoInterface.connection(socket, this.client, wsManagementId);
+      logger.debug(`Socket ${socket.id} connected to channel ${this.channel}`);
+    } catch (error) {
+      logger.error(error, { channel: this.channel, wsManagementId, stack: error.stack });
+    }
+  }
+
+  /**
+   * Handles incoming messages on the channel.
+   *
+   * @private
+   * @param {Socket} socket - The Socket.IO socket object.
+   * @param {any[]} args - The raw arguments received from the socket event.
+   * @param {string} wsManagementId - Unique identifier for the WebSocket management context.
+   * @returns {Promise<void>}
+   */
+  async controller(socket, args, wsManagementId) {
+    try {
+      if (!args || args.length === 0) {
+        logger.warn(`No arguments received for channel: ${this.channel}`, { socketId: socket.id });
+        return;
       }
-    },
-  };
-};
+      // Determine if JSON parsing is needed based on the stream flag
+      const payload = this.#IoInterface.stream ? args[0] : JSON.parse(args[0]);
+
+      await this.#IoInterface.controller(socket, this.client, payload, wsManagementId, args);
+    } catch (error) {
+      logger.error(error, { channel: this.channel, wsManagementId, socketId: socket.id, args, stack: error.stack });
+    }
+  }
+
+  /**
+   * Handles a socket disconnection for this channel.
+   *
+   * @param {Socket} socket - The Socket.IO socket object.
+   * @param {string} reason - The reason for disconnection (e.g., 'client namespace disconnect').
+   * @param {string} wsManagementId - Unique identifier for the WebSocket management context.
+   * @returns {Promise<void>}
+   */
+  async disconnect(socket, reason, wsManagementId) {
+    try {
+      await this.#IoInterface.disconnect(socket, this.client, reason, wsManagementId);
+      delete this.client[socket.id];
+      logger.debug(`Socket ${socket.id} disconnected from channel ${this.channel}. Reason: ${reason}`);
+    } catch (error) {
+      logger.error(error, { channel: this.channel, wsManagementId, reason, socketId: socket.id, stack: error.stack });
+    }
+  }
+}
+
+/**
+ * Backward compatibility function to create a new channel instance.
+ * @memberof SocketIoInterface
+ * @function IoCreateChannel
+ * @param {ChannelInterface} IoInterface - The interface object defining the channel's behavior.
+ * @returns {IoChannel} An instance of the IoChannel class.
+ */
+const IoCreateChannel = (IoInterface) => new IoChannel(IoInterface);
 
-export { IoCreateChannel };
+export { IoChannel, IoCreateChannel };

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 };

package/src/runtime/nginx/Nginx.js

@@ -1,3 +0,0 @@
-const Nginx = {};
-
-export { Nginx };