underpost 3.2.80 → 3.3.0

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
@@ -456,6 +525,7 @@ const defaultSitemapXsl = `<?xml version="1.0" encoding="UTF-8"?>
  * @param {string|number} options.split - Optional zip split size in MB.
  * @param {boolean} options.fullBuild - Whether to perform a full build.
  * @param {boolean} options.iconsBuild - Whether to build icons.
+ * @param {boolean} options.ssrOnly - Whether to rebuild only views defined in `conf.ssr.json`.
  * @returns {Promise<void>} - Promise that resolves when the build is complete.
  * @throws {Error} - If the build fails.
  * @memberof clientBuild
@@ -479,6 +549,7 @@ const buildClient = async (
   const packageData = JSON.parse(fs.readFileSync(`./package.json`, 'utf8'));
   const acmeChallengePath = `/.well-known/acme-challenge`;
   const publicPath = `./public`;
+  const ssrOnly = options.ssrOnly === true;
 
   /**
    * @async
@@ -622,11 +693,11 @@ const buildClient = async (
         ? `${directory}${acmeChallengePath}`
         : `${publicPath}/${host}${acmeChallengePath}`;
 
-      if (!enableLiveRebuild) buildAcmeChallengePath(acmeChallengeFullPath);
+      if (!enableLiveRebuild && !ssrOnly) buildAcmeChallengePath(acmeChallengeFullPath);
 
       if (redirect || disabledRebuild) continue;
 
-      if (fullBuildEnabled)
+      if (fullBuildEnabled && !ssrOnly)
         await fullBuild({
           path,
           logger,
@@ -641,7 +712,7 @@ const buildClient = async (
           publicCopyNonExistingFiles,
         });
 
-      if (components)
+      if (!ssrOnly && components)
         for (const module of Object.keys(components)) {
           if (!fs.existsSync(`${rootClientPath}/components/${module}`))
             fs.mkdirSync(`${rootClientPath}/components/${module}`, { recursive: true });
@@ -664,7 +735,7 @@ const buildClient = async (
           }
         }
 
-      if (services) {
+      if (!ssrOnly && services) {
         for (const module of services) {
           if (!fs.existsSync(`${rootClientPath}/services/${module}`))
             fs.mkdirSync(`${rootClientPath}/services/${module}`, { recursive: true });
@@ -727,7 +798,9 @@ const buildClient = async (
       const swSrcPath = `./src/client/sw/core.sw.js`;
       const swPublicPath = `${rootClientPath}/sw.js`;
       const swShouldRebuild =
-        views && !(enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === swSrcPath));
+        !ssrOnly &&
+        views &&
+        !(enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === swSrcPath));
       // Transformed SW JS is held in memory; it gets prepended with renderPayload
       // and written once below, after PRE_CACHED_RESOURCES are known.
       let swTransformedJs = '';
@@ -741,7 +814,7 @@ const buildClient = async (
         });
       }
 
-      if (views) {
+      if (!ssrOnly && views) {
         if (
           !(
             enableLiveRebuild &&
@@ -916,7 +989,7 @@ const buildClient = async (
             );
           }
       }
-      if (!enableLiveRebuild && siteMapLinks.length > 0) {
+      if (!ssrOnly && !enableLiveRebuild && siteMapLinks.length > 0) {
         const hasSitemapTemplate = fs.existsSync(`${rootClientPath}/sitemap`);
         const sitemapBaseUrl = `https://${host}${path === '/' ? '' : path}`;
         // Create a stream to write to — omit xslUrl so we can inject a relative href below
@@ -953,7 +1026,7 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
         );
       }
 
-      if (fullBuildEnabled && docs) {
+      if (!ssrOnly && fullBuildEnabled && docs) {
         await buildDocs({
           host,
           path,
@@ -977,6 +1050,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 +1074,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) {
@@ -1052,7 +1134,7 @@ ${swTransformedJs}`,
           );
         }
       }
-      if (!enableLiveRebuild && options.buildZip) {
+      if (!ssrOnly && !enableLiveRebuild && options.buildZip) {
         logger.warn('build zip', rootClientPath);
 
         if (!fs.existsSync('./build')) fs.mkdirSync('./build');
@@ -1089,4 +1171,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 };