underpost 2.8.885 → 2.8.886

package/src/server/proxy.js

@@ -1,3 +1,9 @@
+/**
+ * Manages the creation and configuration of the reverse proxy server,
+ * including handling HTTP/HTTPS listeners and routing based on host configuration.
+ * @module src/server/proxy.js
+ * @namespace ProxyService
+ */
 'use strict';
 
 import express from 'express';
@@ -5,7 +11,7 @@ import dotenv from 'dotenv';
 
 import { createProxyMiddleware } from 'http-proxy-middleware';
 import { loggerFactory, loggerMiddleware } from './logger.js';
-import { createSslServer, sslRedirectMiddleware } from './ssl.js';
+import { TLS } from './tls.js';
 import { buildPortProxyRouter, buildProxyRouter } from './conf.js';
 import UnderpostStartUp from './start.js';
 
@@ -13,81 +19,92 @@ dotenv.config();
 
 const logger = loggerFactory(import.meta);
 
-const buildProxy = async () => {
-  // default target
-
-  express().listen(process.env.PORT);
-
-  const proxyRouter = buildProxyRouter();
-
-  for (let port of Object.keys(proxyRouter)) {
-    port = parseInt(port);
-    const hosts = proxyRouter[port];
-    const proxyPath = '/';
-    const proxyHost = 'localhost';
-    const runningData = { host: proxyHost, path: proxyPath, client: null, runtime: 'nodejs', meta: import.meta };
-    const app = express();
-
-    // set logger
-    app.use(loggerMiddleware(import.meta));
-
-    // instance proxy options
-    // https://github.com/chimurai/http-proxy-middleware/tree/v2.0.4#readme
-
-    // proxy middleware options
-    /** @type {import('http-proxy-middleware/dist/types').Options} */
-    const options = {
-      ws: true,
-      // changeOrigin: true,
-      // autoRewrite: false,
-      target: `http://localhost:${process.env.PORT}`,
-      router: {},
-      xfwd: true, // adds x-forward headers
-      // preserveHeaderKeyCase: true,
-      // secure: true, warn validator
-      onProxyReq: (proxyReq, req, res, options) => {
-        // https://wtools.io/check-http-status-code
-        // http://nexodev.org
-        sslRedirectMiddleware(req, res, port, proxyRouter);
-      },
-      pathRewrite: {
-        // only add path
-        // '^/target-path': '/',
-      },
-    };
-    options.router = buildPortProxyRouter(port, proxyRouter);
-
-    const filter = false
-      ? (pathname, req) => {
-          // return pathname.match('^/api') && req.method === 'GET';
-          return true;
-        }
-      : proxyPath;
-    app.use(proxyPath, createProxyMiddleware(filter, options));
-
-    switch (process.env.NODE_ENV) {
-      case 'production':
-        switch (port) {
-          case 443:
-            const { ServerSSL } = await createSslServer(app, hosts);
-            await UnderpostStartUp.API.listenPortController(ServerSSL, port, runningData);
-            break;
-
-          default:
-            await UnderpostStartUp.API.listenPortController(app, port, runningData);
-
-            break;
-        }
-
-        break;
-
-      default:
-        await UnderpostStartUp.API.listenPortController(app, port, runningData);
-
-        break;
+/**
+ * Main class for building and running the proxy server.
+ * All utility methods are implemented as static to serve as a namespace container.
+ * @class Proxy
+ * @augments Proxy
+ * @memberof ProxyService
+ */
+class Proxy {
+  /**
+   * Initializes and starts the reverse proxy server for all configured ports and hosts.
+   * @async
+   * @static
+   * @memberof ProxyService
+   * @returns {Promise<void>}
+   * @memberof ProxyService
+   */
+  static async buildProxy() {
+    // Start a default Express listener on process.env.PORT (potentially unused, but ensures Express is initialized)
+    express().listen(process.env.PORT);
+
+    const proxyRouter = buildProxyRouter();
+
+    for (let port of Object.keys(proxyRouter)) {
+      port = parseInt(port);
+      const hosts = proxyRouter[port];
+      const proxyPath = '/';
+      const proxyHost = 'localhost';
+      const runningData = { host: proxyHost, path: proxyPath, client: null, runtime: 'nodejs', meta: import.meta };
+      const app = express();
+
+      // Set logger middleware
+      app.use(loggerMiddleware(import.meta));
+
+      // Proxy middleware options
+      /** @type {import('http-proxy-middleware/dist/types').Options} */
+      const options = {
+        ws: true, // Enable websocket proxying
+        target: `http://localhost:${process.env.PORT}`, // Default target (should be overridden by router)
+        router: {},
+        xfwd: true, // Adds x-forward headers (Host, Proto, etc.)
+        onProxyReq: (proxyReq, req, res, options) => {
+          // Use the static method from the TLS class for redirection logic
+          TLS.sslRedirectMiddleware(req, res, port, proxyRouter);
+        },
+        pathRewrite: {
+          // Add path rewrite rules here if necessary
+        },
+      };
+
+      options.router = buildPortProxyRouter(port, proxyRouter, { orderByPathLength: true });
+
+      const filter = proxyPath; // Use '/' as the general filter
+      app.use(proxyPath, createProxyMiddleware(filter, options));
+
+      // Determine which server to start (HTTP or HTTPS) based on port and environment
+      switch (process.env.NODE_ENV) {
+        case 'production':
+          switch (port) {
+            case 443:
+              // For port 443 (HTTPS), create the SSL server
+              const { ServerSSL } = await TLS.createSslServer(app, hosts);
+              await UnderpostStartUp.API.listenPortController(ServerSSL, port, runningData);
+              break;
+
+            default:
+              // For other ports in production, use standard HTTP
+              await UnderpostStartUp.API.listenPortController(app, port, runningData);
+              break;
+          }
+          break;
+
+        default:
+          // In non-production, always use standard HTTP listener
+          await UnderpostStartUp.API.listenPortController(app, port, runningData);
+          break;
+      }
+      logger.info('Proxy running', { port, options });
     }
-    logger.info('Proxy running', { port, options });
   }
-};
+}
 
-export { buildProxy };
+/**
+ * Backward compatibility export
+ * @type {function(): Promise<void>}
+ * @memberof ProxyService
+ */
+const buildProxy = Proxy.buildProxy;
+
+export { Proxy, buildProxy };

package/src/server/runtime.js

@@ -1,8 +1,9 @@
 /**
- * @namespace Runtime
- * @description The main runtime orchestrator responsible for reading configuration,
+ * The main runtime orchestrator responsible for reading configuration,
  * initializing services (Prometheus, Ports, DB, Mailer), and building the
  * specific server runtime for each host/path (e.g., nodejs, lampp).
+ * @module src/server/runtime.js
+ * @namespace Runtime
  */
 
 import fs from 'fs-extra';
@@ -27,11 +28,12 @@ const logger = loggerFactory(import.meta);
  *
  * @memberof Runtime
  * @returns {Promise<void>}
+ * @function buildRuntime
  */
 const buildRuntime = async () => {
   const deployId = process.env.DEPLOY_ID;
 
-  // 1. Initialize Prometheus Metrics
+  // Initialize Prometheus Metrics
   const collectDefaultMetrics = promClient.collectDefaultMetrics;
   collectDefaultMetrics();
 
@@ -45,16 +47,13 @@ const buildRuntime = async () => {
   const initPort = parseInt(process.env.PORT) + 1;
   let currentPort = initPort;
 
-  // 2. Load Configuration
+  // Load Configuration
   const confServer = JSON.parse(fs.readFileSync(`./conf/conf.server.json`, 'utf8'));
   const confSSR = JSON.parse(fs.readFileSync(`./conf/conf.ssr.json`, 'utf8'));
-  const singleReplicaHosts = [];
 
-  // 3. Iterate through hosts and paths
+  // Iterate through hosts and paths
   for (const host of Object.keys(confServer)) {
-    if (singleReplicaHosts.length > 0)
-      currentPort += singleReplicaHosts.reduce((accumulator, currentValue) => accumulator + currentValue.replicas, 0);
-
+    let singleReplicaOffsetPortCount = 0;
     const rootHostPath = `/public/${host}`;
     for (const path of Object.keys(confServer[host])) {
       confServer[host][path].port = newInstance(currentPort);
@@ -74,21 +73,19 @@ const buildRuntime = async () => {
         replicas,
         valkey,
         apiBaseHost,
+        useLocalSsl,
       } = confServer[host][path];
 
       // Calculate context data
-      const { redirectTarget, singleReplicaHost } = await getInstanceContext({
+      const { redirectTarget, singleReplicaOffsetPortSum } = await getInstanceContext({
+        deployId,
         redirect,
-        singleReplicaHosts,
         singleReplica,
         replicas,
       });
 
-      if (singleReplicaHost) {
-        singleReplicaHosts.push({
-          host,
-          replicas: replicas.length,
-        });
+      if (singleReplicaOffsetPortSum > 0) {
+        singleReplicaOffsetPortCount += singleReplicaOffsetPortSum;
         continue;
       }
 
@@ -113,6 +110,7 @@ const buildRuntime = async () => {
             apis,
             origins,
             directory,
+            useLocalSsl,
             ws,
             mailer,
             db,
@@ -156,6 +154,7 @@ const buildRuntime = async () => {
       }
       currentPort++;
     }
+    currentPort += singleReplicaOffsetPortCount;
   }
 
   if (Lampp.enabled() && Lampp.router) Lampp.initService();

package/src/server/ssr.js

@@ -1,7 +1,7 @@
 /**
  * Module for managing server side rendering
  * @module src/server/ssr.js
- * @namespace SSR
+ * @namespace ServerSideRendering
  */
 
 import fs from 'fs-extra';
@@ -23,7 +23,7 @@ const logger = loggerFactory(import.meta);
  * It reads the component file, formats it, and executes it in a sandboxed Node.js VM context to extract the component.
  * @param {string} [componentPath='./src/client/ssr/Render.js'] - The path to the SSR component file.
  * @returns {Promise<Function>} A promise that resolves to the SSR component function.
- * @memberof SSR
+ * @memberof ServerSideRendering
  */
 const ssrFactory = async (componentPath = `./src/client/ssr/Render.js`) => {
   const context = { SrrComponent: () => {}, npm_package_version: Underpost.version };
@@ -39,7 +39,7 @@ const ssrFactory = async (componentPath = `./src/client/ssr/Render.js`) => {
  * @param {object} req - The Express request object.
  * @param {string} html - The HTML string to sanitize.
  * @returns {string} The sanitized HTML string with nonces.
- * @memberof SSR
+ * @memberof ServerSideRendering
  */
 const sanitizeHtml = (res, req, html) => {
   const nonce = res.locals.nonce;
@@ -58,7 +58,7 @@ const sanitizeHtml = (res, req, html) => {
  * @param {string} options.rootHostPath - The root path for the host's public files.
  * @param {string} options.path - The base path for the instance.
  * @returns {Promise<{error500: Function, error400: Function}>} A promise that resolves to an object containing the 500 and 404 error handling middleware.
- * @memberof SSR
+ * @memberof ServerSideRendering
  */
 const ssrMiddlewareFactory = async ({ app, directory, rootHostPath, path }) => {
   const Render = await ssrFactory();

package/src/server/tls.js

@@ -0,0 +1,251 @@
+/**
+ * Provides utilities for managing, building, and serving SSL/TLS contexts,
+ * primarily using Certbot files and creating HTTPS servers.
+ * @module src/server/tls.js
+ * @namespace TransportLayerSecurity
+ */
+
+import fs from 'fs-extra';
+import https from 'https';
+import path from 'path';
+import dotenv from 'dotenv';
+import { loggerFactory } from './logger.js';
+
+dotenv.config();
+const logger = loggerFactory(import.meta);
+
+const DEFAULT_HOST = 'localhost';
+const SSL_BASE = (host = DEFAULT_HOST) => path.resolve(`./engine-private/ssl/${host}`);
+
+// Common filename candidates for certs/keys produced by various tools (mkcert, certbot, openssl scripts).
+const CERT_CANDIDATES = [
+  'fullchain.pem',
+  'cert.pem',
+  'ca_bundle.crt',
+  'crt.crt',
+  `${DEFAULT_HOST}.pem`,
+  `${DEFAULT_HOST}.crt`,
+  `${DEFAULT_HOST}-fullchain.pem`,
+];
+const KEY_CANDIDATES = [
+  'privkey.pem',
+  'key.key',
+  'private.key',
+  'key.pem',
+  `${DEFAULT_HOST}-key.pem`,
+  `${DEFAULT_HOST}.key`,
+];
+const ROOT_CANDIDATES = ['rootCA.pem', 'ca.pem', 'ca.crt', 'root.pem'];
+
+class TLS {
+  /**
+   * Look for existing SSL files under engine-private/ssl/<host> and return canonical paths.
+   * It attempts to be permissive: accepts cert-only, cert+ca, or fullchain.
+   * @param {string} host
+   * @returns {{key?:string, cert?:string, fullchain?:string, ca?:string, dir:string}}
+   * @memberof TransportLayerSecurity
+   */
+  static locateSslFiles(host = DEFAULT_HOST) {
+    const dir = SSL_BASE(host);
+    const result = { dir };
+
+    if (!fs.existsSync(dir)) {
+      logger.warn('SSL dir does not exist', { dir });
+      return result;
+    }
+
+    // find key
+    for (const name of KEY_CANDIDATES) {
+      const p = path.join(dir, name);
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+        result.key = p;
+        break;
+      }
+    }
+
+    // find fullchain first
+    for (const name of CERT_CANDIDATES) {
+      const p = path.join(dir, name);
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+        // treat fullchain.pem / ca_bundle.crt as fullchain if name indicates so
+        if (
+          ['fullchain.pem', 'ca_bundle.crt', `${host}-fullchain.pem`].includes(name) ||
+          name.endsWith('fullchain.pem')
+        ) {
+          result.fullchain = p;
+          result.cert = p; // fullchain will be used as cert when building context
+          break;
+        }
+        // otherwise candidate may be leaf cert
+        if (!result.cert) result.cert = p;
+      }
+    }
+
+    // find root/ca if not using fullchain
+    if (!result.fullchain) {
+      // check for direct ca bundle (cert + ca combined) names
+      const caCandidates = ROOT_CANDIDATES.concat(['ca_bundle.crt']);
+      for (const name of caCandidates) {
+        const p = path.join(dir, name);
+        if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+          result.ca = p;
+          break;
+        }
+      }
+      // if no dedicated ca found but cert looks like leaf and there is separate ca under other known names,
+      // try to detect cert + ca in a single file (not trivial) — we prefer explicit ca
+    }
+
+    return result;
+  }
+
+  /**
+   * Validate that a secure context can be built for host (key + cert or fullchain present)
+   * @param {string} host
+   * @returns {boolean}
+   * @memberof TransportLayerSecurity
+   */
+  static validateSecureContext(host = DEFAULT_HOST) {
+    const files = TLS.locateSslFiles(host);
+    return Boolean((files.key && files.cert) || (files.key && files.fullchain));
+  }
+
+  /**
+   * Build a Node.js https.createServer options object (key, cert, ca) for the given host.
+   * If a fullchain is available it will be used for cert and ca will be omitted (fullchain already includes chain).
+   * If separate cert + ca are found, they will be used accordingly.
+   * @param {string} host
+   * @returns {{key:string, cert:string, ca?:string}} options
+   * @memberof TransportLayerSecurity
+   */
+  static buildSecureContext(host = DEFAULT_HOST) {
+    const files = TLS.locateSslFiles(host);
+    if (!files.key) throw new Error(`SSL key not found for host ${host} (looked in ${files.dir})`);
+    if (!files.cert) throw new Error(`SSL certificate not found for host ${host} (looked in ${files.dir})`);
+
+    const key = fs.readFileSync(files.key, 'utf8');
+    const cert = fs.readFileSync(files.cert, 'utf8');
+
+    // If we have a root CA file (explicit) and cert is leaf-only, include ca
+    if (files.ca && files.ca !== files.cert) {
+      const ca = fs.readFileSync(files.ca, 'utf8');
+      return { key, cert, ca };
+    }
+
+    // If cert is fullchain (already contains chain), just return key/cert
+    return { key, cert };
+  }
+
+  /**
+   * Convenience: ensure default host directory exists and copy any matching cert/key files into it using canonical names.
+   * This is useful if your generator produced nonstandard names and you want to normalize them.
+   * The function will copy existing discovered files to: key.key, crt.crt, ca_bundle.crt when possible.
+   * @param {string} host
+   * @returns {boolean} true if at least key+cert exist after operation
+   * @memberof TransportLayerSecurity
+   */
+  static async buildLocalSSL(host = DEFAULT_HOST) {
+    const dir = SSL_BASE(host);
+    await fs.ensureDir(dir);
+    const files = TLS.locateSslFiles(host);
+
+    // If key+cert already exist under canonical names, done
+    const canonicalKey = path.join(dir, 'key.key');
+    const canonicalCert = path.join(dir, 'crt.crt');
+    const canonicalCa = path.join(dir, 'ca_bundle.crt');
+
+    try {
+      if (files.key && files.key !== canonicalKey) await fs.copy(files.key, canonicalKey, { overwrite: true });
+      if (files.cert && files.cert !== canonicalCert) await fs.copy(files.cert, canonicalCert, { overwrite: true });
+      if (files.ca && files.ca !== canonicalCa) await fs.copy(files.ca, canonicalCa, { overwrite: true });
+
+      // If we had a fullchain but not a separate ca, write fullchain also to ca_bundle if missing
+      if (files.fullchain && !fs.existsSync(canonicalCa)) {
+        await fs.copy(files.fullchain, canonicalCa, { overwrite: false });
+      }
+    } catch (err) {
+      logger.warn('buildLocalSSL copy step failed', { err: err.message });
+    }
+
+    return TLS.validateSecureContext(host);
+  }
+
+  /**
+   * Create an HTTPS server (first host) and/or attach SNI contexts for additional hosts.
+   * hosts param is an object whose keys are hostnames (e.g. { 'localhost': {...} }).
+   * Returns the created https.Server instance (or undefined if none created).
+   * @param {import('express').Application} app
+   * @param {Object<string, any>} hosts
+   * @returns {{ServerSSL?: https.Server}}
+   * @memberof TransportLayerSecurity
+   */
+  static async createSslServer(app, hosts = { [DEFAULT_HOST]: {} }) {
+    let server;
+    for (const host of Object.keys(hosts)) {
+      // ensure canonical files exist (copies where possible)
+      await TLS.buildLocalSSL(host);
+      if (!TLS.validate_secure_context_check(host)) {
+        // backward compatibility: some callers expect validateSecureContext
+        if (!TLS.validateSecureContext(host)) {
+          logger.error('Invalid SSL context, skipping host', { host });
+          continue;
+        }
+      }
+
+      // build secure context options
+      try {
+        const ctx = TLS.buildSecureContext(host);
+        if (!server) {
+          server = https.createServer(ctx, app);
+          logger.info('Created HTTPS server for host', { host });
+        } else {
+          server.addContext(host, ctx);
+          logger.info('Added SNI context for host', { host });
+        }
+      } catch (err) {
+        logger.error('Failed to build secure context', { host, message: err.message });
+      }
+    }
+
+    return { ServerSSL: server };
+  }
+
+  /**
+   * Middleware that redirects HTTP -> HTTPS in production for recognized hosts.
+   * Skips ACME challenge paths.
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   * @param {number} port
+   * @param {Object<string, any>} proxyRouter
+   * @returns {import('express').RequestHandler}
+   * @memberof TransportLayerSecurity
+   */
+  static sslRedirectMiddleware(req, res, port = 80, proxyRouter = {}) {
+    const sslRedirectUrl = `https://${req.headers.host}${req.url}`;
+    if (
+      process.env.NODE_ENV === 'production' &&
+      port !== 443 &&
+      !req.secure &&
+      !req.url.startsWith('/.well-known/acme-challenge') &&
+      proxyRouter[443] &&
+      Object.keys(proxyRouter[443]).find((host) => {
+        const [hostSSL] = host.split('/');
+        return sslRedirectUrl.match(hostSSL) && TLS.validateSecureContext(hostSSL);
+      })
+    ) {
+      return res.status(302).redirect(sslRedirectUrl);
+    }
+  }
+}
+
+// small helper for internal backward compatibility check name typo in older code
+TLS.validate_secure_context_check = TLS.validateSecureContext;
+
+// Backward compatibility exports
+const buildSSL = TLS.buildLocalSSL;
+const buildSecureContext = TLS.buildSecureContext;
+const validateSecureContext = TLS.validateSecureContext;
+const createSslServer = TLS.createSslServer;
+const sslRedirectMiddleware = TLS.sslRedirectMiddleware;
+
+export { TLS, buildSSL, buildSecureContext, validateSecureContext, createSslServer, sslRedirectMiddleware };

package/src/server/valkey.js

@@ -1,7 +1,7 @@
 /**
  * Module for managing Valkey
  * @module src/server/valkey.js
- * @namespace Valkey
+ * @namespace ValkeyService
  */
 
 import Valkey from 'iovalkey';
@@ -20,7 +20,7 @@ const ValkeyStatus = {}; // 'connected' | 'dummy' | 'error' | undefined
  * 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 Valkey
+ * @memberof ValkeyService
  */
 const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
 
@@ -31,7 +31,7 @@ const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'conn
  * @param {string} [opts.path=''] - The path of the instance.
  * @returns {string} The instance key.
  * @private
- * @memberof Valkey
+ * @memberof ValkeyService
  */
 const _instanceKey = (opts = { host: '', path: '' }) => `${opts.host || ''}${opts.path || ''}`;
 
@@ -43,7 +43,7 @@ const _instanceKey = (opts = { host: '', path: '' }) => `${opts.host || ''}${opt
  * @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.
- * @memberof Valkey
+ * @memberof ValkeyService
  */
 const createValkeyConnection = async (
   instance = { host: '', path: '' },
@@ -108,7 +108,7 @@ const createValkeyConnection = async (
  * @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 Valkey
+ * @memberof ValkeyService
  */
 const selectDtoFactory = (payload, select) => {
   const result = {};
@@ -122,7 +122,7 @@ const selectDtoFactory = (payload, select) => {
  * 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 Valkey
+ * @memberof ValkeyService
  */
 const valkeyClientFactory = async (options) => {
   const valkey = new Valkey({
@@ -154,7 +154,7 @@ const valkeyClientFactory = async (options) => {
  * @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.
- * @memberof Valkey
+ * @memberof ValkeyService
  */
 const getValkeyObject = async (options = { host: '', path: '' }, key = '') => {
   const k = _instanceKey(options);
@@ -185,7 +185,7 @@ const getValkeyObject = async (options = { host: '', path: '' }, key = '') => {
  * @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.
- * @memberof Valkey
+ * @memberof ValkeyService
  */
 const setValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
   const k = _instanceKey(options);
@@ -212,7 +212,7 @@ const setValkeyObject = async (options = { host: '', path: '' }, key = '', paylo
  * @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.
- * @memberof Valkey
+ * @memberof ValkeyService
  */
 const updateValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
   let base = await getValkeyObject(options, key);
@@ -230,7 +230,7 @@ const updateValkeyObject = async (options = { host: '', path: '' }, key = '', pa
  * @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.
- * @memberof Valkey
+ * @memberof ValkeyService
  */
 const valkeyObjectFactory = async (options = { host: 'localhost', path: '', object: {} }, model = '') => {
   const idoDate = new Date().toISOString();
@@ -268,6 +268,7 @@ const valkeyObjectFactory = async (options = { host: 'localhost', path: '', obje
 /**
  * A collection of Valkey-related API functions.
  * @type {object}
+ * @memberof ValkeyServiceService
  */
 const ValkeyAPI = {
   valkeyClientFactory,

package/src/ws/IoInterface.js

@@ -17,10 +17,11 @@ const logger = loggerFactory(import.meta);
  * @property {function(Socket, Object.<string, Socket>, any, string, any[]): Promise<void>} [controller] - Handler for incoming channel messages.
  * @property {function(Socket, Object.<string, Socket>, string, string): Promise<void>} [disconnect] - Handler on client disconnection.
  * @property {boolean} [stream=false] - Whether the channel should treat the message as a raw stream (no JSON parsing).
+ * @memberof SocketIoInterface
  */
 
 /**
- * @class
+ * @class IoChannel
  * @alias IoChannel
  * @memberof SocketIoInterface
  * @classdesc Manages the logic, client map, and event listeners for a specific WebSocket channel,