underpost 3.2.8 → 3.2.10

package/src/server/start.js

@@ -52,7 +52,7 @@ class UnderpostStartUp {
      * @param {Function} logic - The logic to execute when the server is listening.
      * @returns {Object} An object with a listen method.
      */
-    listenServerFactory: (logic = async () => {}) => {
+    listenServerFactory: (logic = async () => { }) => {
       return {
         listen: async (...args) => {
           const msDelta = 1000;
@@ -133,11 +133,19 @@ class UnderpostStartUp {
      * @param {boolean} options.underpostQuicklyInstall - Whether to use underpost quickly install.
      * @param {boolean} options.skipPullBase - Whether to skip pulling the base code.
      * @param {boolean} options.skipFullBuild - Whether to skip building the full client bundle.
+     * @param {boolean} options.pullBundle - When true, download pre-built client bundle from Cloudinary via pull-bundle before starting.
      */
     async callback(
       deployId = 'dd-default',
       env = 'development',
-      options = { build: false, run: false, underpostQuicklyInstall: false, skipPullBase: false, skipFullBuild: false },
+      options = {
+        build: false,
+        run: false,
+        underpostQuicklyInstall: false,
+        skipPullBase: false,
+        skipFullBuild: false,
+        pullBundle: false,
+      },
     ) {
       Underpost.env.set('container-status', `${deployId}-${env}-build-deployment`);
       if (options.build === true) await Underpost.start.build(deployId, env, options);
@@ -152,12 +160,14 @@ class UnderpostStartUp {
      * @param {boolean} options.skipPullBase - Whether to skip pulling the base code and use the current workspace code directly.
      * @param {boolean} options.underpostQuicklyInstall - Whether to use underpost quickly install.
      * @param {boolean} options.skipFullBuild - Whether to skip building the full client bundle.
+     * @param {boolean} options.pullBundle - When true, download pre-built client bundle from Cloudinary via pull-bundle (must be pushed first with push-bundle).
+     *   This flag is independent of skipFullBuild: it can be combined with skipFullBuild or used alone.
      * @memberof UnderpostStartUp
      */
     async build(
       deployId = 'dd-default',
       env = 'development',
-      options = { underpostQuicklyInstall: false, skipPullBase: false, skipFullBuild: false },
+      options = { underpostQuicklyInstall: false, skipPullBase: false, skipFullBuild: false, pullBundle: false },
     ) {
       const buildBasePath = `/home/dd`;
       const repoName = `engine-${deployId.split('-')[1]}`;
@@ -176,7 +186,8 @@ class UnderpostStartUp {
         for (const itcScript of itcScripts)
           if (itcScript.match(deployId)) shellExec(`node ./engine-private/itc-scripts/${itcScript}`);
       }
-      if (!options.skipFullBuild) shellExec(`node bin client ${deployId}`);
+      if (options.pullBundle === true) shellExec(`node bin run pull-bundle --deploy-id ${deployId}`);
+      else if (!options.skipFullBuild) shellExec(`node bin client ${deployId}`);
     },
     /**
      * Runs a deployment.
@@ -187,20 +198,28 @@ class UnderpostStartUp {
      */
     async run(deployId = 'dd-default', env = 'development', options = {}) {
       const runCmd = env === 'production' ? 'run prod:container' : 'run dev:container';
+      const makeDeployCallback = (cmd) => (code, out, msg) => {
+        if (code !== 0) {
+          logger.error(`Deployment process exited with code ${code}`, { cmd, msg });
+          Underpost.env.set('container-status', 'error');
+        }
+      };
       if (fs.existsSync(`./engine-private/replica`)) {
         const replicas = await fs.readdir(`./engine-private/replica`);
         for (const replica of replicas) {
           if (!replica.match(deployId)) continue;
           shellExec(`node bin env ${replica} ${env}`);
-          shellExec(`npm ${runCmd} ${replica}`, { async: true });
+          const replicaCmd = `npm ${runCmd} ${replica}`;
+          shellExec(replicaCmd, { async: true, callback: makeDeployCallback(replicaCmd) });
           await awaitDeployMonitor(true);
         }
       }
       shellExec(`node bin env ${deployId} ${env}`);
-      shellExec(`npm ${runCmd} ${deployId}`, { async: true });
+      const deployCmd = `npm ${runCmd} ${deployId}`;
+      shellExec(deployCmd, { async: true, callback: makeDeployCallback(deployCmd) });
       await awaitDeployMonitor(true);
       if (env === 'production' && Underpost.env.isInsideContainer()) Underpost.secret.globalSecretClean();
-      Underpost.env.set('container-status', `${deployId}-${env}-running-deployment`);
+      if (Underpost.env.get('container-status') !== 'error') Underpost.env.set('container-status', `${deployId}-${env}-running-deployment`);
     },
   };
 }

package/src/server/valkey.js

@@ -22,7 +22,7 @@ const logger = loggerFactory(import.meta);
 /** @type {Record<string, import('iovalkey').default>} */
 const ValkeyInstances = {};
 
-/** @type {Record<string, 'connected' | 'error'>} */
+/** @type {Record<string, 'connected' | 'reconnecting' | 'error'>} */
 const ValkeyStatus = {};
 
 /**
@@ -57,7 +57,10 @@ const createValkeyConnection = async (instance = {}, connectionOptions = {}) =>
   const client = new Valkey({
     port: connectionOptions.port ?? undefined,
     host: connectionOptions.host ?? undefined,
-    retryStrategy: (attempt) => (attempt === 1 ? undefined : 1000),
+    // Retry indefinitely with capped exponential backoff (1 s → 30 s)
+    retryStrategy: (attempt) => Math.min(attempt * 1000, 30000),
+    // Fail commands immediately when not connected; do NOT queue them
+    maxRetriesPerRequest: 0,
   });
 
   client.on('ready', () => {
@@ -68,6 +71,10 @@ const createValkeyConnection = async (instance = {}, connectionOptions = {}) =>
     ValkeyStatus[key] = 'error';
     logger.error('Valkey error', { err: err?.message, instance });
   });
+  client.on('reconnecting', () => {
+    ValkeyStatus[key] = 'reconnecting';
+    logger.warn('Valkey reconnecting...', { instance });
+  });
   client.on('end', () => {
     ValkeyStatus[key] = 'error';
     logger.warn('Valkey connection ended', { instance });

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

package/typedoc.json

@@ -1,6 +1,15 @@
 {
   "name": "Nexodev - ERP, CRM Development & Cloud DevOps Services",
-  "entryPoints": ["./src/server", "./src/api", "./src/db", "./src/ws", "./src/grpc", "./src/mailer", "./src/runtime"],
+  "entryPoints": [
+    "./src/server",
+    "./src/api",
+    "./src/cli",
+    "./src/db",
+    "./src/ws",
+    "./src/grpc",
+    "./src/mailer",
+    "./src/runtime"
+  ],
   "entryPointStrategy": "expand",
   "exclude": ["**/node_modules/**", "**/docs/**", "**/client/**"],
   "out": "./public/www.nexodev.org/docs/",