react-cheminfo 0.64.1 → 0.65.0

package/src/server/spaPages.ts

@@ -0,0 +1,179 @@
+import { withoutQueryOrFragment } from '../router/core/address.ts';
+import { stripBasePath } from '../router/core/basePath.ts';
+import { noscriptIndex } from '../seo/core/noscript.ts';
+import { pageHeadTags } from '../seo/core/pageMeta.ts';
+import type { PageContent } from '../seo/core/pageProse.ts';
+import type { RouteMeta } from '../seo/core/routes.ts';
+import { pageMetaFor, routeFor } from '../seo/core/routes.ts';
+import { mountPathOf, resolveSite } from '../seo/core/siteFiles.ts';
+import { structuredDataScript } from '../seo/core/structuredData.ts';
+import {
+  PAGE_BODY_MARKER,
+  PAGE_HEAD_MARKER,
+  fill,
+} from '../seo/core/template.ts';
+import { injectTrackingScript } from '../seo/core/trackingScript.ts';
+
+import type { SpaSiteOptions } from './spaSiteOptions.ts';
+
+/** The page an address is answered with. */
+export interface SpaAnswer {
+  /** The page, its head and its crawl path written for the address. */
+  html: string;
+  /** Whether the app routes the address, rather than drawing its "not found". */
+  known: boolean;
+}
+
+/** Writes the page every address of a single-page app is answered with. */
+export interface SpaPages {
+  /**
+   * The page for one address.
+   * @param url - The address asked for, query string included.
+   * @param origin - Where the site is served, mount path included.
+   * @returns The page, and whether the app routes the address.
+   */
+  answer: (url: string, origin: string) => Promise<SpaAnswer>;
+}
+
+/**
+ * Prepare the pages of a single-page app from its built template: the snippet
+ * is put in once, the crawl path is written once per page and kept, and the
+ * head — which names the origin the request arrived on — per request.
+ * @param template - The built `index.html`.
+ * @param routes - Every address the app routes itself.
+ * @param options - The site, and how its pages are written.
+ * @returns The page writer.
+ * @throws {Error} When an indexed site's template carries no head or body
+ * marker, rather than failing on every request afterwards.
+ */
+export function createSpaPages(
+  template: string,
+  routes: readonly RouteMeta[],
+  options: SpaSiteOptions,
+): SpaPages {
+  const site = resolveSite(options.site);
+  const indexed = options.indexed ?? true;
+  const page = injectTrackingScript(template, options.trackingScript);
+  if (indexed) {
+    for (const marker of [PAGE_HEAD_MARKER, PAGE_BODY_MARKER]) {
+      if (!page.includes(marker)) {
+        throw new Error(`the page carries no ${marker}`);
+      }
+    }
+  }
+  const write = indexed ? fill : fillIfPresent;
+  const bodyFor = keptBodies(options.maxCachedPages ?? 2000);
+  const crawled = options.noscript?.routes ?? indexedRoutes(routes);
+  const structured = structuredData(routes, options);
+
+  return {
+    async answer(url, origin) {
+      const mount = mountPathOf({ site, origin });
+      const named = await options.page?.(url);
+      const meta = named?.meta ?? pageMetaFor(routes, url, mount);
+      const content: PageContent = named?.content ?? {
+        heading: meta.title,
+        paragraphs: [meta.description],
+      };
+      const body = bodyFor(
+        meta.path,
+        `${mount}\n${JSON.stringify(content)}`,
+        () =>
+          write(
+            page,
+            PAGE_BODY_MARKER,
+            noscriptIndex({
+              ...options.noscript,
+              site,
+              origin,
+              routes: crawled,
+              content,
+            }),
+          ),
+      );
+      const served = indexed ? meta : { ...meta, indexed: false };
+      const tags = pageHeadTags({
+        site,
+        routes: [served],
+        origin,
+        url: served.path,
+        image: options.image,
+      });
+      const script = indexed ? structured(origin) : undefined;
+      const head = script === undefined ? tags : `${tags}\n${script}`;
+      return {
+        html: write(body, PAGE_HEAD_MARKER, head),
+        known:
+          named !== undefined ||
+          isKnown(routes, url, mount, options.knownRoute),
+      };
+    },
+  };
+}
+
+function indexedRoutes(routes: readonly RouteMeta[]): RouteMeta[] {
+  return routes.filter((route) => route.indexed !== false);
+}
+
+function isKnown(
+  routes: readonly RouteMeta[],
+  url: string,
+  mount: string,
+  knownRoute: ((path: string) => boolean) | undefined,
+): boolean {
+  const path = withoutQueryOrFragment(url);
+  const own = stripBasePath(mount, path);
+  if (knownRoute !== undefined) return knownRoute(own);
+  return (
+    routeFor(routes, own) !== undefined || routeFor(routes, path) !== undefined
+  );
+}
+
+// The block is the same on every page of an origin, so the one origin a
+// configured site is served at is written once rather than per request.
+function structuredData(
+  routes: readonly RouteMeta[],
+  options: SpaSiteOptions,
+): (origin: string) => string | undefined {
+  const option = options.structuredData ?? {};
+  if (option === false) return () => undefined;
+  if (typeof option === 'function') return option;
+  let last: { origin: string; script: string } | undefined;
+  return (origin) => {
+    if (last?.origin !== origin) {
+      const script = structuredDataScript({
+        ...option,
+        site: options.site,
+        routes,
+        origin,
+      });
+      last = { origin, script };
+    }
+    return last.script;
+  };
+}
+
+// The crawl path of a page is kept under its canonical path, and rebuilt when
+// what the page says changes — a course renamed, a compound read again.
+function keptBodies(
+  limit: number,
+): (path: string, key: string, build: () => string) => string {
+  const kept = new Map<string, { key: string; html: string }>();
+  return (path, key, build) => {
+    const entry = kept.get(path);
+    if (entry?.key === key) return entry.html;
+    const html = build();
+    if (limit <= 0) return html;
+    kept.delete(path);
+    if (kept.size >= limit) {
+      const oldest = kept.keys().next();
+      if (oldest.done !== true) kept.delete(oldest.value);
+    }
+    kept.set(path, { key, html });
+    return html;
+  };
+}
+
+function fillIfPresent(html: string, marker: string, content: string): string {
+  return html.includes(marker) ? fill(html, marker, content) : html;
+}

package/src/server/spaSite.ts

@@ -0,0 +1,216 @@
+import { readFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+
+import type { SiteRecord } from '../ecosystem/core/sites.ts';
+import { robotsTxt } from '../seo/core/robots.ts';
+import type { RouteMeta } from '../seo/core/routes.ts';
+import { originOf, resolveSite, sitemapXml } from '../seo/core/siteFiles.ts';
+
+import { healthRoute } from './healthRoute.ts';
+import {
+  BUNDLE_CACHE,
+  DEFAULT_RESERVED,
+  HIDDEN,
+  PAGE_CACHE,
+} from './routeOptions.ts';
+import { readRouteTable } from './routeTable.ts';
+import { isHashedBundle, listSiteFiles } from './siteFiles.ts';
+import type { SpaPages } from './spaPages.ts';
+import { createSpaPages } from './spaPages.ts';
+import type { SpaSiteOptions } from './spaSiteOptions.ts';
+
+/** The page the build wrote, which is a template and never served as it is. */
+const INDEX = 'index.html';
+
+/** What keeps a page out of the index without stopping its crawl. */
+const NO_INDEX = 'noindex, nofollow';
+
+/** The policy of a site nobody is meant to find. */
+const DISALLOW_ALL = 'User-agent: *\nDisallow: /\n';
+
+/**
+ * Serve a single-page app from the backend that answers its API.
+ *
+ * Every address the app routes itself is the built page, with the head of that
+ * address — its title, description, canonical and card — and a crawl path of
+ * its own in its body, so a crawler that runs no script still tells the pages
+ * apart. The `TRACKING_SCRIPT` snippet is in every page. `sitemap.xml` and
+ * `robots.txt` are written from the route table, at the address the site is
+ * served at; the files of the build are served as they are, `assets/` kept for
+ * a year; an address under `reserved` is the API's own 404; and `/health`
+ * answers the deploy script.
+ *
+ *   await app.register(spaSite, {
+ *     root: 'frontend/dist',
+ *     site: 'derepflow',
+ *     siteUrl: process.env.SITE_URL,
+ *     trackingScript: process.env.TRACKING_SCRIPT,
+ *   });
+ *
+ * Without a build — a server started before the frontend was built — it logs
+ * it and serves the API alone.
+ * @param fastify - The server.
+ * @param options - The build, the site, and how its pages are written.
+ * @throws {Error} When `siteUrl` is not an absolute address, or the page of an
+ * indexed site carries no `<!--cheminfo:head-->` or `<!--cheminfo:body-->`.
+ */
+export async function spaSite(
+  fastify: FastifyInstance,
+  options: SpaSiteOptions,
+): Promise<void> {
+  const {
+    health = true,
+    reserved = DEFAULT_RESERVED,
+    notFoundStatus = 200,
+    indexed = true,
+    siteUrl,
+    robots = DEFAULT_RESERVED,
+    sitemapPaths,
+    setHeaders,
+  } = options;
+  const site = resolveSite(options.site);
+  if (health !== false) {
+    await healthRoute(fastify, health === true ? {} : health);
+  }
+
+  const root = resolve(options.root);
+  const files = await listSiteFiles(root);
+  if (!files?.has(INDEX)) {
+    fastify.log.warn({ root }, 'no built frontend: serving the API alone');
+    return;
+  }
+  const routes = options.routes ?? readRouteTable(root, [homeOf(site)]);
+  const configured = siteUrl?.trim() || undefined;
+  if (configured !== undefined) originOf({ site, origin: configured });
+  const pages = createSpaPages(
+    await readFile(join(root, INDEX), 'utf8'),
+    routes,
+    options,
+  );
+  const originFor = (request: FastifyRequest) =>
+    configured ?? requestOrigin(request, site);
+
+  // An optional peer, installed only by a site that has a server: importing
+  // react-cheminfo/server must not need it.
+  const { default: fastifyStatic } = await import('@fastify/static');
+  await fastify.register(fastifyStatic, {
+    root,
+    serve: false,
+    cacheControl: false,
+    setHeaders: (reply, path) => {
+      const file = relative(root, path).split(sep).join('/');
+      reply.header(
+        'cache-control',
+        isHashedBundle(file) ? BUNDLE_CACHE : PAGE_CACHE,
+      );
+      if (!indexed) reply.header('x-robots-tag', NO_INDEX);
+      setHeaders?.(reply, file);
+    },
+  });
+
+  const sendPage = sender(pages, originFor, { indexed, notFoundStatus });
+  const answer = (request: FastifyRequest, reply: FastifyReply) => {
+    const { pathname, search } = new URL(request.url, 'http://site');
+    if (reserved.some((prefix) => pathname.startsWith(prefix))) {
+      return reply.callNotFound();
+    }
+    if (pathname === `/${INDEX}`) return sendPage(request, reply, `/${search}`);
+    const file = buildFile(files, pathname);
+    if (file !== undefined) return reply.sendFile(file);
+    return sendPage(request, reply, request.url);
+  };
+  fastify.get('/', { schema: HIDDEN }, answer);
+  fastify.get('/*', { schema: HIDDEN }, answer);
+
+  fastify.get('/robots.txt', { schema: HIDDEN }, (request, reply) =>
+    reply
+      .type('text/plain; charset=utf-8')
+      .send(
+        indexed
+          ? robotsTxt({ site, routes, origin: originFor(request) }, robots)
+          : DISALLOW_ALL,
+      ),
+  );
+  fastify.get('/sitemap.xml', { schema: HIDDEN }, async (request, reply) => {
+    if (!indexed) return reply.callNotFound();
+    const paths = (await sitemapPaths?.()) ?? [];
+    const listed: RouteMeta[] = [...routes];
+    for (const path of paths) listed.push({ path, title: '', description: '' });
+    return reply
+      .type('application/xml; charset=utf-8')
+      .send(sitemapXml({ site, routes: listed, origin: originFor(request) }));
+  });
+}
+
+/**
+ * The handler answering an address with its page.
+ * @param pages - The page writer.
+ * @param originFor - Where the site is served, for a request.
+ * @param status - How the answer is labelled.
+ * @param status.indexed - Whether search engines may index the site.
+ * @param status.notFoundStatus - The status of an address the app does not route.
+ * @returns The handler.
+ */
+function sender(
+  pages: SpaPages,
+  originFor: (request: FastifyRequest) => string,
+  status: { indexed: boolean; notFoundStatus: number },
+) {
+  return async (request: FastifyRequest, reply: FastifyReply, url: string) => {
+    const { html, known } = await pages.answer(url, originFor(request));
+    reply.header('cache-control', PAGE_CACHE);
+    if (!status.indexed) reply.header('x-robots-tag', NO_INDEX);
+    return reply
+      .code(known ? 200 : status.notFoundStatus)
+      .type('text/html; charset=utf-8')
+      .send(html);
+  };
+}
+
+/**
+ * The file of the build an address names, never the template.
+ * @param files - The files of the build.
+ * @param pathname - The address, without its query.
+ * @returns The file, or `undefined` when the address is a page.
+ */
+function buildFile(
+  files: ReadonlySet<string>,
+  pathname: string,
+): string | undefined {
+  let path: string;
+  try {
+    path = decodeURIComponent(pathname);
+  } catch {
+    return undefined;
+  }
+  const local = path.replace(/^\/+/, '');
+  if (local === '' || local === INDEX) return undefined;
+  return files.has(local) ? local : undefined;
+}
+
+/**
+ * The origin a request arrived on. The `Host` header is the client's to write,
+ * so one that is not a host falls back to the site's own address rather than
+ * reaching a canonical link.
+ * @param request - The request.
+ * @param site - The site served.
+ * @returns The origin, e.g. `https://pdb.cheminfo.org`.
+ */
+function requestOrigin(request: FastifyRequest, site: SiteRecord): string {
+  const candidate = `${request.protocol}://${request.host}`;
+  return URL.canParse(candidate)
+    ? new URL(candidate).origin
+    : `https://${site.host}`;
+}
+
+/**
+ * The page a site answers when its build wrote no route table.
+ * @param site - The site.
+ * @returns Its home page, titled and described by its tagline.
+ */
+function homeOf(site: SiteRecord): RouteMeta {
+  const title = site.tagline.replace(/\.$/, '');
+  return { path: '/', title, description: site.tagline };
+}

package/src/server/spaSiteOptions.ts

@@ -0,0 +1,133 @@
+import type { FastifyReply } from 'fastify';
+
+import type { SiteId, SiteRecord } from '../ecosystem/core/sites.ts';
+import type { NoscriptText } from '../seo/core/noscript.ts';
+import type { PageContent } from '../seo/core/pageProse.ts';
+import type { RobotsDisallow } from '../seo/core/robots.ts';
+import type { RouteMeta } from '../seo/core/routes.ts';
+import type { StructuredDataOptions } from '../seo/core/structuredData.ts';
+
+import type { HealthRouteOptions } from './healthRoute.ts';
+
+/** A page an address names that the route table does not: a compound, a course. */
+export interface SpaPage {
+  /** Its title, description and canonical path. */
+  meta: RouteMeta;
+  /**
+   * What it says for itself in the crawl path.
+   * @default its title as heading, its description as the paragraph
+   */
+  content?: PageContent;
+}
+
+/** What the structured-data block says beyond the site and its address. */
+export type SpaStructuredData = Omit<
+  StructuredDataOptions,
+  'site' | 'routes' | 'origin' | 'languages'
+>;
+
+/** Options of `spaSite`. */
+export interface SpaSiteOptions {
+  /** The directory holding the built frontend. */
+  root: string;
+  /** The site, named or passed. */
+  site: SiteRecord | SiteId;
+  /**
+   * Every address the frontend routes itself, each with its title and
+   * description.
+   * @default the `routes.json` the build wrote beside the page, or the site's
+   * home page alone
+   */
+  routes?: readonly RouteMeta[];
+  /**
+   * Where the site is served, mount path included, e.g.
+   * `https://learn.cheminfo.org/surge`. Every canonical, card and sitemap address
+   * is built on it. A blank value is unset, as compose forwards `${SITE_URL:-}`.
+   * @default the origin the request arrived on
+   */
+  siteUrl?: string;
+  /**
+   * The analytics snippet, put at the end of the head of every page.
+   * @default undefined - nothing is loaded
+   */
+  trackingScript?: string;
+  /**
+   * Address prefixes another plugin answers, such as the API, which never
+   * answer a page: an unknown address there is the API's own 404.
+   * @default ['/v1/', '/docs']
+   */
+  reserved?: readonly string[];
+  /**
+   * The prose of the crawl path, and the pages it links.
+   * @default the site's name and tagline, linking every indexed route
+   */
+  noscript?: NoscriptText;
+  /**
+   * The structured-data block of every page: what kind of application the site
+   * is, a function writing the whole `<script>` for the origin served (an
+   * author, a citation, a search action), or `false` for none.
+   * @default {} - a free web application, described by the site's tagline
+   */
+  structuredData?: false | SpaStructuredData | ((origin: string) => string);
+  /**
+   * The card a link to a page unfurls into, as an absolute address or a path.
+   * @default '/og.png'
+   */
+  image?: string;
+  /**
+   * Addresses `robots.txt` keeps out of the index, each optionally with the
+   * sentence saying why.
+   * @default ['/v1/', '/docs']
+   */
+  robots?: ReadonlyArray<string | RobotsDisallow>;
+  /**
+   * More addresses the sitemap lists after the route table: one per compound,
+   * per published course.
+   * @default undefined - the route table alone
+   */
+  sitemapPaths?: () => readonly string[] | Promise<readonly string[]>;
+  /**
+   * The page an address names when the route table does not: read from the
+   * database, so `/compound/1234` is indexed under the compound's own name.
+   * `undefined` falls back to the table.
+   * @default undefined - every address is read from the table
+   */
+  page?: (url: string) => SpaPage | undefined | Promise<SpaPage | undefined>;
+  /**
+   * Whether an address is one the app routes, given its path without the query
+   * and without the mount.
+   * @default whether the route table claims it, or `page` named it
+   */
+  knownRoute?: (path: string) => boolean;
+  /**
+   * The status an address the app does not route is answered with. It is
+   * still the page, so the app draws its own "not found", but a crawler is not
+   * handed a soft 404.
+   * @default 200
+   */
+  notFoundStatus?: number;
+  /**
+   * Whether search engines may index the site. An admin site sets `false`:
+   * every answer then carries `X-Robots-Tag: noindex, nofollow`, `robots.txt`
+   * disallows everything, there is no sitemap, and a page without the
+   * `<!--cheminfo:head-->` marker is served as it is.
+   * @default true
+   */
+  indexed?: boolean;
+  /**
+   * How many pages, each with its own crawl path, are kept built.
+   * @default 2000
+   */
+  maxCachedPages?: number;
+  /**
+   * Whether `/health` is answered here, and with what more.
+   * @default true
+   */
+  health?: boolean | HealthRouteOptions;
+  /**
+   * Headers for a file of the build, such as a cross-origin opening for the
+   * decks another site fetches.
+   * @default undefined - the cache headers alone
+   */
+  setHeaders?: (reply: FastifyReply, file: string) => void;
+}

package/src/server/staticSite.ts

@@ -1,15 +1,19 @@
 import { readFile } from 'node:fs/promises';
 import { join, relative, resolve, sep } from 'node:path';
 
-import type {
-  FastifyInstance,
-  FastifyReply,
-  FastifyRequest,
-  FastifySchema,
-} from 'fastify';
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
 
+import { joinBasePath, normalizeBasePath } from '../router/core/basePath.ts';
 import { injectTrackingScript } from '../seo/core/trackingScript.ts';
-
+import { escapeAttribute } from '../share/core/escape.ts';
+
+import { healthRoute } from './healthRoute.ts';
+import {
+  ALLOW_ORIGIN,
+  BUNDLE_CACHE,
+  HIDDEN,
+  PAGE_CACHE,
+} from './routeOptions.ts';
 import { isHashedBundle, listSiteFiles, resolveAddress } from './siteFiles.ts';
 
 /** Options of {@link staticSite}. */
@@ -35,6 +39,15 @@ export interface StaticSiteOptions {
    * @default ['/v1/']
    */
   reserved?: readonly string[];
+  /**
+   * The path the deployment is mounted at, `/osiris` for
+   * `https://www.cheminfo.org/osiris/`, behind a proxy that takes it off before
+   * the request arrives. It is written into the `<base href="/">` of every page
+   * when they are read, and in front of every redirect, so one image serves a
+   * host of its own and a shared one without a rebuild or a copy of the build.
+   * @default '' - the site owns the root of its host
+   */
+  basePath?: string;
 }
 
 /** A page: the file with the snippet in its head, and the tag a browser checks. */
@@ -43,21 +56,8 @@ interface Page {
   etag: string;
 }
 
-/** A page is checked on every visit: it names the bundles of its own build. */
-const PAGE_CACHE = 'no-cache';
-
-/** A bundle is named by its content, so it never changes under its name. */
-const BUNDLE_CACHE = 'public, max-age=31536000, immutable';
-
-/**
- * Every file of a build is public, and a page framed by a sandboxed view runs
- * under an opaque origin, where everything it fetches from its own site is
- * cross-origin: the static hosts open every response, and so does this server.
- */
-const ALLOW_ORIGIN = 'access-control-allow-origin';
-
-/** Kept out of the API's documentation (`@fastify/swagger` reads `hide`). */
-const HIDDEN: FastifySchema & { hide: boolean } = { hide: true };
+/** The `<base>` a build carries, which a mounted deployment rewrites. */
+const ROOT_BASE = /<base\s+href=(?<quote>["'])\/\k<quote>\s*\/?>/i;
 
 /**
  * Serve a site's build from Node, with the rules every static host of the
@@ -81,19 +81,16 @@ export async function staticSite(
 ): Promise<void> {
   const { trackingScript, redirects = {}, reserved = ['/v1/'] } = options;
   const root = resolve(options.root);
+  const basePath = normalizeBasePath(options.basePath ?? '');
 
-  fastify.get(
-    '/health',
-    { logLevel: 'silent', schema: HIDDEN },
-    (_request, reply) => reply.header(ALLOW_ORIGIN, '*').send({ status: 'ok' }),
-  );
+  await healthRoute(fastify);
 
   const files = await listSiteFiles(root);
   if (files === undefined) {
     fastify.log.warn({ root }, 'no built site: serving the API alone');
     return;
   }
-  const pages = await readPages(root, files, trackingScript);
+  const pages = await readPages(root, files, { trackingScript, basePath });
 
   // An optional peer, installed only by a site that has a server: importing
   // react-cheminfo/server must not need it.
@@ -121,7 +118,10 @@ export async function staticSite(
     const destination =
       redirects[pathname] ?? redirects[pathname.replace(/\/$/, '')];
     if (destination !== undefined) {
-      return reply.redirect(`${destination}${search}`, 301);
+      return reply.redirect(
+        `${mountedAddress(basePath, destination)}${search}`,
+        301,
+      );
     }
 
     const file = resolveAddress(files, pathname);
@@ -138,23 +138,29 @@ export async function staticSite(
 }
 
 /**
- * Read every page of the build once, with the snippet in its head.
+ * Read every page of the build once, with the snippet in its head and the
+ * mount in its `<base>`.
  * @param root - The build.
  * @param files - Its files.
- * @param trackingScript - The snippet, if any.
+ * @param stamp - What is written into every page.
+ * @param stamp.trackingScript - The snippet, if any.
+ * @param stamp.basePath - The mount, `''` for none.
  * @returns The pages, by file.
  */
 async function readPages(
   root: string,
   files: ReadonlySet<string>,
-  trackingScript: string | undefined,
+  stamp: { trackingScript: string | undefined; basePath: string },
 ): Promise<Map<string, Page>> {
   const htmlFiles = [...files].filter((file) => file.endsWith('.html'));
   const pages = await Promise.all(
     htmlFiles.map(async (file) => {
-      const html = injectTrackingScript(
-        await readFile(join(root, file), 'utf8'),
-        trackingScript,
+      const html = stampBase(
+        injectTrackingScript(
+          await readFile(join(root, file), 'utf8'),
+          stamp.trackingScript,
+        ),
+        stamp.basePath,
       );
       return [file, { html, etag: await etagOf(html) }] as const;
     }),
@@ -162,6 +168,30 @@ async function readPages(
   return new Map(pages);
 }
 
+/**
+ * Write the mount into the first `<base href="/">` a page carries, as the
+ * container entrypoints of a mounted image do.
+ * @param html - The page.
+ * @param basePath - The mount, `''` for none.
+ * @returns The page, its relative addresses resolving under the mount.
+ */
+function stampBase(html: string, basePath: string): string {
+  if (basePath === '') return html;
+  const tag = `<base href="${escapeAttribute(`${basePath}/`)}" />`;
+  return html.replace(ROOT_BASE, () => tag);
+}
+
+/**
+ * Where a redirect sends the browser: under the mount the proxy took off.
+ * @param basePath - The mount, `''` for none.
+ * @param destination - The address, from the site's own root or absolute.
+ * @returns The address the browser is sent to.
+ */
+function mountedAddress(basePath: string, destination: string): string {
+  if (basePath === '' || !destination.startsWith('/')) return destination;
+  return joinBasePath(basePath, destination);
+}
+
 function sendPage(
   request: FastifyRequest,
   reply: FastifyReply,