@underpostnet/cyberia 3.2.80

package/src/server/tls.js

@@ -0,0 +1,254 @@
+/**
+ * Transport Layer Security (TLS) / SSL utilities and HTTPS server creation and management.
+ * @module src/server/tls.js
+ * @namespace UnderpostTLS
+ */
+
+import fs from 'fs-extra';
+import https from 'https';
+import path from 'path';
+import { loggerFactory } from './logger.js';
+
+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 UnderpostTLS
+   */
+  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 UnderpostTLS
+   */
+  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 UnderpostTLS
+   */
+  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 UnderpostTLS
+   */
+  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 UnderpostTLS
+   */
+  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.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 UnderpostTLS
+   */
+  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);
+    }
+  }
+}
+
+/**
+ * @class UnderpostTLS
+ * @description TLS/SSL utilities for Underpost.
+ * @memberof UnderpostTLS
+ */
+class UnderpostTLS {
+  static API = {
+    TLS,
+    SSL_BASE,
+    locateSslFiles: TLS.locateSslFiles,
+    validateSecureContext: TLS.validateSecureContext,
+    buildSecureContext: TLS.buildSecureContext,
+    buildLocalSSL: TLS.buildLocalSSL,
+    createSslServer: TLS.createSslServer,
+    sslRedirectMiddleware: TLS.sslRedirectMiddleware,
+  };
+}
+
+export { TLS, SSL_BASE, UnderpostTLS };
+export default UnderpostTLS;

package/src/server/valkey.js

@@ -0,0 +1,201 @@
+/**
+ * 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 { loggerFactory } from './logger.js';
+import Underpost from '../index.js';
+
+const logger = loggerFactory(import.meta);
+
+// ─── Instance registry ────────────────────────────────────────────────────────
+
+/** @type {Record<string, import('iovalkey').default>} */
+const ValkeyInstances = {};
+
+/** @type {Record<string, 'connected' | 'reconnecting' | 'error'>} */
+const ValkeyStatus = {};
+
+/**
+ * Derives the registry key from an instance descriptor.
+ * @param {{ host?: string, path?: string }} opts
+ * @returns {string}
+ */
+const _instanceKey = (opts = {}) => `${opts.host || ''}${opts.path || ''}`;
+
+// ─── Connection ───────────────────────────────────────────────────────────────
+
+/**
+ * Returns true when at least one Valkey instance is connected.
+ * @returns {boolean}
+ * @memberof ValkeyService
+ */
+const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
+
+/**
+ * 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 = {}, connectionOptions = {}) => {
+  const key = _instanceKey(instance);
+
+  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 {
+        const probe = `__vk_probe_${Date.now()}`;
+        await client.set(probe, '1');
+        await client.get(probe);
+        await client.del(probe);
+        ValkeyStatus[key] = 'connected';
+      } catch {
+        ValkeyStatus[key] = 'error';
+      }
+    })(),
+    new Promise((resolve) => setTimeout(resolve, 1500)),
+  ]);
+
+  ValkeyInstances[key] = client;
+  logger.info('Valkey instance registered', { key, status: ValkeyStatus[key] });
+  return client;
+};
+
+// ─── Internal client resolver ─────────────────────────────────────────────────
+
+/**
+ * Resolves the connected client for an instance or throws.
+ * @param {{ host?: string, path?: string }} options
+ * @returns {import('iovalkey').default}
+ */
+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 client;
+};
+
+// ─── CRUD ─────────────────────────────────────────────────────────────────────
+
+/**
+ * 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 get = async (options, key) => {
+  const raw = await _client(options).get(key);
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+};
+
+/**
+ * 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 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);
+};
+
+/**
+ * Deletes a key.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @returns {Promise<number>}
+ * @memberof ValkeyService
+ */
+const del = async (options, key) => _client(options).del(key);
+
+/**
+ * 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 update = async (options, key, payload) => {
+  const base = (await get(options, key)) ?? {};
+  return set(options, key, { ...base, ...payload, updatedAt: new Date().toISOString() });
+};
+
+// ─── Public API class ─────────────────────────────────────────────────────────
+
+/**
+ * Namespace grouping all Valkey operations.
+ * @memberof ValkeyService
+ */
+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/server.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// https://nodejs.org/api
+// https://expressjs.com/en/4x/api.html
+
+import dotenv from 'dotenv';
+import { loggerFactory } from './server/logger.js';
+import { buildClient } from './client-builder/client-build.js';
+import { buildRuntime } from './server/runtime.js';
+import { ProcessController } from './server/process.js';
+import { Config } from './server/conf.js';
+
+dotenv.config();
+
+await Config.build();
+
+const logger = loggerFactory(import.meta);
+
+await logger.setUpInfo();
+
+if (process.env.NODE_ENV === 'development') await buildClient();
+
+await buildRuntime();
+
+ProcessController.init(logger);

package/src/ws/IoInterface.js

@@ -0,0 +1,129 @@
+/**
+ * Module for creating and managing WebSocket channels.
+ * @module src/ws/IoInterface.js
+ * @namespace SocketIoInterface
+ */
+
+import { loggerFactory } from '../server/logger.js';
+import { Socket } from 'socket.io';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * Defines the structure for a WebSocket channel's behavior functions.
+ * @typedef {Object} ChannelInterface
+ * @property {string} channel - The name of the channel.
+ * @property {function(Socket, Object.<string, Socket>, string): Promise<void>} [connection] - Handler on client connection.
+ * @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
+ */
+
+/**
+ * Manages the logic, client map, and event listeners for a specific WebSocket channel,
+ * ensuring robust message handling and lifecycle management.
+ * @class IoChannel
+ * @memberof SocketIoInterface
+ */
+class IoChannel {
+  /**
+   * @method
+   * @type {ChannelInterface}
+   */
+  #IoInterface;
+
+  /**
+   * Map of connected sockets for this channel, keyed by socket ID.
+   * @type {Object.<string, Socket>}
+   */
+  client = {};
+
+  /**
+   * Creates an instance of IoChannel.
+   * @param {ChannelInterface} IoInterface - The interface object defining the channel's behavior.
+   */
+  constructor(IoInterface) {
+    this.#IoInterface = {
+      channel: '',
+      connection: async (socket = {}, client = {}, hostKeyContext = '') => { },
+      controller: async (socket = {}, client = {}, payload = {}, hostKeyContext = '', args = []) => { },
+      disconnect: async (socket = {}, client = {}, reason = '', hostKeyContext = '') => { },
+      stream: false,
+      ...IoInterface,
+    };
+    logger.debug(`Channel instance created for: ${this.channel}`);
+  }
+
+  /**
+   * Gets the name of the channel.
+   * @returns {string} The channel name.
+   */
+  get channel() {
+    return this.#IoInterface.channel;
+  }
+
+  /**
+   * Handles a new socket connection for this channel.
+   * Sets up the listener for the channel message.
+   *
+   * @param {Socket} socket - The Socket.IO socket object.
+   * @param {string} hostKeyContext - Unique identifier for the WebSocket management context.
+   * @returns {Promise<void>}
+   */
+  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, 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, hostKeyContext, stack: error.stack });
+    }
+  }
+
+  /**
+   * Handles incoming messages on the channel.
+   *
+   * @method
+   * @param {Socket} socket - The Socket.IO socket object.
+   * @param {any[]} args - The raw arguments received from the socket event.
+   * @param {string} hostKeyContext - Unique identifier for the WebSocket management context.
+   * @returns {Promise<void>}
+   */
+  async controller(socket, args, hostKeyContext) {
+    try {
+      if (!args || args.length === 0) {
+        logger.warn(`No arguments received for channel: ${this.channel}`, { socketId: socket.id });
+        return;
+      }
+      // 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, hostKeyContext, args);
+    } catch (error) {
+      logger.error(error, { channel: this.channel, hostKeyContext, socketId: socket.id, args, stack: error.stack });
+    }
+  }
+
+  /**
+   * Handles a socket disconnection for this channel.
+   *
+   * @param {Socket} socket - The Socket.IO socket object.
+   * @param {string} reason - The reason for disconnection (e.g., 'client namespace disconnect').
+   * @param {string} hostKeyContext - Unique identifier for the WebSocket management context.
+   * @returns {Promise<void>}
+   */
+  async disconnect(socket, reason, hostKeyContext) {
+    try {
+      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, hostKeyContext, reason, socketId: socket.id, stack: error.stack });
+    }
+  }
+}
+
+export { IoChannel };

package/src/ws/IoServer.js

@@ -0,0 +1,68 @@
+/**
+ * Module for creating and managing WebSocket servers.
+ * @module ws/IoServer
+ */
+
+'use strict';
+
+import { Server } from 'socket.io';
+import { loggerFactory } from '../server/logger.js';
+import Underpost from '../index.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @class IoServer
+ * @classdesc Factory for creating and configuring Socket.IO server instances
+ * with CORS configuration and HTTP server attachment.
+ */
+class IoServer {
+  /**
+   * Creates a new WebSocket server instance attached to an HTTP server.
+   *
+   * @static
+   * @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 = () => {}) {
+    logger.info('origins', options.origins);
+    const wsOptions = {
+      cors: {
+        origins: options.origins,
+        methods: ['GET', 'POST', 'DELETE', 'PUT'],
+        allowedHeaders: [
+          'Access-Control-Allow-Headers',
+          'Access-Control-Allow-Origin',
+          'X-Requested-With',
+          'X-Access-Token',
+          'Content-Type',
+          'Host',
+          'Accept',
+          'Connection',
+          'Cache-Control',
+          'Authorization',
+        ],
+        credentials: true,
+      },
+      path: options.path !== '/' ? `${options.path}/socket.io/` : '/socket.io/',
+    };
+
+    const ioServerInstance = Underpost.start.listenServerFactory(() =>
+      new Server(httpServer, wsOptions).on('connection', connectionHandler),
+    );
+
+    logger.info('Socket.IO Server created and listening', { path: wsOptions.path });
+
+    return {
+      options: wsOptions,
+      meta: import.meta,
+      ioServer: ioServerInstance,
+    };
+  }
+}
+
+export { IoServer };