cyberia 3.1.3 → 3.2.5

package/src/server/start.js

@@ -163,10 +163,9 @@ class UnderpostStartUp {
         shellExec(`mkdir -p ${buildBasePath}/engine`);
         shellExec(`cd ${buildBasePath} && sudo cp -a ./${repoName}/. ./engine`);
         shellExec(`cd ${buildBasePath} && sudo rm -rf ./${repoName}`);
-        shellExec(`cd ${buildBasePath}/engine && underpost clone ${process.env.GITHUB_USERNAME}/${repoName}-private`);
-        shellExec(`cd ${buildBasePath}/engine && sudo mv ./${repoName}-private ./engine-private`);
       }
       shellCd(`${buildBasePath}/engine`);
+      Underpost.repo.privateEngineRepoFactory(deployId);
       shellExec(options?.underpostQuicklyInstall ? `underpost install` : `npm install`);
       shellExec(`node bin env ${deployId} ${env}`);
       if (fs.existsSync('./engine-private/itc-scripts')) {
@@ -197,6 +196,7 @@ class UnderpostStartUp {
       shellExec(`node bin env ${deployId} ${env}`);
       shellExec(`npm ${runCmd} ${deployId}`, { async: true });
       await awaitDeployMonitor(true);
+      if (env === 'production' && Underpost.env.isInsideContainer()) Underpost.secret.globalSecretClean();
       Underpost.env.set('container-status', `${deployId}-${env}-running-deployment`);
     },
   };

package/src/ws/IoInterface.js

@@ -126,13 +126,4 @@ class IoChannel {
   }
 }
 
-/**
- * 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 { IoChannel, IoCreateChannel };
+export { IoChannel };

package/src/ws/IoServer.js

@@ -1,7 +1,6 @@
 /**
  * Module for creating and managing WebSocket servers.
- * @module src/ws/IoServer
- * @namespace SocketIoServer
+ * @module ws/IoServer
  */
 
 'use strict';
@@ -9,33 +8,27 @@
 import { Server } from 'socket.io';
 import { loggerFactory } from '../server/logger.js';
 import Underpost from '../index.js';
-import http from 'http';
 
 const logger = loggerFactory(import.meta);
 
 /**
- * @class IoServerClass
- * @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 IoServer
+ * @classdesc Factory for creating and configuring Socket.IO server instances
+ * with CORS configuration and HTTP server attachment.
  */
-class IoServerClass {
+class IoServer {
   /**
    * 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`).
+   * @param {import('http').Server} httpServer - The HTTP server instance to attach to.
+   * @param {Object} options - Configuration options.
+   * @param {string[]} options.origins - Allowed CORS origins.
+   * @param {string} options.path - Base API path. Socket.IO path is appended automatically.
+   * @param {function(import('socket.io').Socket): void} connectionHandler - Handler for new connections.
+   * @returns {{ options: import('socket.io').ServerOptions, ioServer: import('socket.io').Server, meta: ImportMeta }}
    */
-  static create(httpServer, options = {}, ConnectionHandler = () => {}) {
+  static create(httpServer, options = {}, connectionHandler = () => {}) {
     logger.info('origins', options.origins);
     const wsOptions = {
       cors: {
@@ -55,12 +48,11 @@ class IoServerClass {
         ],
         credentials: true,
       },
-      // Ensure the path ends correctly, appending '/socket.io/'
       path: options.path !== '/' ? `${options.path}/socket.io/` : '/socket.io/',
     };
 
     const ioServerInstance = Underpost.start.listenServerFactory(() =>
-      new Server(httpServer, wsOptions).on('connection', ConnectionHandler),
+      new Server(httpServer, wsOptions).on('connection', connectionHandler),
     );
 
     logger.info('Socket.IO Server created and listening', { path: wsOptions.path });
@@ -73,15 +65,4 @@ class IoServerClass {
   }
 }
 
-/**
- * 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 };
+export { IoServer };

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

@@ -1,23 +1,68 @@
-import { loggerFactory } from '../../../server/logger.js';
-import { IoCreateChannel } from '../../IoInterface.js';
-import { CoreWsEmit } from '../core.ws.emit.js';
-
-const channel = 'chat';
-const logger = loggerFactory(import.meta);
-
-const CoreWsChatController = {
-  channel,
-  controller: function (socket, client, payload, wsManagementId) {
-    for (const socketId of Object.keys(client)) {
-      if (socketId !== socket.id) {
-        CoreWsEmit(channel, client[socketId], { id: socket.id, ...payload });
+/**
+ * Chat WebSocket channel — broadcasts messages to all connected sockets except the sender.
+ * @module ws/core/channels/core.ws.chat
+ */
+
+import { IoChannel } from '../../IoInterface.js';
+import { CoreWsEmitter } from '../core.ws.emit.js';
+
+/**
+ * @class CoreWsChatChannel
+ * @classdesc Manages the chat WebSocket channel with per-instance state.
+ * Broadcasts incoming messages to all other connected sockets.
+ */
+class CoreWsChatChannel {
+  /** @type {Object.<string, Object>} Per-instance state keyed by wsManagementId. */
+  static #state = {};
+
+  /** @type {IoChannel} */
+  static #io = new IoChannel({
+    channel: 'chat',
+    controller(socket, client, payload, wsManagementId) {
+      for (const socketId of Object.keys(client)) {
+        if (socketId !== socket.id) {
+          CoreWsEmitter.emit('chat', client[socketId], { id: socket.id, ...payload });
+        }
       }
-    }
-  },
-  connection: function (socket, client, wsManagementId) {},
-  disconnect: function (socket, client, reason, wsManagementId) {},
-};
+    },
+  });
+
+  /** @returns {Object.<string, import('socket.io').Socket>} Connected sockets map. */
+  static get client() {
+    return this.#io.client;
+  }
+
+  /** @returns {string} Channel name. */
+  static get channel() {
+    return this.#io.channel;
+  }
+
+  /**
+   * Initializes state for a server instance.
+   * @param {string} wsManagementId - Unique server context ID.
+   */
+  static init(wsManagementId) {
+    this.#state[wsManagementId] = {};
+  }
+
+  /**
+   * Registers a socket connection.
+   * @param {import('socket.io').Socket} socket
+   * @param {string} wsManagementId
+   */
+  static connection(socket, wsManagementId) {
+    return this.#io.connection(socket, wsManagementId);
+  }
 
-const CoreWsChatChannel = IoCreateChannel(CoreWsChatController);
+  /**
+   * Handles socket disconnection.
+   * @param {import('socket.io').Socket} socket
+   * @param {string} reason
+   * @param {string} wsManagementId
+   */
+  static disconnect(socket, reason, wsManagementId) {
+    return this.#io.disconnect(socket, reason, wsManagementId);
+  }
+}
 
-export { CoreWsChatChannel, CoreWsChatController };
+export { CoreWsChatChannel };

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

@@ -1,35 +1,116 @@
-import { loggerFactory } from '../../../server/logger.js';
-import { IoCreateChannel } from '../../IoInterface.js';
-import { CoreWsMailerManagement } from '../management/core.ws.mailer.js';
-
-const channel = 'mailer';
-const logger = loggerFactory(import.meta);
-
-const CoreWsMailerController = {
-  channel,
-  controller: function (socket, client, payload, wsManagementId) {
-    switch (payload.status) {
-      case 'register-user':
-        CoreWsMailerManagement.element[wsManagementId][socket.id] = {
-          model: {
-            user: payload.user,
-          },
-        };
-        break;
-      case 'unregister-user':
-        delete CoreWsMailerManagement.element[wsManagementId][socket.id];
-        break;
-
-      default:
-        break;
+/**
+ * Mailer WebSocket channel — manages user↔socket bidirectional mapping
+ * for targeted real-time pushes (e.g. email confirmation notifications).
+ * @module ws/core/channels/core.ws.mailer
+ */
+
+import { IoChannel } from '../../IoInterface.js';
+
+/**
+ * @class CoreWsMailerChannel
+ * @classdesc Manages the mailer WebSocket channel with O(1) user↔socket lookup.
+ * Handles register/unregister messages and cleanup on disconnect.
+ */
+class CoreWsMailerChannel {
+  /** @type {Object.<string, Object.<string, { model: { user: Object } }>>} Socket data keyed by `[wsManagementId][socketId]`. */
+  static #data = {};
+
+  /** @type {Object.<string, Object.<string, string>>} Reverse index: `[wsManagementId][userId]` → socketId. */
+  static #userIndex = {};
+
+  /** @type {IoChannel} */
+  static #io = new IoChannel({
+    channel: 'mailer',
+    controller(socket, client, payload, wsManagementId) {
+      switch (payload.status) {
+        case 'register-user':
+          CoreWsMailerChannel.setUser(wsManagementId, socket.id, payload.user);
+          break;
+        case 'unregister-user':
+          CoreWsMailerChannel.removeSocket(wsManagementId, socket.id);
+          break;
+        default:
+          break;
+      }
+    },
+    disconnect(socket, client, reason, wsManagementId) {
+      CoreWsMailerChannel.removeSocket(wsManagementId, socket.id);
+    },
+  });
+
+  /** @returns {Object.<string, import('socket.io').Socket>} Connected sockets map. */
+  static get client() {
+    return this.#io.client;
+  }
+
+  /** @returns {string} Channel name. */
+  static get channel() {
+    return this.#io.channel;
+  }
+
+  /**
+   * Initializes state for a server instance.
+   * @param {string} wsManagementId - Unique server context ID (`${host}${path}`).
+   */
+  static init(wsManagementId) {
+    this.#data[wsManagementId] = {};
+    this.#userIndex[wsManagementId] = {};
+  }
+
+  /**
+   * Registers a socket connection.
+   * @param {import('socket.io').Socket} socket
+   * @param {string} wsManagementId
+   */
+  static connection(socket, wsManagementId) {
+    return this.#io.connection(socket, wsManagementId);
+  }
+
+  /**
+   * Handles socket disconnection.
+   * @param {import('socket.io').Socket} socket
+   * @param {string} reason
+   * @param {string} wsManagementId
+   */
+  static disconnect(socket, reason, wsManagementId) {
+    return this.#io.disconnect(socket, reason, wsManagementId);
+  }
+
+  /**
+   * Registers a user↔socket mapping.
+   * @param {string} wsManagementId
+   * @param {string} socketId
+   * @param {Object} user - User data with `_id` property.
+   */
+  static setUser(wsManagementId, socketId, user) {
+    this.#data[wsManagementId][socketId] = { model: { user } };
+    if (user?._id) {
+      this.#userIndex[wsManagementId][user._id.toString()] = socketId;
+    }
+  }
+
+  /**
+   * Removes a socket entry and its reverse user index.
+   * @param {string} wsManagementId
+   * @param {string} socketId
+   */
+  static removeSocket(wsManagementId, socketId) {
+    const entry = this.#data[wsManagementId]?.[socketId];
+    if (entry?.model?.user?._id) {
+      delete this.#userIndex[wsManagementId][entry.model.user._id.toString()];
     }
-  },
-  connection: function (socket, client, wsManagementId) {},
-  disconnect: function (socket, client, reason, wsManagementId) {
-    delete CoreWsMailerManagement.element[wsManagementId][socket.id];
-  },
-};
+    delete this.#data[wsManagementId]?.[socketId];
+  }
 
-const CoreWsMailerChannel = IoCreateChannel(CoreWsMailerController);
+  /**
+   * Finds the socket ID for a user (O(1) reverse index lookup).
+   * @param {string} wsManagementId
+   * @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];
+  }
+}
 
-export { CoreWsMailerChannel, CoreWsMailerController };
+export { CoreWsMailerChannel };

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

@@ -1,31 +1,90 @@
-import { loggerFactory } from '../../../server/logger.js';
-import { IoCreateChannel } from '../../IoInterface.js';
-import { CoreWsStreamManagement } from '../management/core.ws.stream.js';
-
-const channel = 'stream';
-const logger = loggerFactory(import.meta);
-
-const CoreWsStreamController = {
-  channel,
-  stream: true,
-  controller: function (socket, client, payload, wsManagementId, args) {
-    const [roomId, userId] = args;
-    CoreWsStreamManagement.element[wsManagementId][socket.id] = args;
-
-    socket.join(roomId); // Join the room
-    socket.broadcast.emit(`${channel}-user-connected`, userId); // Tell everyone else in the room that we joined
-  },
-  connection: function (socket, client, wsManagementId) {
-    CoreWsStreamManagement.element[wsManagementId][socket.id] = [];
-  },
-  disconnect: function (socket, client, reason, wsManagementId) {
-    // Communicate the disconnection
-    const [roomId, userId] = CoreWsStreamManagement.element[wsManagementId][socket.id];
-    socket.broadcast.emit(`${channel}-user-disconnected`, userId);
-    delete CoreWsStreamManagement.element[wsManagementId][socket.id];
-  },
-};
-
-const CoreWsStreamChannel = IoCreateChannel(CoreWsStreamController);
-
-export { CoreWsStreamChannel, CoreWsStreamController };
+/**
+ * Stream WebSocket channel — manages per-socket room membership and user tracking.
+ * @module ws/core/channels/core.ws.stream
+ */
+
+import { IoChannel } from '../../IoInterface.js';
+
+/**
+ * @class CoreWsStreamChannel
+ * @classdesc Manages the stream WebSocket channel. Each socket can join a room
+ * 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]`. */
+  static #state = {};
+
+  /** @type {IoChannel} */
+  static #io = new IoChannel({
+    channel: 'stream',
+    stream: true,
+    controller(socket, client, payload, wsManagementId, 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])) {
+        if (entry[0] === roomId && entry[1]) existingUsers.push(entry[1]);
+      }
+
+      CoreWsStreamChannel.#state[wsManagementId][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] = [];
+    },
+    disconnect(socket, client, reason, wsManagementId) {
+      const entry = CoreWsStreamChannel.#state[wsManagementId]?.[socket.id];
+      if (!entry || entry.length === 0) {
+        if (CoreWsStreamChannel.#state[wsManagementId]) delete CoreWsStreamChannel.#state[wsManagementId][socket.id];
+        return;
+      }
+      const [roomId, userId] = entry;
+      socket.to(roomId).emit('stream-user-disconnected', userId);
+      delete CoreWsStreamChannel.#state[wsManagementId][socket.id];
+    },
+  });
+
+  /** @returns {Object.<string, import('socket.io').Socket>} Connected sockets map. */
+  static get client() {
+    return this.#io.client;
+  }
+
+  /** @returns {string} Channel name. */
+  static get channel() {
+    return this.#io.channel;
+  }
+
+  /**
+   * Initializes state for a server instance.
+   * @param {string} wsManagementId - Unique server context ID (`${host}${path}`).
+   */
+  static init(wsManagementId) {
+    this.#state[wsManagementId] = {};
+  }
+
+  /**
+   * Registers a socket connection.
+   * @param {import('socket.io').Socket} socket
+   * @param {string} wsManagementId
+   */
+  static connection(socket, wsManagementId) {
+    return this.#io.connection(socket, wsManagementId);
+  }
+
+  /**
+   * Handles socket disconnection.
+   * @param {import('socket.io').Socket} socket
+   * @param {string} reason
+   * @param {string} wsManagementId
+   */
+  static disconnect(socket, reason, wsManagementId) {
+    return this.#io.disconnect(socket, reason, wsManagementId);
+  }
+}
+
+export { CoreWsStreamChannel };

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

@@ -1,47 +1,36 @@
 /**
- * Module for handling new WebSocket connections and setting up channel listeners.
- * @module ws/core.ws.connection
- * @namespace CoreWsConnection
+ * Core WebSocket connection handler — wires sockets to all channels.
+ * @module ws/core/core.ws.connection
  */
 
 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);
 
 /**
- * @class CoreWsConnectionManager
- * @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 CoreWsConnectionHandler
+ * @classdesc Subscribes a new socket to all core channels (chat, mailer, stream)
+ * and delegates disconnect events to each channel.
  */
-class CoreWsConnectionManager {
+class CoreWsConnectionHandler {
   /**
-   * 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}
+   * Handles a new WebSocket connection.
+   * @param {import('socket.io').Socket} socket
+   * @param {string} wsManagementId
    */
-  static handleConnection(socket, wsManagementId) {
+  static handle(socket, wsManagementId) {
     logger.info(`New connection established. Socket ID: ${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);
 
-    // Set up the disconnect listener
     socket.on('disconnect', (reason) => {
-      logger.info(`Connection disconnected. Socket ID: ${socket.id} due to reason: ${reason}`);
+      logger.info(`Connection disconnected. Socket ID: ${socket.id}, reason: ${reason}`);
 
-      // Notify all channels of the disconnection
       CoreWsChatChannel.disconnect(socket, reason, wsManagementId);
       CoreWsMailerChannel.disconnect(socket, reason, wsManagementId);
       CoreWsStreamChannel.disconnect(socket, reason, wsManagementId);
@@ -49,14 +38,4 @@ class CoreWsConnectionManager {
   }
 }
 
-/**
- * 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 { CoreWsConnectionManager, CoreWsConnection };
+export { CoreWsConnectionHandler };

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

@@ -1,29 +1,24 @@
 /**
- * Module for standardized WebSocket message emission (sending).
- * @module ws/core.ws.emit
- * @namespace CoreWsEmitter
+ * Standardized WebSocket message emission.
+ * @module ws/core/core.ws.emit
  */
 
 import { loggerFactory } from '../../server/logger.js';
-import { Socket } from 'socket.io';
 
 const logger = loggerFactory(import.meta);
 
 /**
  * @class CoreWsEmitter
- * @alias CoreWsEmitter
- * @memberof CoreWsEmitter
- * @classdesc Provides a static utility method for safely emitting messages over a WebSocket connection.
+ * @classdesc Provides a static utility for safely emitting JSON-serialized messages over Socket.IO.
  */
 class CoreWsEmitter {
   /**
-   * Emits a payload to a specific client over a given channel.
-   * The payload is automatically JSON stringified.
+   * Emits a JSON-stringified payload to a client on a given channel.
    *
    * @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.
+   * @param {string} channel - The channel/event name to emit on.
+   * @param {import('socket.io').Socket} client - The Socket.IO socket to emit to.
+   * @param {Object} payload - The data object to send.
    * @returns {void}
    */
   static emit(channel = '', client = {}, payload = {}) {
@@ -31,23 +26,12 @@ class CoreWsEmitter {
       if (client && typeof client.emit === 'function') {
         client.emit(channel, JSON.stringify(payload));
       } else {
-        logger.error('Invalid client: Cannot emit message.', { channel, client, payload });
+        logger.error('Invalid client: Cannot emit message.', { channel, payload });
       }
     } catch (error) {
-      logger.error(error, { channel, client, payload, stack: error.stack });
+      logger.error(error, { channel, 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 { CoreWsEmitter, CoreWsEmit };
+export { CoreWsEmitter };