cyberia 3.2.5 → 3.2.12

package/src/server/valkey.js

@@ -1,293 +1,201 @@
 /**
- * Module for managing Valkey
+ * Valkey connection and key-value store module.
+ *
+ * Responsibilities:
+ *  - Manage per-instance Valkey connections keyed by `${host}${path}`.
+ *  - Provide a thin, typed CRUD surface: get / set / del / update.
+ *  - Expose connection status helpers.
+ *
+ * Out of scope: domain model factories, DTO projection — those belong in
+ * their respective service modules (e.g. guest.service.js).
+ *
  * @module src/server/valkey.js
  * @namespace ValkeyService
  */
-
 import Valkey from 'iovalkey';
-import mongoose from 'mongoose';
-import { hashPassword } from './auth.js';
 import { loggerFactory } from './logger.js';
+import Underpost from '../index.js';
 
 const logger = loggerFactory(import.meta);
 
-// Per-instance registries keyed by `${host}${path}`
+// ─── Instance registry ────────────────────────────────────────────────────────
+
+/** @type {Record<string, import('iovalkey').default>} */
 const ValkeyInstances = {};
-const DummyStores = {}; // in-memory Maps per instance
-const ValkeyStatus = {}; // 'connected' | 'dummy' | 'error' | undefined
+
+/** @type {Record<string, 'connected' | 'reconnecting' | 'error'>} */
+const ValkeyStatus = {};
 
 /**
- * Checks if any Valkey instance is connected.
- * This is a backward-compatible overall flag.
- * @returns {boolean} True if any instance has a 'connected' status.
- * @memberof ValkeyService
+ * Derives the registry key from an instance descriptor.
+ * @param {{ host?: string, path?: string }} opts
+ * @returns {string}
  */
-const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
+const _instanceKey = (opts = {}) => `${opts.host || ''}${opts.path || ''}`;
+
+// ─── Connection ───────────────────────────────────────────────────────────────
 
 /**
- * Generates a unique key for a Valkey instance based on its host and path.
- * @param {object} [opts={ host: '', path: '' }] - The instance options.
- * @param {string} [opts.host=''] - The host of the instance.
- * @param {string} [opts.path=''] - The path of the instance.
- * @returns {string} The instance key.
- * @private
+ * Returns true when at least one Valkey instance is connected.
+ * @returns {boolean}
  * @memberof ValkeyService
  */
-const _instanceKey = (opts = { host: '', path: '' }) => `${opts.host || ''}${opts.path || ''}`;
+const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
 
 /**
- * Creates and manages a connection to a Valkey server for a given instance.
- * It sets up a client, attaches event listeners for connection status, and implements a fallback to an in-memory dummy store if the connection fails.
- * @param {object} [instance={ host: '', path: '' }] - The instance identifier.
- * @param {string} [instance.host=''] - The host of the instance.
- * @param {string} [instance.path=''] - The path of the instance.
- * @param {object} [valkeyServerConnectionOptions={ host: '', path: '' }] - Connection options for the iovalkey client.
- * @returns {Promise<Valkey|undefined>} A promise that resolves to the Valkey client instance, or undefined if creation fails.
+ * Creates a Valkey client for the given instance and waits for connectivity.
+ * Throws on connection failure — callers decide whether to abort or continue
+ * without Valkey.
+ *
+ * @param {{ host?: string, path?: string }} instance - Registry key descriptor.
+ * @param {{ host?: string, port?: number }} connectionOptions - iovalkey connection options.
+ * @returns {Promise<import('iovalkey').default>}
  * @memberof ValkeyService
  */
-const createValkeyConnection = async (
-  instance = { host: '', path: '' },
-  valkeyServerConnectionOptions = { host: '', path: '' },
-) => {
+const createValkeyConnection = async (instance = {}, connectionOptions = {}) => {
   const key = _instanceKey(instance);
-  // Initialize dummy store for the instance
-  if (!DummyStores[key]) DummyStores[key] = new Map();
 
-  try {
-    const client = await ValkeyAPI.valkeyClientFactory(valkeyServerConnectionOptions);
-
-    // Attach listeners for visibility
-    client.on?.('ready', () => {
-      ValkeyStatus[key] = 'connected';
-      logger.info('Valkey connected', { instance, status: ValkeyStatus[key] });
-    });
-    client.on?.('error', (err) => {
-      // Switch to dummy if not yet connected
-      if (ValkeyStatus[key] !== 'connected') {
-        ValkeyStatus[key] = 'dummy';
-      } else {
-        ValkeyStatus[key] = 'error';
-      }
-      logger.warn('Valkey error', { err: err?.message, instance, status: ValkeyStatus[key] });
-    });
-    client.on?.('end', () => {
-      if (ValkeyStatus[key] !== 'dummy') ValkeyStatus[key] = 'error';
-      logger.warn('Valkey connection ended', { instance, status: ValkeyStatus[key] });
-    });
-
-    // Probe connectivity with a short timeout
-    const probe = async () => {
+  const client = new Valkey({
+    port: connectionOptions.port ?? undefined,
+    host: connectionOptions.host ?? undefined,
+    // 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', () => {
+    ValkeyStatus[key] = 'connected';
+    logger.info('Valkey connected', { instance });
+  });
+  client.on('error', (err) => {
+    ValkeyStatus[key] = 'error';
+    logger.error('Valkey error', { err: err?.message, instance });
+    if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error');
+  });
+  client.on('reconnecting', () => {
+    ValkeyStatus[key] = 'reconnecting';
+    logger.warn('Valkey reconnecting...', { instance });
+  });
+  client.on('end', () => {
+    ValkeyStatus[key] = 'error';
+    logger.warn('Valkey connection ended', { instance });
+  });
+
+  // Verify connectivity with a probe before marking ready
+  await Promise.race([
+    (async () => {
       try {
-        // basic ping via SET/GET roundtrip
-        const probeKey = `__vk_probe_${Date.now()}`;
-        await client.set(probeKey, '1');
-        await client.get(probeKey);
+        const probe = `__vk_probe_${Date.now()}`;
+        await client.set(probe, '1');
+        await client.get(probe);
+        await client.del(probe);
         ValkeyStatus[key] = 'connected';
-      } catch (e) {
-        ValkeyStatus[key] = 'dummy';
-        logger.warn('Valkey probe failed, falling back to dummy', { instance, error: e?.message });
+      } catch {
+        ValkeyStatus[key] = 'error';
       }
-    };
-
-    // Race with timeout to avoid hanging
-    await Promise.race([probe(), new Promise((resolve) => setTimeout(resolve, 1000))]);
+    })(),
+    new Promise((resolve) => setTimeout(resolve, 1500)),
+  ]);
 
-    ValkeyInstances[key] = client;
-    if (!ValkeyStatus[key]) ValkeyStatus[key] = 'dummy';
-  } catch (err) {
-    ValkeyStatus[key] = 'dummy';
-    logger.warn('Valkey client creation failed, using dummy', { instance, error: err?.message });
-  }
-
-  return ValkeyInstances[key];
+  ValkeyInstances[key] = client;
+  logger.info('Valkey instance registered', { key, status: ValkeyStatus[key] });
+  return client;
 };
 
+// ─── Internal client resolver ─────────────────────────────────────────────────
+
 /**
- * Factory function to create a Data Transfer Object (DTO) from a payload.
- * It filters the payload to include only the keys specified in the `select` object.
- * @param {object} payload - The source object.
- * @param {object} select - An object where keys are field names and values are 1 to include them.
- * @returns {object} A new object containing only the selected fields from the payload.
- * @memberof ValkeyService
+ * Resolves the connected client for an instance or throws.
+ * @param {{ host?: string, path?: string }} options
+ * @returns {import('iovalkey').default}
  */
-const selectDtoFactory = (payload, select) => {
-  const result = {};
-  for (const key of Object.keys(select)) {
-    if (select[key] === 1 && key in payload) result[key] = payload[key];
+const _client = (options) => {
+  const k = _instanceKey(options);
+  const client = ValkeyInstances[k];
+  if (!client || ValkeyStatus[k] !== 'connected') {
+    throw new Error(`Valkey instance not connected: ${k}`);
   }
-  return result;
+  return client;
 };
 
-/**
- * Factory function to create a new Valkey client instance.
- * @param {object} options - Connection options for the iovalkey client.
- * @returns {Promise<Valkey>} A promise that resolves to a new Valkey client.
- * @memberof ValkeyService
- */
-const valkeyClientFactory = async (options) => {
-  const valkey = new Valkey({
-    port: options?.port ? options.port : undefined,
-    host: options?.host ? options.host : undefined,
-    // Keep retry strategy minimal; state handled in createValkeyConnection
-    retryStrategy: (attempt) => {
-      if (attempt === 1) return undefined; // stop aggressive retries early
-      return 1000; // retry interval if library continues
-    },
-  }); // Connect to 127.0.0.1:6379
-  // new Valkey(6380); // 127.0.0.1:6380
-  // new Valkey(6379, '192.168.1.1'); // 192.168.1.1:6379
-  // new Valkey('/tmp/redis.sock');
-  // new Valkey({
-  //   port: 6379, // Valkey port
-  //   host: '127.0.0.1', // Valkey host
-  //   username: 'default', // needs Valkey >= 6
-  //   password: 'my-top-secret',
-  //   db: 0, // Defaults to 0
-  // });
-  return valkey;
-};
+// ─── CRUD ─────────────────────────────────────────────────────────────────────
 
 /**
- * Retrieves an object from Valkey by key for a specific instance.
- * If the Valkey client is not connected or an error occurs, it falls back to the dummy in-memory store.
- * It automatically parses JSON strings.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key of the object to retrieve.
- * @returns {Promise<object|string|null>} A promise that resolves to the retrieved object, string, or null if not found.
+ * Retrieves and JSON-parses a value by key.
+ * Returns null when the key does not exist.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @returns {Promise<object | string | null>}
  * @memberof ValkeyService
  */
-const getValkeyObject = async (options = { host: '', path: '' }, key = '') => {
-  const k = _instanceKey(options);
-  const status = ValkeyStatus[k];
+const get = async (options, key) => {
+  const raw = await _client(options).get(key);
+  if (raw == null) return null;
   try {
-    if (status === 'connected' && ValkeyInstances[k]) {
-      const value = await ValkeyInstances[k].get(key);
-      if (value == null) return null;
-      try {
-        return JSON.parse(value);
-      } catch {
-        // not JSON, return raw string
-        return value;
-      }
-    }
-  } catch (err) {
-    logger.warn('Valkey get failed, using dummy', { key, err: err?.message });
+    return JSON.parse(raw);
+  } catch {
+    return raw;
   }
-  // Dummy fallback returns stored value as-is (string or object)
-  return DummyStores[k]?.get(key) ?? null;
 };
 
 /**
- * Sets an object or string in Valkey for a specific instance.
- * If the Valkey client is not connected, it writes to the in-memory dummy store instead.
- * Objects are automatically stringified.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key under which to store the payload.
- * @param {object|string} [payload={}] - The data to store.
- * @returns {Promise<string>} A promise that resolves to 'OK' on success.
+ * Serialises and stores a value by key.
+ * Pass `ttlMs` to set an expiry in milliseconds.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @param {object | string} payload
+ * @param {number} [ttlMs]
+ * @returns {Promise<string>} Resolves to 'OK'.
  * @memberof ValkeyService
  */
-const setValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
-  const k = _instanceKey(options);
-  const isString = typeof payload === 'string';
-  const value = isString ? payload : JSON.stringify(payload);
-  try {
-    if (ValkeyStatus[k] === 'connected' && ValkeyInstances[k]) {
-      return await ValkeyInstances[k].set(key, value);
-    }
-  } catch (err) {
-    logger.warn('Valkey set failed, writing to dummy', { key, err: err?.message });
-  }
-  if (!DummyStores[k]) DummyStores[k] = new Map();
-  // Store raw string or object accordingly
-  DummyStores[k].set(key, isString ? payload : payload);
-  return 'OK';
+const set = async (options, key, payload, ttlMs) => {
+  const value = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  if (ttlMs) return _client(options).set(key, value, 'PX', ttlMs);
+  return _client(options).set(key, value);
 };
 
 /**
- * Updates an existing object in Valkey by merging it with a new payload.
- * It retrieves the current object, merges it with the new payload, and sets the updated object back.
- * It also updates the `updatedAt` timestamp.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key of the object to update.
- * @param {object} [payload={}] - The new data to merge into the object.
- * @returns {Promise<string>} A promise that resolves to the result of the set operation.
+ * Deletes a key.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @returns {Promise<number>}
  * @memberof ValkeyService
  */
-const updateValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
-  let base = await getValkeyObject(options, key);
-  if (typeof base !== 'object' || base === null) base = {};
-  base.updatedAt = new Date().toISOString();
-  return await setValkeyObject(options, key, { ...base, ...payload });
-};
+const del = async (options, key) => _client(options).del(key);
 
 /**
- * Factory function to create a new object based on a model schema.
- * It generates a new object with default properties like `_id`, `createdAt`, and `updatedAt`,
- * and model-specific properties.
- * @param {object} [options={ host: 'localhost', path: '', object: {} }] - Options for object creation.
- * @param {string} [options.host='localhost'] - The host context for the object.
- * @param {object} [options.object={}] - An initial object to extend.
- * @param {string} [model=''] - The name of the model schema to use (e.g., 'user').
- * @returns {Promise<object>} A promise that resolves to the newly created object.
+ * Shallow-merges `payload` into the existing object stored at `key`
+ * and persists the result.  The `updatedAt` timestamp is refreshed automatically.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @param {object} payload
+ * @returns {Promise<string>} Resolves to 'OK'.
  * @memberof ValkeyService
  */
-const valkeyObjectFactory = async (options = { host: 'localhost', path: '', object: {} }, model = '') => {
-  const idoDate = new Date().toISOString();
-  options.object = options.object || {};
-  const { object } = options;
-  const _id = new mongoose.Types.ObjectId().toString();
-  object._id = _id;
-  object.createdAt = idoDate;
-  object.updatedAt = idoDate;
-  switch (model) {
-    case 'user': {
-      const role = 'guest';
-      object._id = `${role}${_id}`;
-      return {
-        ...object,
-        username: `${role}${_id.slice(-5)}`,
-        email: `${_id}@${options.host}`,
-        password: hashPassword(process.env.JWT_SECRET),
-        role,
-        failedLoginAttempts: 0,
-        phoneNumbers: [],
-        publicKey: [],
-        profileImageId: null,
-        emailConfirmed: false,
-        recoverTimeOut: null,
-        lastLoginDate: null,
-        activeSessions: [],
-      };
-    }
-    default:
-      throw new Error(`model schema not found: ${model}`);
-  }
+const update = async (options, key, payload) => {
+  const base = (await get(options, key)) ?? {};
+  return set(options, key, { ...base, ...payload, updatedAt: new Date().toISOString() });
 };
 
+// ─── Public API class ─────────────────────────────────────────────────────────
+
 /**
- * A collection of Valkey-related API functions.
- * @type {object}
- * @memberof ValkeyServiceService
+ * Namespace grouping all Valkey operations.
+ * @memberof ValkeyService
  */
-const ValkeyAPI = {
-  valkeyClientFactory,
-  selectDtoFactory,
-  getValkeyObject,
-  setValkeyObject,
-  valkeyObjectFactory,
-  updateValkeyObject,
-  createValkeyConnection,
-};
-
-export {
-  valkeyClientFactory,
-  selectDtoFactory,
-  getValkeyObject,
-  setValkeyObject,
-  valkeyObjectFactory,
-  updateValkeyObject,
-  isValkeyEnable,
-  createValkeyConnection,
-  ValkeyAPI,
-};
+class ValkeyAPI {
+  /** @param {{ host?: string, path?: string }} options */
+  static isConnected = (options) => ValkeyStatus[_instanceKey(options)] === 'connected';
+  static get = get;
+  static set = set;
+  static del = del;
+  static update = update;
+  static createValkeyConnection = createValkeyConnection;
+}
+
+export { isValkeyEnable, createValkeyConnection, get, set, del, update, ValkeyAPI };

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