underpost 3.2.8 → 3.2.10

package/src/server/conf.js

@@ -41,6 +41,20 @@ const logger = loggerFactory(import.meta);
  */
 const ENV_REF_PREFIX = 'env:';
 
+/**
+ * Resolves a standardized context key from host/path descriptors.
+ * The key is used across DB, WS, mailer, and cache registries.
+ *
+ * @method resolveHostKeyContext
+ * @param {{host?: string, path?: string}|string} [context={ host: '', path: '' }] - Context object or prebuilt key.
+ * @returns {string} Host key context string.
+ * @memberof ServerConfBuilder
+ */
+const resolveHostKeyContext = (context = { host: '', path: '' }) => {
+  if (typeof context === 'string') return context;
+  return `${context.host || ''}${context.path || ''}`;
+};
+
 /**
  * Recursively walks a configuration object and replaces every string value that
  * starts with {@link ENV_REF_PREFIX} (`"env:"`) with the corresponding
@@ -1208,7 +1222,7 @@ const validateTemplatePath = (absolutePath = '') => {
   const confSsr = DefaultConf.ssr[ssr];
   const clients = DefaultConf.client.default.services;
 
-  if (absolutePath.match('src/api') && !confServer.apis.find((p) => absolutePath.match(`src/api/${p}/`))) {
+  if (absolutePath.match('src/api') && !absolutePath.match('src/api/types.js') && !confServer.apis.find((p) => absolutePath.match(`src/api/${p}/`))) {
     return false;
   }
   if (absolutePath.match('conf.dd-') && absolutePath.match('.js')) return false;
@@ -1250,14 +1264,8 @@ const validateTemplatePath = (absolutePath = '') => {
     return false;
   }
   if (
-    absolutePath.match('src/client/ssr/offline') &&
-    !confSsr.offline.find((p) => absolutePath.match(`src/client/ssr/offline/${p.client}.js`))
-  ) {
-    return false;
-  }
-  if (
-    absolutePath.match('src/client/ssr/pages') &&
-    !confSsr.pages.find((p) => absolutePath.match(`src/client/ssr/pages/${p.client}.js`))
+    absolutePath.match('src/client/ssr/views') &&
+    !(confSsr.views || []).find((p) => absolutePath.match(`src/client/ssr/views/${p.client}.js`))
   ) {
     return false;
   }
@@ -1287,6 +1295,7 @@ const validateTemplatePath = (absolutePath = '') => {
 const awaitDeployMonitor = async (init = false, deltaMs = 1000) => {
   if (init) Underpost.env.set('await-deploy', new Date().toISOString());
   await timer(deltaMs);
+  if (Underpost.env.get('container-status') === 'error') throw new Error('Container status error');
   if (Underpost.env.get('await-deploy')) return await awaitDeployMonitor();
 };
 
@@ -1312,59 +1321,6 @@ const mergeFile = async (parts = [], outputFilePath) => {
   });
 };
 
-/**
- * @method rebuildConfFactory
- * @description Rebuilds the conf factory.
- * @param {object} options - The options.
- * @param {string} options.deployId - The deploy ID.
- * @param {string} options.valkey - The valkey.
- * @param {boolean} [options.mongo=false] - The mongo.
- * @returns {object} - The rebuild conf factory.
- * @memberof ServerConfBuilder
- */
-const rebuildConfFactory = ({ deployId, valkey, mongo }) => {
-  const confServer = loadReplicas(deployId, loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`));
-  const hosts = {};
-  for (const host of Object.keys(confServer)) {
-    hosts[host] = {};
-    for (const path of Object.keys(confServer[host])) {
-      if (!confServer[host][path].db) continue;
-      const { singleReplica, replicas, db } = confServer[host][path];
-      const { provider } = db;
-      if (singleReplica) {
-        for (const replica of replicas) {
-          const deployIdReplica = buildReplicaId({ replica, deployId });
-          const confServerReplica = loadConfServerJson(`./engine-private/replica/${deployIdReplica}/conf.server.json`);
-          for (const _host of Object.keys(confServerReplica)) {
-            for (const _path of Object.keys(confServerReplica[_host])) {
-              hosts[host][_path] = { replica: { host, path } };
-              confServerReplica[_host][_path].valkey = valkey;
-              switch (provider) {
-                case 'mongoose':
-                  confServerReplica[_host][_path].db.host = mongo.host;
-                  break;
-              }
-            }
-          }
-          fs.writeFileSync(
-            `./engine-private/replica/${deployIdReplica}/conf.server.json`,
-            JSON.stringify(confServerReplica, null, 4),
-            'utf8',
-          );
-        }
-      } else hosts[host][path] = {};
-      confServer[host][path].valkey = valkey;
-      switch (provider) {
-        case 'mongoose':
-          confServer[host][path].db.host = mongo.host;
-          break;
-      }
-    }
-  }
-  fs.writeFileSync(`./engine-private/conf/${deployId}/conf.server.json`, JSON.stringify(confServer, null, 4), 'utf8');
-  return { hosts };
-};
-
 /**
  * @method getPathsSSR
  * @description Gets the paths SSR.
@@ -1377,8 +1333,7 @@ const getPathsSSR = (conf) => {
   for (const o of conf.head) paths.push(`src/client/ssr/head/${o}.js`);
   for (const o of conf.body) paths.push(`src/client/ssr/body/${o}.js`);
   for (const o of Object.keys(conf.mailer)) paths.push(`src/client/ssr/mailer/${conf.mailer[o]}.js`);
-  for (const o of conf.offline) paths.push(`src/client/ssr/mailer/${o.client}.js`);
-  for (const o of conf.pages) paths.push(`src/client/ssr/pages/${o.client}.js`);
+  for (const o of conf.views || []) paths.push(`src/client/ssr/views/${o.client}.js`);
   return paths;
 };
 
@@ -1774,7 +1729,6 @@ export {
   pathPortAssignmentFactory,
   deployRangePortFactory,
   awaitDeployMonitor,
-  rebuildConfFactory,
   buildCliDoc,
   getInstanceContext,
   buildApiConf,
@@ -1784,6 +1738,7 @@ export {
   devProxyHostFactory,
   isTlsDevProxy,
   getTlsHosts,
+  resolveHostKeyContext,
   resolveConfSecrets,
   loadConfServerJson,
   getConfFolder,

package/src/server/data-query.js

@@ -5,7 +5,16 @@
  * @namespace DataQuery
  */
 
-export const DataQuery = {
+/**
+ * @class DataQuery
+ * @description Utility class for parsing request query parameters into Mongoose query options,
+ * including support for AG Grid filterModel and sortModel. Provides a static `parse`
+ * method that takes in request query parameters and returns an object containing the MongoDB
+ * query, sort options, pagination skip/limit, and page number. Designed to be used in API
+ * controllers to handle complex querying needs from the frontend.
+ * @memberof DataQuery
+ */
+class DataQuery {
   /**
    * Parse request query parameters into Mongoose query options
    * @param {Object} params - The request query parameters (req.query)
@@ -20,7 +29,7 @@ export const DataQuery = {
    * @memberof DataQuery
    * @returns {Object} { query, sort, skip, limit, page }
    */
-  parse: (params = {}) => {
+  static parse(params = {}) {
     let { filterModel, sortModel, page, limit, sort: sortParam, asc, order, query: defaultQuery } = params;
 
     // === 1. Pagination ===
@@ -35,7 +44,7 @@ export const DataQuery = {
     const query = DataQuery._parseFilter(filterModel, defaultQuery);
 
     return { query, sort, skip, limit, page };
-  },
+  }
 
   /**
    * Parse sort parameters from AG Grid sortModel or simple sort params
@@ -47,7 +56,7 @@ export const DataQuery = {
    * @return {Object} sort object for Mongoose
    * @memberof DataQuery
    */
-  _parseSort: (sortModel, sortParam, asc, order) => {
+  static _parseSort(sortModel, sortParam, asc, order) {
     const sort = {};
 
     // Parse sortModel from string if needed
@@ -90,7 +99,7 @@ export const DataQuery = {
     }
 
     return sort;
-  },
+  }
 
   /**
    * Parse filter parameters from AG Grid filterModel
@@ -100,7 +109,7 @@ export const DataQuery = {
    * @return {Object} query object for Mongoose
    * @memberof DataQuery
    */
-  _parseFilter: (filterModel, defaultQuery) => {
+  static _parseFilter(filterModel, defaultQuery) {
     let query = defaultQuery ? { ...defaultQuery } : {};
 
     // Parse filterModel from string if needed
@@ -127,7 +136,7 @@ export const DataQuery = {
     });
 
     return query;
-  },
+  }
 
   /**
    * Parse a single field filter
@@ -137,7 +146,7 @@ export const DataQuery = {
    * @return {Object|null} query condition for the field or null if invalid
    * @memberof DataQuery
    */
-  _parseFieldFilter: (field, filter) => {
+  static _parseFieldFilter(field, filter) {
     if (!filter || !filter.filterType) {
       return null;
     }
@@ -158,7 +167,7 @@ export const DataQuery = {
       default:
         return null;
     }
-  },
+  }
 
   /**
    * Parse text filter
@@ -168,7 +177,7 @@ export const DataQuery = {
    * @return {Object|null} query condition for the text field or null if invalid
    * @memberof DataQuery
    */
-  _parseTextFilter: (field, filter) => {
+  static _parseTextFilter(field, filter) {
     const { type, filter: filterValue } = filter;
 
     if (filterValue === null || filterValue === undefined || filterValue === '') {
@@ -219,7 +228,7 @@ export const DataQuery = {
     }
 
     return query;
-  },
+  }
 
   /**
    * Parse number filter
@@ -229,7 +238,7 @@ export const DataQuery = {
    * @return {Object|null} query condition for the number field or null if invalid
    * @memberof DataQuery
    */
-  _parseNumberFilter: (field, filter) => {
+  static _parseNumberFilter(field, filter) {
     const { type, filter: filterValue, filterTo } = filter;
 
     if (filterValue === null || filterValue === undefined) {
@@ -281,7 +290,7 @@ export const DataQuery = {
     }
 
     return query;
-  },
+  }
 
   /**
    * Parse date filter
@@ -291,7 +300,7 @@ export const DataQuery = {
    * @return {Object|null} query condition for the date field or null if invalid
    * @memberof DataQuery
    */
-  _parseDateFilter: (field, filter) => {
+  static _parseDateFilter(field, filter) {
     const { type, dateFrom, dateTo } = filter;
 
     // Handle blank/notBlank without dates
@@ -391,7 +400,7 @@ export const DataQuery = {
     }
 
     return query;
-  },
+  }
 
   /**
    * Parse set filter
@@ -401,7 +410,7 @@ export const DataQuery = {
    * @return {Object|null} query condition for the set field or null if invalid
    * @memberof DataQuery
    */
-  _parseSetFilter: (field, filter) => {
+  static _parseSetFilter(field, filter) {
     const { values } = filter;
 
     if (!Array.isArray(values) || values.length === 0) {
@@ -409,7 +418,7 @@ export const DataQuery = {
     }
 
     return { [field]: { $in: values } };
-  },
+  }
 
   /**
    * Parse multi filter (combines multiple filters with AND/OR)
@@ -419,7 +428,7 @@ export const DataQuery = {
    * @return {Object|null} query condition for the multi filter or null if invalid
    * @memberof DataQuery
    */
-  _parseMultiFilter: (field, filter) => {
+  static _parseMultiFilter(field, filter) {
     const { filterModels, operator } = filter;
 
     if (!Array.isArray(filterModels) || filterModels.length === 0) {
@@ -445,5 +454,8 @@ export const DataQuery = {
       // AND operator (default)
       return { $and: conditions };
     }
-  },
-};
+  }
+}
+
+export { DataQuery };
+export default DataQuery;

package/src/server/dns.js

@@ -101,6 +101,22 @@ class Dns {
     return ipv4.address;
   }
 
+  /**
+   * Gets the MAC address of the main (default route) network interface.
+   * @static
+   * @memberof UnderpostDns
+   * @returns {string|null} The MAC address, or null if not found.
+   */
+  static getMainInterfaceMac() {
+    const interfaceName = Dns.getDefaultNetworkInterface();
+    const networkInfo = os.networkInterfaces()[interfaceName];
+    if (!networkInfo || networkInfo.length === 0) {
+      logger.error(`Could not find network interface: ${interfaceName}`);
+      return null;
+    }
+    return networkInfo[0].mac;
+  }
+
   /**
    * Setup nftables tables and chains if they don't exist.
    * @static
@@ -491,6 +507,12 @@ class Dns {
       });
     }
 
+    if (options.mac) {
+      const mac = Dns.getMainInterfaceMac();
+      console.log(mac);
+      return mac;
+    }
+
     let ip;
     if (options.dhcp) ip = Dns.getLocalIPv4Address();
     else ip = await Dns.getPublicIp();

package/src/server/process.js

@@ -1,6 +1,22 @@
 /**
  * Module for process and shell command management.
- * Provides utilities for executing shell commands, managing signals, and handling environment details.
+ * Provides utilities for executing shell commands, managing signals, and
+ * handling environment details.
+ *
+ * Execution semantics:
+ *   - `shellExec(cmd)` throws `ShellExecError` on non-zero exit (fail-fast
+ *     is the default). CI/CD chains observe the failure end-to-end.
+ *   - `shellExec(cmd, { silentOnError: true })` opts out — returns the
+ *     `ShellString` result with `.code/.stdout/.stderr` so callers can
+ *     branch on the exit code themselves. Use for existence checks
+ *     (`test -x …`, `command -v …`, `kubectl get` when "missing" is a
+ *     normal answer).
+ *   - `shellExec(cmd, { cwd: "..." })` runs hermetically in `cwd` without
+ *      touching shelljs's global state.
+ *   - All children spawned by `shellExec` register in
+ *     `ProcessController.children` so SIGINT/SIGTERM forwarding can reach
+ *     them before the parent exits.
+ *
  * @module src/server/process.js
  * @namespace Process
  */
@@ -19,6 +35,12 @@ const logger = loggerFactory(import.meta);
 const getRootDirectory = () => process.cwd().replace(/\\/g, '/');
 /**
  * Controls and manages process-level events and signals.
+ *
+ * Subprocess registry: any child process tracked here will receive
+ * SIGTERM (followed by SIGKILL after a short grace period) when the
+ * parent receives SIGINT or SIGTERM. This prevents orphaned children
+ * during Ctrl+C in dev and during pod-termination in K8S.
+ *
  * @namespace ProcessController
  */
 class ProcessController {
@@ -41,9 +63,41 @@ class ProcessController {
     'SIGSEGV',
     'SIGILL',
   ];
+
+  /**
+   * Registry of currently running tracked child processes.
+   * Populated when callers spawn via the streaming Node-native path
+   * (future expansion). The sets are exposed so signal handlers and
+   * test harnesses can introspect / clean up the registry.
+   */
+  static children = new Set();
+
+  /** Internal: forward terminating signals to all tracked children. */
+  static _forwardToChildren(sig) {
+    if (ProcessController.children.size === 0) return;
+    for (const child of [...ProcessController.children]) {
+      try {
+        if (!child.killed) child.kill(sig);
+      } catch (_) {
+        // child may already have exited; ignore.
+      }
+    }
+    // Hard SIGKILL after 5s grace if any child is still alive.
+    setTimeout(() => {
+      for (const child of [...ProcessController.children]) {
+        try {
+          if (!child.killed) child.kill('SIGKILL');
+        } catch (_) {
+          /* noop */
+        }
+      }
+    }, 5000).unref();
+  }
+
   /**
    * Sets up listeners for various process signals defined in {@link ProcessController.SIG}.
-   * Handles graceful exit on 'SIGINT' (Ctrl+C).
+   * Handles graceful exit on 'SIGINT' (Ctrl+C) — but first forwards the
+   * signal to every tracked child so they get a chance to clean up.
    * @memberof ProcessController
    * @returns {Array<process.Process>} An array of process listener handles.
    */
@@ -53,7 +107,14 @@ class ProcessController {
         ProcessController.logger.info(`process on ${sig}`, args);
         switch (sig) {
           case 'SIGINT':
-            return process.exit();
+          case 'SIGTERM':
+          case 'SIGHUP':
+            ProcessController._forwardToChildren('SIGTERM');
+            // Give children a moment to exit cleanly before our own exit.
+            if (sig === 'SIGINT') {
+              setTimeout(() => process.exit(130), 200).unref();
+            }
+            break;
           default:
             break;
         }
@@ -71,33 +132,111 @@ class ProcessController {
     ProcessController.logger = logger;
     process.on('exit', (...args) => {
       ProcessController.logger.info(`process on exit`, args);
+      // Last-chance reap: any tracked child still alive at exit time
+      // gets a hard kill so the parent does not leak orphans into the
+      // pod / shell session.
+      ProcessController._forwardToChildren('SIGKILL');
     });
     ProcessController.onSigListen();
-    Underpost.env.delete('await-deploy');
+  }
+}
+/**
+ * `ShellExecError` — thrown by `shellExec` when the underlying command
+ * exits with a non-zero code (the default fail-fast behaviour). Carries
+ * the exit code, stdout, and stderr for inspection by callers / CI
+ * pipelines that need structured failure data.
+ */
+class ShellExecError extends Error {
+  constructor(cmd, code, stdout, stderr) {
+    super(`shellExec failed (exit=${code}): ${cmd}`);
+    this.name = 'ShellExecError';
+    this.cmd = cmd;
+    this.code = code;
+    this.stdout = stdout;
+    this.stderr = stderr;
   }
 }
 /**
  * Executes a shell command using shelljs.
+ *
+ * **Default behaviour is fail-fast**: a non-zero exit code throws
+ * `ShellExecError`. Callers that need to branch on the exit code
+ * (existence checks, optional commands) must pass `silentOnError: true`
+ * to opt out of throwing.
+ *
+ * The async-callback path is exempt from the throw — shelljs delivers
+ * `(code, stdout, stderr)` to the callback, which owns its own error
+ * handling.
+ *
  * @memberof Process
  * @param {string} cmd - The command string to execute.
  * @param {Object} [options] - Options for execution.
- * @param {boolean} [options.silent=false] - Suppress output from shell commands.
- * @param {boolean} [options.async=false] - Run command asynchronously.
- * @param {boolean} [options.stdout=false] - Return stdout content (string) instead of shelljs result object.
- * @param {boolean} [options.disableLog=false] - Prevent logging of the command.
- * @param {Function} [options.callback=null] - Callback function for asynchronous execution.
- * @returns {string|shelljs.ShellString} The result of the shell command (string if `stdout: true`, otherwise a ShellString object).
+ * @param {boolean} [options.silent=false] - Suppress child stdout/stderr to the parent terminal.
+ * @param {boolean} [options.async=false] - Run the command asynchronously (use with `callback`).
+ * @param {boolean} [options.stdout=false] - Return stdout string instead of the `ShellString` result object.
+ * @param {boolean} [options.disableLog=false] - Skip the `[process] cmd …` info log line.
+ * @param {Function} [options.callback=null] - Async callback `(code, stdout, stderr) => void` when `async: true`.
+ * @param {boolean} [options.silentOnError=false] - When `true`, swallow non-zero exits and return the `ShellString` instead of throwing. Inverse of the previous `throwOnError` flag.
+ * @param {string} [options.cwd] - Hermetic working directory (snapshotted + restored — does NOT leak).
+ * @returns {string|shelljs.ShellString} `ShellString` by default; the stdout string when `stdout: true`.
+ * @throws {ShellExecError} On non-zero exit when `silentOnError` is not set.
  */
-const shellExec = (
-  cmd,
-  options = { silent: false, async: false, stdout: false, disableLog: false, callback: null },
-) => {
+const shellExec = (cmd, options = {}) => {
   if (!options.disableLog) logger.info(`cmd`, cmd);
-  if (options.callback) return shell.exec(cmd, options, options.callback);
-  return options.stdout ? shell.exec(cmd, options).stdout : shell.exec(cmd, options);
+
+  // Whitelist exactly the keys `shelljs.exec` understands. Passing our own
+  // bookkeeping keys through (or a literal `cwd: undefined`) makes shelljs
+  // call `path.resolve(undefined)` and crash with ERR_INVALID_ARG_TYPE.
+  const shellOpts = {};
+  if (options.silent !== undefined) shellOpts.silent = options.silent;
+  if (options.async !== undefined) shellOpts.async = options.async;
+
+  // Hermetic cwd. shelljs.cd mutates a process-wide global; instead we
+  // snapshot the current cwd here, switch for the duration of this call,
+  // and restore in `finally`. We deliberately do NOT forward `cwd` to
+  // shelljs — leaving its `cwd` unset means it inherits our just-changed
+  // `process.cwd()`, and we keep full control of restore semantics.
+  const previousCwd = options.cwd ? process.cwd() : null;
+  if (options.cwd) {
+    try {
+      process.chdir(options.cwd);
+    } catch (err) {
+      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error')
+      throw new ShellExecError(cmd, -1, '', `chdir(${options.cwd}) failed: ${err.message}`);
+    }
+  }
+  try {
+    if (options.callback) {
+      // Async path. shelljs invokes the callback with (code, stdout, stderr).
+      // The callback owns its own error handling; the throw default does
+      // not apply here.
+      return shell.exec(cmd, shellOpts, options.callback);
+    }
+    const result = shell.exec(cmd, shellOpts);
+
+    if (!options.silentOnError && result && typeof result.code === 'number' && result.code !== 0) {
+      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error')
+      throw new ShellExecError(cmd, result.code, result.stdout || '', result.stderr || '');
+    }
+
+    return options.stdout ? result.stdout : result;
+  } finally {
+    if (previousCwd) {
+      try {
+        process.chdir(previousCwd);
+      } catch (_) {
+        /* best-effort restore */
+      }
+    }
+  }
 };
 /**
  * Changes the current working directory using shelljs.
+ *
+ * Note: `shellCd` mutates global state. Prefer `shellExec(cmd, { cwd })`
+ * for one-shot directory-scoped commands; use `shellCd` only for the
+ * outermost shell where the cwd should persist across many calls.
+ *
  * @memberof Process
  * @param {string} cd - The path to change the directory to.
  * @param {Object} [options] - Options for the CD operation.
@@ -110,6 +249,11 @@ const shellCd = (cd, options = { disableLog: false }) => {
 };
 /**
  * Wraps a command to run it as a daemon process in a shell (keeping the process alive/terminal open).
+ *
+ * NB: callers must ensure `cmd` does not contain unescaped single quotes —
+ * the wrapper uses `bash -c '<cmd>; …'`. For arbitrary user input prefer
+ * a heredoc or a temporary script file.
+ *
  * @memberof Process
  * @param {string} cmd - The command to daemonize.
  * @returns {string} The shell command string for the daemon process.
@@ -119,11 +263,19 @@ const daemonProcess = (cmd) => `exec bash -c '${cmd}; exec tail -f /dev/null'`;
  * Retrieves the process ID (PID) of the most recently created gnome-terminal instance.
  * Note: This function is environment-specific (GNOME/Linux) and uses `pgrep -n`.
  * @memberof Process
- * @returns {number} The PID of the last gnome-terminal process.
+ * @returns {number|null} The PID of the last gnome-terminal process, or null if none running.
  */
 // list all terminals: pgrep gnome-terminal
 // list last terminal: pgrep -n gnome-terminal
-const getTerminalPid = () => JSON.parse(shellExec(`pgrep -n gnome-terminal`, { stdout: true, silent: true }));
+const getTerminalPid = () => {
+  const raw = shellExec(`pgrep -n gnome-terminal`, { stdout: true, silent: true, silentOnError: true });
+  if (!raw || !raw.trim()) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
 /**
  * Copies text content to the system clipboard using clipboardy.
  * Logs the copied content for confirmation.
@@ -135,4 +287,13 @@ function pbcopy(data) {
   clipboard.writeSync(data || '🦄');
   logger.info(`copied to clipboard`, clipboard.readSync());
 }
-export { ProcessController, getRootDirectory, shellExec, shellCd, pbcopy, getTerminalPid, daemonProcess };
+export {
+  ProcessController,
+  ShellExecError,
+  getRootDirectory,
+  shellExec,
+  shellCd,
+  pbcopy,
+  getTerminalPid,
+  daemonProcess,
+};

package/src/server/runtime.js

@@ -176,7 +176,7 @@ const buildRuntime = async () => {
   }
 
   if (Lampp.enabled() && Lampp.router) Lampp.initService();
-
+  Underpost.env.delete('await-deploy');
   Underpost.start.logRuntimeRouter();
 };