underpost 3.2.80 → 3.2.90

package/src/cli/ssh.js

@@ -7,6 +7,7 @@
 import { generateRandomPasswordSelection } from '../client/components/core/CommonJs.js';
 import { pbcopy, shellExec } from '../server/process.js';
 import { loggerFactory } from '../server/logger.js';
+import { waitForPort } from '../server/conf.js';
 import fs from 'fs-extra';
 import Underpost from '../index.js';
 
@@ -606,8 +607,8 @@ EOF
     },
 
     /**
-     * Waits until a TCP SSH port becomes reachable on a host.
-     * @async
+     * Waits until a TCP SSH port becomes reachable on a host. Delegates to
+     * {@link ServerConfBuilder.waitForPort}, which owns the probe.
      * @function waitForSshPort
      * @memberof UnderpostSSH
      * @param {object} params
@@ -617,25 +618,14 @@ EOF
      * @param {number} [params.intervalMs=3000] - Poll interval.
      * @returns {Promise<boolean>} True once the port accepts connections, false on timeout.
      */
-    waitForSshPort: async ({ host, port = 22, timeoutMs = 10 * 60 * 1000, intervalMs = 3000 }) => {
-      const deadline = Date.now() + timeoutMs;
-      while (Date.now() < deadline) {
-        const probe = shellExec(
-          `timeout 5 bash -c '</dev/tcp/${host}/${port}' >/dev/null 2>&1 && echo open || echo closed`,
-          { silent: true, stdout: true, silentOnError: true, disableLog: true },
-        );
-        if (`${probe}`.trim() === 'open') return true;
-        await new Promise((r) => setTimeout(r, intervalMs));
-      }
-      logger.warn(`SSH port ${host}:${port} not reachable within timeout`);
-      return false;
-    },
+    waitForSshPort: ({ host, port = 22, timeoutMs = 10 * 60 * 1000, intervalMs = 3000 }) =>
+      waitForPort({ host, port, open: true, timeoutMs, intervalMs }),
 
     /**
      * Waits until a host's SSH port stops accepting connections (e.g. while it
      * reboots). Used to detect a reboot edge before waiting for the port to come
      * back up, so callers don't latch onto the pre-reboot (ephemeral) sshd.
-     * @async
+     * Delegates to {@link ServerConfBuilder.waitForPort}.
      * @function waitForSshPortClosed
      * @memberof UnderpostSSH
      * @param {object} params
@@ -645,18 +635,8 @@ EOF
      * @param {number} [params.intervalMs=3000] - Poll interval.
      * @returns {Promise<boolean>} True once the port is closed, false on timeout.
      */
-    waitForSshPortClosed: async ({ host, port = 22, timeoutMs = 3 * 60 * 1000, intervalMs = 3000 }) => {
-      const deadline = Date.now() + timeoutMs;
-      while (Date.now() < deadline) {
-        const probe = shellExec(
-          `timeout 5 bash -c '</dev/tcp/${host}/${port}' >/dev/null 2>&1 && echo open || echo closed`,
-          { silent: true, stdout: true, silentOnError: true, disableLog: true },
-        );
-        if (`${probe}`.trim() === 'closed') return true;
-        await new Promise((r) => setTimeout(r, intervalMs));
-      }
-      return false;
-    },
+    waitForSshPortClosed: ({ host, port = 22, timeoutMs = 3 * 60 * 1000, intervalMs = 3000 }) =>
+      waitForPort({ host, port, open: false, timeoutMs, intervalMs }),
 
     /**
      * Orchestrates a non-interactive, key-only SSH session against a freshly

package/src/client-builder/client-build.js

@@ -23,12 +23,81 @@ import { shellExec } from '../server/process.js';
 import { SitemapStream, streamToPromise } from 'sitemap';
 import { Readable } from 'stream';
 import { buildIcons } from './client-icons.js';
+import { statusPageBuildSegment } from '../server/underpost-gateway.js';
 import Underpost from '../index.js';
 import { buildDocs } from './client-build-docs.js';
 import { ssrFactory } from './ssr.js';
 
 // Static Site Generation (SSG)
 
+const STATUS_PAGE_VIEW_PATH = /^\/([1-5]\d{2})$/;
+
+// Views a route intercepts before the workload sees the request. They are
+// declared by the flag that already marks them as the app's default for that
+// condition, so a new one becomes edge-served by adding its flag here rather
+// than by naming its path in a second place.
+const INTERCEPT_VIEW_FLAGS = ['maintenanceDefault', 'offlineDefault'];
+
+/**
+ * Resolves the SSR views that render an HTTP status page into the static
+ * artifacts they build to. A view is a status page when its route path is a
+ * bare status code (`/404`, `/500`, `/503`), which the build writes to
+ * `<path>/index.html` inside the served bundle.
+ *
+ * Single source of truth for PWA status-page routing: this build writes the
+ * artifact, and `deploy --build-manifest` points its HTTPRoute rules at the
+ * same resolved URL — neither side hardcodes a status code.
+ * @function statusPageRoutesFactory
+ * @param {Array<object>} [views] - SSR view entries from `conf.ssr.json`.
+ * @param {string} [proxyPath] - The client's proxy sub-path (`/`, `/peer`, ...).
+ * @returns {Array<{status: string, routePath: string, indexUrl: string, title: string, client: string}>}
+ *   One entry per status view, in declaration order.
+ * @memberof clientBuild
+ */
+const statusPageRoutesFactory = ({ views = [], proxyPath = '/' } = {}) => {
+  const prefix = !proxyPath || proxyPath === '/' ? '' : proxyPath.replace(/\/$/, '');
+  return (Array.isArray(views) ? views : [])
+    .map((view) => ({ view, status: STATUS_PAGE_VIEW_PATH.exec(view?.path || '')?.[1] }))
+    .filter(({ status }) => status !== undefined)
+    .map(({ view, status }) => ({
+      status,
+      routePath: `${prefix}${view.path}`,
+      indexUrl: `${prefix}${view.path}/index.html`,
+      title: view.title,
+      client: view.client,
+    }));
+};
+
+/**
+ * Resolves the SSR views a gateway route intercepts and serves statically —
+ * the maintenance and offline documents. They carry no request-time logic, so
+ * the workload never needs to see them; the same build that writes the artifact
+ * hands `deploy --build-manifest` the URL its HTTPRoute rule targets.
+ * @function staticContextRoutesFactory
+ * @param {Array<object>} [views] - SSR view entries from `conf.ssr.json`.
+ * @param {string} [proxyPath] - The client's proxy sub-path (`/`, `/peer`, ...).
+ * @returns {Array<{context: string, routePath: string, indexUrl: string, title: string, client: string}>}
+ *   One entry per intercepted view, in declaration order.
+ * @memberof clientBuild
+ */
+const staticContextRoutesFactory = ({ views = [], proxyPath = '/' } = {}) => {
+  const prefix = !proxyPath || proxyPath === '/' ? '' : proxyPath.replace(/\/$/, '');
+  return (Array.isArray(views) ? views : [])
+    .filter(
+      (view) =>
+        view?.path &&
+        !STATUS_PAGE_VIEW_PATH.test(view.path) &&
+        INTERCEPT_VIEW_FLAGS.some((flag) => view[flag] === true),
+    )
+    .map((view) => ({
+      context: view.path.replace(/^\/+|\/+$/g, ''),
+      routePath: `${prefix}${view.path}`,
+      indexUrl: `${prefix}${view.path}/index.html`,
+      title: view.title,
+      client: view.client,
+    }));
+};
+
 /**
  * Recursively copies files from source to destination, but only files that don't exist in destination.
  * @function copyNonExistingFiles
@@ -742,14 +811,12 @@ const buildClient = async (
       }
 
       if (views) {
-        if (
-          !(
-            enableLiveRebuild &&
-            !options.liveClientBuildPaths.find(
-              (p) => p.srcBuildPath.startsWith(`./src/client/ssr`) || p.srcBuildPath.slice(-9) === '.index.js',
-            )
+        if (!(
+          enableLiveRebuild &&
+          !options.liveClientBuildPaths.find(
+            (p) => p.srcBuildPath.startsWith(`./src/client/ssr`) || p.srcBuildPath.slice(-9) === '.index.js',
           )
-        )
+        ))
           for (const view of views) {
             const buildPath = `${
               rootClientPath[rootClientPath.length - 1] === '/' ? rootClientPath.slice(0, -1) : rootClientPath
@@ -977,6 +1044,8 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
         // when the network is unreachable.
         const ssrClientConf = confSSR[getCapVariableName(client)] || {};
         const ssrViews = Array.isArray(ssrClientConf.views) ? ssrClientConf.views : [];
+        const statusPageRoutes = statusPageRoutesFactory({ views: ssrViews, proxyPath: path });
+        if (statusPageRoutes.length > 0) logger.info('ssr status page routes', statusPageRoutes);
         const PRE_CACHED_RESOURCES = [];
         let offlineFallbackUrl = null;
         let maintenanceFallbackUrl = null;
@@ -999,9 +1068,16 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
             renderApi: { JSONweb },
           });
 
-          const buildPath = `${
-            rootClientPath[rootClientPath.length - 1] === '/' ? rootClientPath.slice(0, -1) : rootClientPath
-          }${view.path === '/' ? view.path : `${view.path}/`}`;
+          // A status view is built under `status-pages/<status>/`, not on its own
+          // `/<status>` route: the gateway serves it by intercepting the
+          // runtime's error, and a document on that route would give the runtime
+          // a page of its own to serve or redirect to for the same condition.
+          const statusCode = statusPageRoutes.find((route) => route.routePath === `${proxyPrefix}${view.path}`)?.status;
+          const clientRoot =
+            rootClientPath[rootClientPath.length - 1] === '/' ? rootClientPath.slice(0, -1) : rootClientPath;
+          const buildPath = statusCode
+            ? `${clientRoot}/${dir.dirname(statusPageBuildSegment(statusCode))}/`
+            : `${clientRoot}${view.path === '/' ? view.path : `${view.path}/`}`;
 
           const indexUrl = buildIndexUrl(view.path);
           if (view.offlineDefault) {
@@ -1089,4 +1165,11 @@ ${swTransformedJs}`,
   }
 };
 
-export { buildClient, copyNonExistingFiles, unzipClientBuild, mergeClientBuildZip };
+export {
+  buildClient,
+  copyNonExistingFiles,
+  unzipClientBuild,
+  mergeClientBuildZip,
+  staticContextRoutesFactory,
+  statusPageRoutesFactory,
+};

package/src/client-builder/ssr.js

@@ -9,9 +9,8 @@ import vm from 'node:vm';
 
 import Underpost from '../index.js';
 
-import { srcFormatted, JSONweb } from './client-formatted.js';
+import { srcFormatted } from './client-formatted.js';
 import { loggerFactory } from '../server/logger.js';
-import { getRootDirectory } from '../server/process.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -47,78 +46,33 @@ const sanitizeHtml = (res, req, html) => {
 };
 
 /**
- * Factory function to create Express middleware for handling 404 and 500 errors.
- * It generates server-side rendered HTML for these error pages. If static error pages exist, it redirects to them.
- * @param {object} options - The options for creating the middleware.
- * @param {object} options.app - The Express app instance.
- * @param {string} options.directory - The directory for the instance's static files.
- * @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.
+ * Creates the Express middleware that terminates an unmatched request and an
+ * unhandled error.
+ *
+ * Both return a bare status and nothing else. Status page delivery belongs to
+ * the edge: the gateway intercepts the status and serves the declared document
+ * from `underpost-gateway`, preserving this response's code and the client's
+ * URI. A runtime that rendered its own page, redirected to one, or fetched one
+ * over HTTP would be competing with that — and would be the only one of the
+ * three runtimes doing so.
+ * @param {string} [path] - The instance's proxy sub-path, used only to alias `/home`.
+ * @returns {Promise<{error500: Function, error400: Function}>} The two terminators.
  * @memberof ServerSideRendering
  */
-const ssrMiddlewareFactory = async ({ app, directory, rootHostPath, path }) => {
-  const Render = await ssrFactory();
-  const ssrPath = path === '/' ? path : `${path}/`;
-
-  // Build default html src for 404 and 500
-
-  const defaultHtmlSrc404 = Render({
-    title: '404 Not Found',
-    ssrPath,
-    ssrHeadComponents: '',
-    ssrBodyComponents: (await ssrFactory(`./src/client/ssr/body/404.js`))(),
-    renderPayload: {
-      apiBasePath: process.env.BASE_API,
-      version: Underpost.version,
-    },
-    renderApi: {
-      JSONweb,
-    },
-  });
-  const path404 = `${directory ? directory : `${getRootDirectory()}${rootHostPath}`}/404/index.html`;
-  const page404 = fs.existsSync(path404) ? `${path === '/' ? '' : path}/404` : undefined;
-
-  const defaultHtmlSrc500 = Render({
-    title: '500 Server Error',
-    ssrPath,
-    ssrHeadComponents: '',
-    ssrBodyComponents: (await ssrFactory(`./src/client/ssr/body/500.js`))(),
-    renderPayload: {
-      apiBasePath: process.env.BASE_API,
-      version: Underpost.version,
-    },
-    renderApi: {
-      JSONweb,
-    },
-  });
-  const path500 = `${directory ? directory : `${getRootDirectory()}${rootHostPath}`}/500/index.html`;
-  const page500 = fs.existsSync(path500) ? `${path === '/' ? '' : path}/500` : undefined;
-
-  return {
-    error500: function (err, req, res, next) {
-      logger.error(err, err.stack);
-      if (page500) return res.status(500).redirect(page500);
-      else {
-        res.set('Content-Type', 'text/html');
-        return res.status(500).send(sanitizeHtml(res, req, defaultHtmlSrc500));
-      }
-    },
-    error400: function (req, res, next) {
-      // if /<path>/home redirect to /<path>
-      const homeRedirectPath = `${path === '/' ? '' : path}/home`;
-      if (req.url.startsWith(homeRedirectPath)) {
-        const redirectUrl = req.url.replace('/home', '');
-        return res.redirect(redirectUrl.startsWith('/') ? redirectUrl : `/${redirectUrl}`);
-      }
-
-      if (page404) return res.status(404).redirect(page404);
-      else {
-        res.set('Content-Type', 'text/html');
-        return res.status(404).send(sanitizeHtml(res, req, defaultHtmlSrc404));
-      }
-    },
-  };
-};
+const ssrMiddlewareFactory = async ({ path = '/' } = {}) => ({
+  error500: function (err, req, res, next) {
+    logger.error(err, err.stack);
+    return res.sendStatus(500);
+  },
+  error400: function (req, res, next) {
+    // `/<path>/home` is an alias of `/<path>`, not a missing route.
+    const homeRedirectPath = `${path === '/' ? '' : path}/home`;
+    if (req.url.startsWith(homeRedirectPath)) {
+      const redirectUrl = req.url.replace('/home', '');
+      return res.redirect(redirectUrl.startsWith('/') ? redirectUrl : `/${redirectUrl}`);
+    }
+    return res.sendStatus(404);
+  },
+});
 
 export { ssrMiddlewareFactory, ssrFactory, sanitizeHtml };