underpost 3.2.9 → 3.2.11

package/src/ws/IoInterface.js

@@ -46,9 +46,9 @@ class IoChannel {
   constructor(IoInterface) {
     this.#IoInterface = {
       channel: '',
-      connection: async (socket = {}, client = {}, wsManagementId = '') => {},
-      controller: async (socket = {}, client = {}, payload = {}, wsManagementId = '', args = []) => {},
-      disconnect: async (socket = {}, client = {}, reason = '', wsManagementId = '') => {},
+      connection: async (socket = {}, client = {}, hostKeyContext = '') => { },
+      controller: async (socket = {}, client = {}, payload = {}, hostKeyContext = '', args = []) => { },
+      disconnect: async (socket = {}, client = {}, reason = '', hostKeyContext = '') => { },
       stream: false,
       ...IoInterface,
     };
@@ -68,18 +68,18 @@ class IoChannel {
    * 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.
+   * @param {string} hostKeyContext - Unique identifier for the WebSocket management context.
    * @returns {Promise<void>}
    */
-  async connection(socket, wsManagementId) {
+  async connection(socket, hostKeyContext) {
     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);
+      socket.on(this.channel, (...args) => this.controller(socket, args, hostKeyContext));
+      await this.#IoInterface.connection(socket, this.client, hostKeyContext);
       logger.debug(`Socket ${socket.id} connected to channel ${this.channel}`);
     } catch (error) {
-      logger.error(error, { channel: this.channel, wsManagementId, stack: error.stack });
+      logger.error(error, { channel: this.channel, hostKeyContext, stack: error.stack });
     }
   }
 
@@ -89,10 +89,10 @@ class IoChannel {
    * @method
    * @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.
+   * @param {string} hostKeyContext - Unique identifier for the WebSocket management context.
    * @returns {Promise<void>}
    */
-  async controller(socket, args, wsManagementId) {
+  async controller(socket, args, hostKeyContext) {
     try {
       if (!args || args.length === 0) {
         logger.warn(`No arguments received for channel: ${this.channel}`, { socketId: socket.id });
@@ -101,9 +101,9 @@ class IoChannel {
       // 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);
+      await this.#IoInterface.controller(socket, this.client, payload, hostKeyContext, args);
     } catch (error) {
-      logger.error(error, { channel: this.channel, wsManagementId, socketId: socket.id, args, stack: error.stack });
+      logger.error(error, { channel: this.channel, hostKeyContext, socketId: socket.id, args, stack: error.stack });
     }
   }
 
@@ -112,16 +112,16 @@ class IoChannel {
    *
    * @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.
+   * @param {string} hostKeyContext - Unique identifier for the WebSocket management context.
    * @returns {Promise<void>}
    */
-  async disconnect(socket, reason, wsManagementId) {
+  async disconnect(socket, reason, hostKeyContext) {
     try {
-      await this.#IoInterface.disconnect(socket, this.client, reason, wsManagementId);
+      await this.#IoInterface.disconnect(socket, this.client, reason, hostKeyContext);
       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 });
+      logger.error(error, { channel: this.channel, hostKeyContext, reason, socketId: socket.id, stack: error.stack });
     }
   }
 }

package/src/ws/core/channels/core.ws.chat.js

@@ -12,13 +12,13 @@ import { CoreWsEmitter } from '../core.ws.emit.js';
  * Broadcasts incoming messages to all other connected sockets.
  */
 class CoreWsChatChannel {
-  /** @type {Object.<string, Object>} Per-instance state keyed by wsManagementId. */
+  /** @type {Object.<string, Object>} Per-instance state keyed by hostKeyContext. */
   static #state = {};
 
   /** @type {IoChannel} */
   static #io = new IoChannel({
     channel: 'chat',
-    controller(socket, client, payload, wsManagementId) {
+    controller(socket, client, payload, hostKeyContext) {
       for (const socketId of Object.keys(client)) {
         if (socketId !== socket.id) {
           CoreWsEmitter.emit('chat', client[socketId], { id: socket.id, ...payload });
@@ -39,29 +39,29 @@ class CoreWsChatChannel {
 
   /**
    * Initializes state for a server instance.
-   * @param {string} wsManagementId - Unique server context ID.
+   * @param {string} hostKeyContext - Unique server context ID.
    */
-  static init(wsManagementId) {
-    this.#state[wsManagementId] = {};
+  static init(hostKeyContext) {
+    this.#state[hostKeyContext] = {};
   }
 
   /**
    * Registers a socket connection.
    * @param {import('socket.io').Socket} socket
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static connection(socket, wsManagementId) {
-    return this.#io.connection(socket, wsManagementId);
+  static connection(socket, hostKeyContext) {
+    return this.#io.connection(socket, hostKeyContext);
   }
 
   /**
    * Handles socket disconnection.
    * @param {import('socket.io').Socket} socket
    * @param {string} reason
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static disconnect(socket, reason, wsManagementId) {
-    return this.#io.disconnect(socket, reason, wsManagementId);
+  static disconnect(socket, reason, hostKeyContext) {
+    return this.#io.disconnect(socket, reason, hostKeyContext);
   }
 }
 

package/src/ws/core/channels/core.ws.mailer.js

@@ -12,29 +12,29 @@ import { IoChannel } from '../../IoInterface.js';
  * Handles register/unregister messages and cleanup on disconnect.
  */
 class CoreWsMailerChannel {
-  /** @type {Object.<string, Object.<string, { model: { user: Object } }>>} Socket data keyed by `[wsManagementId][socketId]`. */
+  /** @type {Object.<string, Object.<string, { model: { user: Object } }>>} Socket data keyed by `[hostKeyContext][socketId]`. */
   static #data = {};
 
-  /** @type {Object.<string, Object.<string, string>>} Reverse index: `[wsManagementId][userId]` → socketId. */
+  /** @type {Object.<string, Object.<string, string>>} Reverse index: `[hostKeyContext][userId]` → socketId. */
   static #userIndex = {};
 
   /** @type {IoChannel} */
   static #io = new IoChannel({
     channel: 'mailer',
-    controller(socket, client, payload, wsManagementId) {
+    controller(socket, client, payload, hostKeyContext) {
       switch (payload.status) {
         case 'register-user':
-          CoreWsMailerChannel.setUser(wsManagementId, socket.id, payload.user);
+          CoreWsMailerChannel.setUser(hostKeyContext, socket.id, payload.user);
           break;
         case 'unregister-user':
-          CoreWsMailerChannel.removeSocket(wsManagementId, socket.id);
+          CoreWsMailerChannel.removeSocket(hostKeyContext, socket.id);
           break;
         default:
           break;
       }
     },
-    disconnect(socket, client, reason, wsManagementId) {
-      CoreWsMailerChannel.removeSocket(wsManagementId, socket.id);
+    disconnect(socket, client, reason, hostKeyContext) {
+      CoreWsMailerChannel.removeSocket(hostKeyContext, socket.id);
     },
   });
 
@@ -50,66 +50,66 @@ class CoreWsMailerChannel {
 
   /**
    * Initializes state for a server instance.
-   * @param {string} wsManagementId - Unique server context ID (`${host}${path}`).
+   * @param {string} hostKeyContext - Unique server context ID (`${host}${path}`).
    */
-  static init(wsManagementId) {
-    this.#data[wsManagementId] = {};
-    this.#userIndex[wsManagementId] = {};
+  static init(hostKeyContext) {
+    this.#data[hostKeyContext] = {};
+    this.#userIndex[hostKeyContext] = {};
   }
 
   /**
    * Registers a socket connection.
    * @param {import('socket.io').Socket} socket
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static connection(socket, wsManagementId) {
-    return this.#io.connection(socket, wsManagementId);
+  static connection(socket, hostKeyContext) {
+    return this.#io.connection(socket, hostKeyContext);
   }
 
   /**
    * Handles socket disconnection.
    * @param {import('socket.io').Socket} socket
    * @param {string} reason
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static disconnect(socket, reason, wsManagementId) {
-    return this.#io.disconnect(socket, reason, wsManagementId);
+  static disconnect(socket, reason, hostKeyContext) {
+    return this.#io.disconnect(socket, reason, hostKeyContext);
   }
 
   /**
    * Registers a user↔socket mapping.
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    * @param {string} socketId
    * @param {Object} user - User data with `_id` property.
    */
-  static setUser(wsManagementId, socketId, user) {
-    this.#data[wsManagementId][socketId] = { model: { user } };
+  static setUser(hostKeyContext, socketId, user) {
+    this.#data[hostKeyContext][socketId] = { model: { user } };
     if (user?._id) {
-      this.#userIndex[wsManagementId][user._id.toString()] = socketId;
+      this.#userIndex[hostKeyContext][user._id.toString()] = socketId;
     }
   }
 
   /**
    * Removes a socket entry and its reverse user index.
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    * @param {string} socketId
    */
-  static removeSocket(wsManagementId, socketId) {
-    const entry = this.#data[wsManagementId]?.[socketId];
+  static removeSocket(hostKeyContext, socketId) {
+    const entry = this.#data[hostKeyContext]?.[socketId];
     if (entry?.model?.user?._id) {
-      delete this.#userIndex[wsManagementId][entry.model.user._id.toString()];
+      delete this.#userIndex[hostKeyContext][entry.model.user._id.toString()];
     }
-    delete this.#data[wsManagementId]?.[socketId];
+    delete this.#data[hostKeyContext]?.[socketId];
   }
 
   /**
    * Finds the socket ID for a user (O(1) reverse index lookup).
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    * @param {string} userId - The user `_id`.
    * @returns {string|undefined} Socket ID, or `undefined` if not connected.
    */
-  static getUserWsId(wsManagementId, userId) {
-    return this.#userIndex[wsManagementId]?.[userId];
+  static getUserWsId(hostKeyContext, userId) {
+    return this.#userIndex[hostKeyContext]?.[userId];
   }
 }
 

package/src/ws/core/channels/core.ws.stream.js

@@ -11,41 +11,41 @@ import { IoChannel } from '../../IoInterface.js';
  * and broadcast connection/disconnection events to other room members.
  */
 class CoreWsStreamChannel {
-  /** @type {Object.<string, Object.<string, Array>>} Per-socket room/user args keyed by `[wsManagementId][socketId]`. */
+  /** @type {Object.<string, Object.<string, Array>>} Per-socket room/user args keyed by `[hostKeyContext][socketId]`. */
   static #state = {};
 
   /** @type {IoChannel} */
   static #io = new IoChannel({
     channel: 'stream',
     stream: true,
-    controller(socket, client, payload, wsManagementId, args) {
+    controller(socket, client, payload, hostKeyContext, args) {
       const [roomId, userId] = args;
 
       // Collect existing users in the room before registering the new one
       const existingUsers = [];
-      for (const entry of Object.values(CoreWsStreamChannel.#state[wsManagementId])) {
+      for (const entry of Object.values(CoreWsStreamChannel.#state[hostKeyContext])) {
         if (entry[0] === roomId && entry[1]) existingUsers.push(entry[1]);
       }
 
-      CoreWsStreamChannel.#state[wsManagementId][socket.id] = args;
+      CoreWsStreamChannel.#state[hostKeyContext][socket.id] = args;
       socket.join(roomId);
       socket.to(roomId).emit('stream-user-connected', userId);
 
       // Tell the joining user about everyone already in the room
       if (existingUsers.length > 0) socket.emit('stream-existing-users', existingUsers);
     },
-    connection(socket, client, wsManagementId) {
-      CoreWsStreamChannel.#state[wsManagementId][socket.id] = [];
+    connection(socket, client, hostKeyContext) {
+      CoreWsStreamChannel.#state[hostKeyContext][socket.id] = [];
     },
-    disconnect(socket, client, reason, wsManagementId) {
-      const entry = CoreWsStreamChannel.#state[wsManagementId]?.[socket.id];
+    disconnect(socket, client, reason, hostKeyContext) {
+      const entry = CoreWsStreamChannel.#state[hostKeyContext]?.[socket.id];
       if (!entry || entry.length === 0) {
-        if (CoreWsStreamChannel.#state[wsManagementId]) delete CoreWsStreamChannel.#state[wsManagementId][socket.id];
+        if (CoreWsStreamChannel.#state[hostKeyContext]) delete CoreWsStreamChannel.#state[hostKeyContext][socket.id];
         return;
       }
       const [roomId, userId] = entry;
       socket.to(roomId).emit('stream-user-disconnected', userId);
-      delete CoreWsStreamChannel.#state[wsManagementId][socket.id];
+      delete CoreWsStreamChannel.#state[hostKeyContext][socket.id];
     },
   });
 
@@ -61,29 +61,29 @@ class CoreWsStreamChannel {
 
   /**
    * Initializes state for a server instance.
-   * @param {string} wsManagementId - Unique server context ID (`${host}${path}`).
+   * @param {string} hostKeyContext - Unique server context ID (`${host}${path}`).
    */
-  static init(wsManagementId) {
-    this.#state[wsManagementId] = {};
+  static init(hostKeyContext) {
+    this.#state[hostKeyContext] = {};
   }
 
   /**
    * Registers a socket connection.
    * @param {import('socket.io').Socket} socket
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static connection(socket, wsManagementId) {
-    return this.#io.connection(socket, wsManagementId);
+  static connection(socket, hostKeyContext) {
+    return this.#io.connection(socket, hostKeyContext);
   }
 
   /**
    * Handles socket disconnection.
    * @param {import('socket.io').Socket} socket
    * @param {string} reason
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static disconnect(socket, reason, wsManagementId) {
-    return this.#io.disconnect(socket, reason, wsManagementId);
+  static disconnect(socket, reason, hostKeyContext) {
+    return this.#io.disconnect(socket, reason, hostKeyContext);
   }
 }
 

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

@@ -19,21 +19,21 @@ class CoreWsConnectionHandler {
   /**
    * Handles a new WebSocket connection.
    * @param {import('socket.io').Socket} socket
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static handle(socket, wsManagementId) {
+  static handle(socket, hostKeyContext) {
     logger.info(`New connection established. Socket ID: ${socket.id}`);
 
-    CoreWsChatChannel.connection(socket, wsManagementId);
-    CoreWsMailerChannel.connection(socket, wsManagementId);
-    CoreWsStreamChannel.connection(socket, wsManagementId);
+    CoreWsChatChannel.connection(socket, hostKeyContext);
+    CoreWsMailerChannel.connection(socket, hostKeyContext);
+    CoreWsStreamChannel.connection(socket, hostKeyContext);
 
     socket.on('disconnect', (reason) => {
       logger.info(`Connection disconnected. Socket ID: ${socket.id}, reason: ${reason}`);
 
-      CoreWsChatChannel.disconnect(socket, reason, wsManagementId);
-      CoreWsMailerChannel.disconnect(socket, reason, wsManagementId);
-      CoreWsStreamChannel.disconnect(socket, reason, wsManagementId);
+      CoreWsChatChannel.disconnect(socket, reason, hostKeyContext);
+      CoreWsMailerChannel.disconnect(socket, reason, hostKeyContext);
+      CoreWsStreamChannel.disconnect(socket, reason, hostKeyContext);
     });
   }
 }

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

@@ -10,6 +10,7 @@ import { CoreWsConnectionHandler } from './core.ws.connection.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 { resolveHostKeyContext } from '../../server/conf.js';
 
 /**
  * @class CoreWsServer
@@ -27,13 +28,13 @@ class CoreWsServer {
    */
   static create(httpServer, options) {
     const { host, path } = options;
-    const wsManagementId = `${host}${path}`;
+    const hostKeyContext = resolveHostKeyContext({ host, path });
 
-    CoreWsChatChannel.init(wsManagementId);
-    CoreWsMailerChannel.init(wsManagementId);
-    CoreWsStreamChannel.init(wsManagementId);
+    CoreWsChatChannel.init(hostKeyContext);
+    CoreWsMailerChannel.init(hostKeyContext);
+    CoreWsStreamChannel.init(hostKeyContext);
 
-    return IoServer.create(httpServer, options, (socket) => CoreWsConnectionHandler.handle(socket, wsManagementId));
+    return IoServer.create(httpServer, options, (socket) => CoreWsConnectionHandler.handle(socket, hostKeyContext));
   }
 }
 

package/src/ws/default/channels/default.ws.main.js

@@ -10,7 +10,7 @@ import { IoChannel } from '../../IoInterface.js';
  * @classdesc Provides a no-op main channel for the default WebSocket server.
  */
 class DefaultWsMainChannel {
-  /** @type {Object.<string, Object>} Per-instance state keyed by wsManagementId. */
+  /** @type {Object.<string, Object>} Per-instance state keyed by hostKeyContext. */
   static #state = {};
 
   /** @type {IoChannel} */
@@ -28,29 +28,29 @@ class DefaultWsMainChannel {
 
   /**
    * Initializes state for a server instance.
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static init(wsManagementId) {
-    this.#state[wsManagementId] = {};
+  static init(hostKeyContext) {
+    this.#state[hostKeyContext] = {};
   }
 
   /**
    * Registers a socket connection.
    * @param {import('socket.io').Socket} socket
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static connection(socket, wsManagementId) {
-    return this.#io.connection(socket, wsManagementId);
+  static connection(socket, hostKeyContext) {
+    return this.#io.connection(socket, hostKeyContext);
   }
 
   /**
    * Handles socket disconnection.
    * @param {import('socket.io').Socket} socket
    * @param {string} reason
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static disconnect(socket, reason, wsManagementId) {
-    return this.#io.disconnect(socket, reason, wsManagementId);
+  static disconnect(socket, reason, hostKeyContext) {
+    return this.#io.disconnect(socket, reason, hostKeyContext);
   }
 }
 

package/src/ws/default/default.ws.connection.js

@@ -17,17 +17,17 @@ class DefaultWsConnectionHandler {
   /**
    * Handles a new WebSocket connection.
    * @param {import('socket.io').Socket} socket
-   * @param {string} wsManagementId
+   * @param {string} hostKeyContext
    */
-  static handle(socket, wsManagementId) {
+  static handle(socket, hostKeyContext) {
     logger.info(`DefaultWsConnection ${socket.id}`);
 
-    DefaultWsMainChannel.connection(socket, wsManagementId);
+    DefaultWsMainChannel.connection(socket, hostKeyContext);
 
     socket.on('disconnect', (reason) => {
       logger.info(`DefaultWsConnection ${socket.id} due to reason: ${reason}`);
 
-      DefaultWsMainChannel.disconnect(socket, reason, wsManagementId);
+      DefaultWsMainChannel.disconnect(socket, reason, hostKeyContext);
     });
   }
 }

package/src/ws/default/default.ws.server.js

@@ -8,6 +8,7 @@
 import { IoServer } from '../IoServer.js';
 import { DefaultWsConnectionHandler } from './default.ws.connection.js';
 import { DefaultWsMainChannel } from './channels/default.ws.main.js';
+import { resolveHostKeyContext } from '../../server/conf.js';
 
 /**
  * @class DefaultWsServer
@@ -24,11 +25,11 @@ class DefaultWsServer {
    */
   static create(httpServer, options) {
     const { host, path } = options;
-    const wsManagementId = `${host}${path}`;
+    const hostKeyContext = resolveHostKeyContext({ host, path });
 
-    DefaultWsMainChannel.init(wsManagementId);
+    DefaultWsMainChannel.init(hostKeyContext);
 
-    return IoServer.create(httpServer, options, (socket) => DefaultWsConnectionHandler.handle(socket, wsManagementId));
+    return IoServer.create(httpServer, options, (socket) => DefaultWsConnectionHandler.handle(socket, hostKeyContext));
   }
 }