cyberia 3.2.5 → 3.2.12

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/tsconfig.docs.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "maxNodeModuleJsDepth": 0,
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.js"],
+  "exclude": ["node_modules"]
+}

package/typedoc.dd-cyberia.json

@@ -0,0 +1,29 @@
+{
+  "name": "CYBERIA Online",
+  "entryPoints": [
+    "./src/server",
+    "./src/api",
+    "./src/cli",
+    "./src/db",
+    "./src/ws",
+    "./src/grpc",
+    "./src/mailer",
+    "./src/runtime"
+  ],
+  "entryPointStrategy": "expand",
+  "exclude": ["**/node_modules/**", "**/docs/**", "**/client/**", "**/hardhat/**"],
+  "out": "./public/www.cyberiaonline.com/docs/",
+  "readme": "./src/client/public/cyberia-docs/ARCHITECTURE.md",
+  "tsconfig": "./tsconfig.docs.json",
+  "skipErrorChecking": true,
+  "logLevel": "Error",
+  "includeVersion": true,
+  "hideGenerator": true,
+  "searchInComments": true,
+  "navigation": {
+    "includeCategories": true,
+    "includeGroups": true
+  },
+  "categorizeByGroup": true,
+  "sort": ["source-order"]
+}

package/typedoc.json

@@ -0,0 +1,29 @@
+{
+  "name": "CYBERIA Online",
+  "entryPoints": [
+    "./src/server",
+    "./src/api",
+    "./src/cli",
+    "./src/db",
+    "./src/ws",
+    "./src/grpc",
+    "./src/mailer",
+    "./src/runtime"
+  ],
+  "entryPointStrategy": "expand",
+  "exclude": ["**/node_modules/**", "**/docs/**", "**/client/**", "**/hardhat/**"],
+  "out": "./public/www.cyberiaonline.com/docs/",
+  "readme": "./src/client/public/cyberia-docs/ARCHITECTURE.md",
+  "tsconfig": "./tsconfig.docs.json",
+  "skipErrorChecking": true,
+  "logLevel": "Error",
+  "includeVersion": true,
+  "hideGenerator": true,
+  "searchInComments": true,
+  "navigation": {
+    "includeCategories": true,
+    "includeGroups": true
+  },
+  "categorizeByGroup": true,
+  "sort": ["source-order"]
+}