underpost 3.2.22 → 3.2.28

package/src/{server → client-builder}/client-icons.js

@@ -1,10 +1,10 @@
 /**
  * Module for building client-side icons
- * @module src/server/client-icons.js
+ * @module src/client-builder/client-icons.js
  * @namespace clientIcons
  */
 import { favicons } from 'favicons';
-import { loggerFactory } from './logger.js';
+import { loggerFactory } from '../server/logger.js';
 import fs from 'fs-extra';
 import { getCapVariableName } from '../client/components/core/CommonJs.js';
 

package/src/{server → client-builder}/ssr.js

@@ -1,6 +1,6 @@
 /**
  * Module for managing server side rendering
- * @module src/server/ssr.js
+ * @module src/client-builder/ssr.js
  * @namespace ServerSideRendering
  */
 
@@ -10,19 +10,19 @@ import vm from 'node:vm';
 import Underpost from '../index.js';
 
 import { srcFormatted, JSONweb } from './client-formatted.js';
-import { loggerFactory } from './logger.js';
-import { getRootDirectory } from './process.js';
+import { loggerFactory } from '../server/logger.js';
+import { getRootDirectory } from '../server/process.js';
 
 const logger = loggerFactory(import.meta);
 
 /**
  * Creates a server-side rendering component function from a given file path.
  * 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.
+ * @param {string} [componentPath='./src/client/ssr/RootDocument.js'] - The path to the SSR component file.
  * @returns {Promise<Function>} A promise that resolves to the SSR component function.
  * @memberof ServerSideRendering
  */
-const ssrFactory = async (componentPath = `./src/client/ssr/Render.js`) => {
+const ssrFactory = async (componentPath = `./src/client/ssr/RootDocument.js`) => {
   const context = { SrrComponent: () => {}, npm_package_version: Underpost.version };
   vm.createContext(context);
   vm.runInContext(await srcFormatted(fs.readFileSync(componentPath, 'utf8')), context);

package/src/client.build.js

@@ -6,7 +6,7 @@
 import { loggerFactory } from './server/logger.js';
 import { Config } from './server/conf.js';
 import { ProcessController } from './server/process.js';
-import { clientLiveBuild } from './server/client-build-live.js';
+import { clientLiveBuild } from './client-builder/client-build-live.js';
 
 await Config.build();
 

package/src/client.dev.js

@@ -6,7 +6,7 @@
 import { loggerFactory } from './server/logger.js';
 import { ProcessController } from './server/process.js';
 import { Config, buildClientStaticConf } from './server/conf.js';
-import { createClientDevServer } from './server/client-dev-server.js';
+import { createClientDevServer } from './client-builder/client-dev-server.js';
 
 const logger = loggerFactory(import.meta);
 

package/src/index.js

@@ -10,6 +10,7 @@ import UnderpostKickStart from './cli/kickstart.js';
 import UnderpostCluster from './cli/cluster.js';
 import UnderpostDB from './cli/db.js';
 import UnderpostDeploy from './cli/deploy.js';
+import UnderpostDockerCompose from './cli/docker-compose.js';
 import UnderpostKubectl from './cli/kubectl.js';
 import UnderpostRootEnv from './cli/env.js';
 import UnderpostFileStorage from './cli/fs.js';
@@ -44,7 +45,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.2.22';
+  static version = 'v3.2.28';
 
   /**
    * Required Node.js major version
@@ -146,6 +147,15 @@ class Underpost {
   static get deploy() {
     return UnderpostDeploy.API;
   }
+  /**
+   * Docker Compose pipeline cli API
+   * @static
+   * @type {UnderpostDockerCompose.API}
+   * @memberof Underpost
+   */
+  static get dockerCompose() {
+    return UnderpostDockerCompose.API;
+  }
   /**
    * File Storage cli API
    * @static
@@ -321,6 +331,7 @@ export {
   UnderpostCluster,
   UnderpostDB,
   UnderpostDeploy,
+  UnderpostDockerCompose,
   UnderpostKubectl,
   UnderpostRootEnv,
   UnderpostFileStorage,

package/src/mailer/EmailRender.js

@@ -1,4 +1,4 @@
-import { ssrFactory } from '../server/ssr.js';
+import { ssrFactory } from '../client-builder/ssr.js';
 
 /**
  * Module for handling the rendering and styling of HTML emails using SSR components.

package/src/{server → projects/underpost}/catalog-underpost.js

@@ -1,7 +1,7 @@
 /**
  * Underpost platform content catalog — the base `pwa-microservices-template`.
  *
- * @module src/server/catalog-underpost.js
+ * @module src/projects/underpost/catalog-underpost.js
  * @namespace UnderpostCatalog
  */
 
@@ -11,7 +11,6 @@
  * @memberof UnderpostCatalog
  */
 const TEMPLATE_RESTORE_PATHS = [
-  `./src/server/catalog-underpost.js`,
   `./.github/workflows/pwa-microservices-template-page.cd.yml`,
   `./.github/workflows/pwa-microservices-template-test.ci.yml`,
   `./.github/workflows/npmpkg.ci.yml`,

package/src/runtime/express/Express.js

@@ -19,8 +19,8 @@ import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { createPeerServer } from '../../server/peer.js';
 import { createValkeyConnection } from '../../server/valkey.js';
 import { applySecurity, authMiddlewareFactory } from '../../server/auth.js';
-import { ssrMiddlewareFactory } from '../../server/ssr.js';
-import { buildSwaggerUiOptions } from '../../server/client-build-docs.js';
+import { ssrMiddlewareFactory } from '../../client-builder/ssr.js';
+import { buildSwaggerUiOptions } from '../../client-builder/client-build-docs.js';
 
 import { shellExec } from '../../server/process.js';
 import { devProxyHostFactory, isDevProxyContext, isTlsDevProxy } from '../../server/conf.js';

package/src/runtime/nginx/Nginx.js

@@ -0,0 +1,250 @@
+/**
+ * Exported singleton instance of the NginxService class.
+ * Manages dynamic generation of nginx reverse-proxy router configuration used
+ * by the Docker Compose development stack. Mirrors the conventions of
+ * {@link module:src/runtime/lampp/Lampp.js LamppService}.
+ * @module src/runtime/nginx/Nginx.js
+ * @namespace NginxService
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { loggerFactory } from '../../server/logger.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @class NginxService
+ * @description Builds nginx `server` blocks (the router) for fronting upstream
+ * application services and writes the rendered configuration to disk. The
+ * router is accumulated in memory via {@link NginxService#createApp} and
+ * flushed with {@link NginxService#writeConf}, keeping config generation
+ * decoupled from the filesystem location it is written to.
+ * @memberof NginxService
+ */
+class NginxService {
+  /**
+   * @type {string}
+   * @description Accumulated nginx `server { ... }` blocks (the router definition).
+   * @memberof NginxService
+   */
+  router = '';
+
+  /**
+   * @type {Set<string>}
+   * @description Upstream blocks keyed by upstream name to avoid duplicates.
+   * @memberof NginxService
+   */
+  upstreams;
+
+  /**
+   * @type {boolean}
+   * @description Whether a default_server catch-all block has been emitted.
+   * @memberof NginxService
+   */
+  hasDefaultServer;
+
+  constructor() {
+    this.reset();
+  }
+
+  /**
+   * Resets the in-memory router, upstreams, and default-server flag.
+   * @method reset
+   * @returns {void}
+   * @memberof NginxService
+   */
+  reset() {
+    this.router = '';
+    this.upstreams = new Map();
+    this.hasDefaultServer = false;
+  }
+
+  /**
+   * Appends a raw render fragment to the router string.
+   * @method appendRouter
+   * @param {string} render - The configuration fragment to append.
+   * @returns {string} The complete, updated router configuration string.
+   * @memberof NginxService
+   */
+  appendRouter(render) {
+    if (!this.router) return (this.router = render);
+    return (this.router += render);
+  }
+
+  /**
+   * Clears the in-memory router configuration.
+   * @method removeRouter
+   * @returns {void}
+   * @memberof NginxService
+   */
+  removeRouter() {
+    this.reset();
+  }
+
+  /**
+   * Registers a named upstream pointing at a container service:port.
+   * Idempotent: repeated names with the same target are collapsed.
+   * @method addUpstream
+   * @param {string} name - The upstream identifier.
+   * @param {string} service - The Docker service name (resolved via service discovery).
+   * @param {number} port - The upstream container port.
+   * @returns {string} The upstream name.
+   * @memberof NginxService
+   */
+  addUpstream(name, service, port) {
+    this.upstreams.set(name, `upstream ${name} { server ${service}:${port}; }`);
+    return name;
+  }
+
+  /**
+   * Renders the standard proxy directive block shared by all locations,
+   * including websocket upgrade headers and forwarded headers.
+   * @method proxyLocation
+   * @param {string} location - The location path (e.g. '/', '/peer').
+   * @param {string} upstream - The upstream name to proxy to.
+   * @returns {string} The rendered `location { ... }` block.
+   * @memberof NginxService
+   */
+  proxyLocation(location, upstream) {
+    return `
+    location ${location} {
+        proxy_pass http://${upstream};
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_read_timeout 3600s;
+    }
+`;
+  }
+
+  /**
+   * Renders the `/healthz` location used by the proxy container healthcheck.
+   * @method healthLocation
+   * @returns {string} The rendered health-check location block.
+   * @memberof NginxService
+   */
+  healthLocation() {
+    return `
+    location = /healthz {
+        access_log off;
+        return 200 "ok\\n";
+        add_header Content-Type text/plain;
+    }
+`;
+  }
+
+  /**
+   * Creates an nginx virtual-host (`server`) entry for a host and appends it to
+   * the router. Each route maps a URL prefix to an upstream service:port with
+   * websocket support, mirroring the Contour HTTPProxy route model.
+   *
+   * @method createApp
+   * @param {object} options - Virtual host options.
+   * @param {string} options.host - The `server_name` (e.g. 'default.net').
+   * @param {number} [options.listen=80] - The listen port.
+   * @param {Array<{location: string, service: string, port: number}>} options.routes
+   *   - Route table. Longer prefixes should precede '/' for correct matching.
+   * @param {boolean} [options.resetRouter] - Clear the router before appending.
+   * @returns {string} The complete, updated router configuration string.
+   * @memberof NginxService
+   */
+  createApp({ host, listen = 80, routes = [], resetRouter = false }) {
+    if (resetRouter) this.removeRouter();
+
+    const safeHost = host.replace(/[^a-zA-Z0-9]/g, '_');
+    const locationBlocks = routes
+      .map(({ location, service, port }) => {
+        const upstreamName = this.addUpstream(`up_${safeHost}_${port}`, service, port);
+        return this.proxyLocation(location, upstreamName);
+      })
+      .join('');
+
+    this.appendRouter(`
+server {
+    listen ${listen};
+    server_name ${host};
+${this.healthLocation()}${locationBlocks}}
+`);
+
+    return this.router;
+  }
+
+  /**
+   * Emits a `default_server` catch-all that forwards to the given upstream and
+   * answers the health probe for unmatched Host headers. Safe to call once.
+   *
+   * @method createDefaultServer
+   * @param {object} options - Default server options.
+   * @param {string} options.service - The Docker service name to fall back to.
+   * @param {number} options.port - The upstream container port.
+   * @param {number} [options.listen=80] - The listen port.
+   * @returns {string} The complete, updated router configuration string.
+   * @memberof NginxService
+   */
+  createDefaultServer({ service, port, listen = 80 }) {
+    if (this.hasDefaultServer) return this.router;
+    this.hasDefaultServer = true;
+    const upstreamName = this.addUpstream('up_default', service, port);
+    this.appendRouter(`
+server {
+    listen ${listen} default_server;
+    server_name _;
+${this.healthLocation()}${this.proxyLocation('/', upstreamName)}}
+`);
+    return this.router;
+  }
+
+  /**
+   * Renders the full nginx config document: the websocket connection map, all
+   * upstream blocks, the global `proxy_http_version`, and the accumulated router.
+   * @method render
+   * @returns {string} The complete nginx configuration file content.
+   * @memberof NginxService
+   */
+  render() {
+    const upstreamBlocks = Array.from(this.upstreams.values()).join('\n');
+    return `# Generated by src/runtime/nginx/Nginx.js — do not hand-edit.
+# Reverse proxy derived from manifests/deployment/*/proxy.yaml (Contour HTTPProxy).
+# Upstreams resolve container services via the Docker internal network.
+
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+${upstreamBlocks}
+
+proxy_http_version 1.1;
+${this.router}`;
+  }
+
+  /**
+   * Writes the rendered configuration to the given path, creating parent
+   * directories as needed. Idempotent and safe to rerun.
+   * @method writeConf
+   * @param {string} confPath - Absolute or relative destination path.
+   * @returns {string} The path written.
+   * @memberof NginxService
+   */
+  writeConf(confPath) {
+    const target = path.resolve(confPath);
+    fs.mkdirpSync(path.dirname(target));
+    fs.writeFileSync(target, this.render(), 'utf8');
+    logger.info(`nginx config written`, { path: target, upstreams: this.upstreams.size });
+    return target;
+  }
+}
+
+/**
+ * @description Exported singleton instance of the NginxService class.
+ * @type {NginxService}
+ * @memberof NginxService
+ */
+const Nginx = new NginxService();
+
+export { Nginx, NginxService };
+export default Nginx;

package/src/server/catalog.js

@@ -18,8 +18,6 @@ import fs from 'fs-extra';
 import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 
-const catalogDir = path.dirname(fileURLToPath(import.meta.url));
-
 /** Empty product catalog returned for deploy ids without a dedicated module. */
 const EMPTY_CATALOG = {
   sourceMoves: [],
@@ -43,12 +41,11 @@ const EMPTY_CATALOG = {
 const loadDeployCatalog = async (deployId) => {
   const suffix = (deployId ?? '').split('dd-')[1];
   if (!suffix) return EMPTY_CATALOG;
-  try {
-    const mod = await import(`./catalog-${suffix}.js`);
+  if (fs.existsSync(`./src/projects/${suffix}/catalog-${suffix}.js`)) {
+    const mod = await import(`../projects/${suffix}/catalog-${suffix}.js`);
     return { ...EMPTY_CATALOG, ...(mod.default ?? {}) };
-  } catch {
-    return EMPTY_CATALOG;
   }
+  return EMPTY_CATALOG;
 };
 
 /**
@@ -62,14 +59,10 @@ const loadDeployCatalog = async (deployId) => {
  */
 const loadProductCatalogs = async () => {
   const catalogs = [];
-  for (const file of fs.readdirSync(catalogDir)) {
-    if (!/^catalog-.+\.js$/.test(file) || file === 'catalog-underpost.js') continue;
-    try {
-      const mod = await import(`./${file}`);
-      if (mod.default) catalogs.push({ ...EMPTY_CATALOG, ...mod.default });
-    } catch {
-      /* a malformed/removed product catalog must not break the base build */
-    }
+  for (const file of await fs.readdir('./src/projects')) {
+    if (file === 'underpost') continue;
+    const mod = await import(`../projects/${file}/catalog-${file}.js`);
+    if (mod.default) catalogs.push({ ...EMPTY_CATALOG, ...mod.default });
   }
   return catalogs;
 };

package/src/server/conf.js

@@ -1337,7 +1337,7 @@ const mergeFile = async (parts = [], outputFilePath) => {
  * @memberof ServerConfBuilder
  */
 const getPathsSSR = (conf) => {
-  const paths = ['src/client/ssr/Render.js'];
+  const paths = ['src/client/ssr/RootDocument.js'];
   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`);
@@ -1928,7 +1928,8 @@ const syncDeployIdSources = (sourceMoves = []) => {
  */
 const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-template' } = {}) => {
   const walk = (await import('ignore-walk')).default;
-  const { TEMPLATE_RESTORE_PATHS, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION } = await import('./catalog-underpost.js');
+  const { TEMPLATE_RESTORE_PATHS, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION } =
+    await import('../projects/underpost/catalog-underpost.js');
   const { loadProductCatalogs } = await import('./catalog.js');
   const githubUsername = process.env.GITHUB_USERNAME;
 
@@ -1974,7 +1975,6 @@ const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-te
   }
   shellExec(`rm -rf ${toPath}/.github`);
   shellExec(`rm -rf ${toPath}/manifests/deployment/dd-*`);
-  shellExec(`rm -rf ${toPath}/src/server/catalog-*`);
 
   fs.mkdirSync(`${toPath}/.github/workflows`, { recursive: true });
   for (const restorePath of TEMPLATE_RESTORE_PATHS) {

package/src/server.js

@@ -4,7 +4,7 @@
 // https://expressjs.com/en/4x/api.html
 
 import { loggerFactory } from './server/logger.js';
-import { buildClient } from './server/client-build.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';

package/typedoc.json

@@ -8,7 +8,9 @@
     "./src/ws",
     "./src/grpc",
     "./src/mailer",
-    "./src/runtime"
+    "./src/runtime",
+    "./src/client-builder",
+    "./src/projects/underpost"
   ],
   "entryPointStrategy": "expand",
   "exclude": ["**/node_modules/**", "**/docs/**", "**/client/**"],