react-cheminfo 0.64.0 → 0.65.0

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,

package/src/server/toolSiteServer.ts

@@ -0,0 +1,127 @@
+import type { FastifyInstance, FastifyServerOptions } from 'fastify';
+
+import { siteById } from '../ecosystem/core/lookup.ts';
+import type { SiteId } from '../ecosystem/core/sites.ts';
+
+import type { ServerConfig } from './config.ts';
+import type { ListenSiteOptions } from './listenSite.ts';
+import { listenSite } from './listenSite.ts';
+import { readRepositoryVersion } from './repositoryVersion.ts';
+import { DEFAULT_RESERVED } from './routeOptions.ts';
+import { staticSite } from './staticSite.ts';
+
+/** What a site's API is registered with. */
+export interface ToolSiteContext {
+  /** The site, as `ECOSYSTEM_SITES` names it. */
+  siteId: SiteId;
+  /** Its host, `osiris.cheminfo.org`: what the tool server and its documentation are called. */
+  name: string;
+  /** The release the repository is at. */
+  version: string;
+  /** The configuration the server was built with. */
+  config: ServerConfig;
+}
+
+/** Options of {@link toolSiteServer}. */
+export interface ToolSiteServerOptions {
+  /** The site, as `ECOSYSTEM_SITES` names it. */
+  siteId: SiteId;
+  /** The configuration, from `readServerConfig`. */
+  config: ServerConfig;
+  /**
+   * Register the API beside the pages: the tool routes of
+   * `cheminfo-mcp-server` under `/v1`, their documentation at `/docs`.
+   */
+  registerApi: (
+    app: FastifyInstance,
+    context: ToolSiteContext,
+  ) => void | Promise<void>;
+  /**
+   * Addresses the site does not have any more, and the one that does their
+   * work; the query is carried over.
+   * @default {}
+   */
+  redirects?: Readonly<Record<string, string>>;
+  /**
+   * Whether, and how, Fastify logs.
+   * @default true
+   */
+  logger?: FastifyServerOptions['logger'];
+  /**
+   * Address prefixes the API answers, which never answer a page.
+   * @default ['/v1/', '/docs']
+   */
+  reserved?: readonly string[];
+  /**
+   * The release the API reports.
+   * @default the root `package.json` of the repository the process runs in
+   */
+  version?: string;
+}
+
+/**
+ * Build a tool site's server without listening: the API the site registers,
+ * then the same build the static host serves, by the static hosts' rules.
+ *
+ * The page never calls the API — it computes in the browser — so the server only
+ * adds: the tools under `/v1` for chats and MCP clients, documented at `/docs`.
+ *
+ *   const app = await toolSiteServer({
+ *     siteId: 'osiris',
+ *     config,
+ *     registerApi: (app, { name, version }) => registerTools(app, name, version),
+ *   });
+ * @param options - The site, its configuration and its API.
+ * @returns The server, ready to listen or to be injected in tests.
+ */
+export async function toolSiteServer(
+  options: ToolSiteServerOptions,
+): Promise<FastifyInstance> {
+  const {
+    siteId,
+    config,
+    registerApi,
+    redirects = {},
+    logger = true,
+    reserved = DEFAULT_RESERVED,
+  } = options;
+  // An optional peer, installed only by a site that has a server.
+  const { fastify } = await import('fastify');
+  const app = fastify({ logger, trustProxy: config.trustProxy });
+  const version = options.version ?? readRepositoryVersion(process.cwd());
+  await registerApi(app, {
+    siteId,
+    name: siteById(siteId).host,
+    version,
+    config,
+  });
+  await app.register(staticSite, {
+    root: config.root,
+    trackingScript: config.trackingScript,
+    redirects,
+    reserved,
+    basePath: config.basePath,
+  });
+  return app;
+}
+
+/**
+ * Build a site's server from its configuration, listen where it says, and close
+ * cleanly when the container is stopped — the whole of a `main.ts`:
+ *
+ *   await startToolServer(buildServer, readServerConfig(process.env, SITE));
+ * @param build - Builds the server, e.g. with {@link toolSiteServer}.
+ * @param config - The configuration, from `readServerConfig`.
+ * @param options - What else to stop, and on which signals.
+ * @returns The server, listening.
+ * @throws {Error} When the server cannot listen, after it has been closed.
+ */
+export async function startToolServer(
+  build: (config: ServerConfig) => FastifyInstance | Promise<FastifyInstance>,
+  config: ServerConfig,
+  options: Pick<ListenSiteOptions, 'onClose' | 'signals'> = {},
+): Promise<FastifyInstance> {
+  const app = await build(config);
+  await listenSite(app, { ...options, port: config.port, host: config.host });
+  return app;
+}

package/src/server/trustProxy.ts

@@ -0,0 +1,32 @@
+/** A value that is only digits: a hop count. */
+const HOP_COUNT = /^\d+$/;
+
+/**
+ * Read which reverse proxies a deployment names, for Fastify's `trustProxy`.
+ *
+ * Behind a proxy, `request.ip` is the proxy's address on every request and
+ * `request.protocol` reads `http` for an HTTPS client, so the variable names the
+ * proxy whose `X-Forwarded-For` is believed: an address, a CIDR range, or a
+ * comma-separated list of either. `true` believes any peer, which is only safe
+ * when the port is unreachable except through the proxy.
+ *
+ * A hop count is refused. Fastify 5.12.7 and later trust nothing for a number,
+ * since a hop count cannot tell the proxy from a client, so the service would
+ * silently log the proxy's address again — and a function over the hop, the
+ * usual way around it, believes any peer that sends enough addresses.
+ * @param value - `TRUST_PROXY`, as written.
+ * @returns The proxies as written, `true` to believe any peer, or `false` when
+ * the variable is unset, blank or `false`.
+ * @throws {Error} When the value is a hop count.
+ */
+export function parseTrustProxy(value: string | undefined): boolean | string {
+  const text = value?.trim();
+  if (!text || text.toLowerCase() === 'false') return false;
+  if (text.toLowerCase() === 'true') return true;
+  if (HOP_COUNT.test(text)) {
+    throw new Error(
+      `TRUST_PROXY=${text} is a hop count, which trusts nothing. Name the proxy's address or CIDR instead.`,
+    );
+  }
+  return text;
+}

package/src/server/types.ts

@@ -0,0 +1,25 @@
+import type { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import type {
+  FastifyBaseLogger,
+  FastifyInstance,
+  RawReplyDefaultExpression,
+  RawRequestDefaultExpression,
+  RawServerDefault,
+} from 'fastify';
+
+/**
+ * A Fastify instance whose routes are typed from their TypeBox schemas: the
+ * `body`, `params`, `querystring` and response of a route registered on it are
+ * inferred. A route module takes it as its parameter, and the server is built
+ * with `fastify(options).withTypeProvider<TypeBoxTypeProvider>()`.
+ *
+ * Types only: `@fastify/type-provider-typebox` is an optional peer, installed by
+ * the backends that type their routes this way.
+ */
+export type FastifyTyped = FastifyInstance<
+  RawServerDefault,
+  RawRequestDefaultExpression,
+  RawReplyDefaultExpression,
+  FastifyBaseLogger,
+  TypeBoxTypeProvider
+>;

package/src/server.ts

@@ -5,3 +5,43 @@ export {
   listSiteFiles,
   resolveAddress,
 } from './server/siteFiles.ts';
+export type {
+  ServerConfig,
+  ServerConfigOptions,
+  ServerEnvironment,
+} from './server/config.ts';
+export { readHttpAddress, readServerConfig } from './server/config.ts';
+export type { ReadEnvNumberOptions } from './server/envNumber.ts';
+export { readEnvNumber } from './server/envNumber.ts';
+export type { HealthRouteOptions } from './server/healthRoute.ts';
+export { healthRoute } from './server/healthRoute.ts';
+export type { ListenSiteOptions } from './server/listenSite.ts';
+export { listenSite } from './server/listenSite.ts';
+export { readRepositoryVersion } from './server/repositoryVersion.ts';
+export { readRouteTable } from './server/routeTable.ts';
+export { spaSite } from './server/spaSite.ts';
+export type {
+  SpaPage,
+  SpaSiteOptions,
+  SpaStructuredData,
+} from './server/spaSiteOptions.ts';
+export type {
+  ToolSiteContext,
+  ToolSiteServerOptions,
+} from './server/toolSiteServer.ts';
+export { startToolServer, toolSiteServer } from './server/toolSiteServer.ts';
+export { parseTrustProxy } from './server/trustProxy.ts';
+export type { FastifyTyped } from './server/types.ts';
+export type {
+  AnswerAddresses,
+  AnswerAddressesInput,
+} from './server/answerAddresses.ts';
+export {
+  answerAddresses,
+  joinAddress,
+  viewOrigins,
+} from './server/answerAddresses.ts';
+export type { CardMetaOptions, PageAnswer } from './server/cardMeta.ts';
+export { cardMeta, pageAnswer } from './server/cardMeta.ts';
+export type { SiteViewOptions } from './server/siteView.ts';
+export { siteView } from './server/siteView.ts';

package/src/share/core/config.ts

@@ -41,9 +41,12 @@ export function parseShareConfig<
 >(search: string, vocabulary: ShareVocabulary<Codecs>): ShareConfig<Codecs> {
   const values = firstValues(parseQuery(search));
   const embed = values.get(EMBED_PARAM);
+  const asked = splitHidden(values.get(HIDE_PARAM));
   return {
-    embed: embed !== undefined && embed !== '0',
-    hidden: orderHidden(splitHidden(values.get(HIDE_PARAM)), vocabulary.parts),
+    embed:
+      (embed !== undefined && embed !== '0') ||
+      namesAny(asked, vocabulary.legacyEmbedParts ?? []),
+    hidden: orderHidden(asked, vocabulary.parts),
     params: readParams(values, vocabulary.params) as ShareParamValues<Codecs>,
   };
 }
@@ -154,6 +157,46 @@ export function suggestedShareConfig<
   return { ...parseShareConfig('', vocabulary), embed: true, hidden };
 }
 
+/**
+ * Read the parts a `?hide=` value switches off, for a page that holds its
+ * query decoded rather than as a string.
+ * @param raw - The raw value, comma separated; `undefined` when absent.
+ * @param parts - The hideable parts, in the vocabulary order.
+ * @returns The keys of the parts named, in that order; a key the vocabulary
+ * does not list is dropped, so a hand-written link cannot hide what it cannot
+ * name.
+ */
+export function readHiddenParts(
+  raw: string | undefined,
+  parts: readonly HideablePart[],
+): readonly string[] {
+  return orderHidden(splitHidden(raw), parts);
+}
+
+/**
+ * Write a `?hide=` value in the vocabulary order, so one selection always
+ * produces one link.
+ * @param hidden - The keys switched off, in any order and any collection.
+ * @param parts - The hideable parts, in the vocabulary order.
+ * @returns The value, empty when nothing the vocabulary lists is switched off.
+ */
+export function formatHiddenParts(
+  hidden: Iterable<string>,
+  parts: readonly HideablePart[],
+): string {
+  return orderHidden(new Set(hidden), parts).join(',');
+}
+
+function namesAny(
+  asked: ReadonlySet<string>,
+  keys: readonly string[],
+): boolean {
+  for (const key of keys) {
+    if (asked.has(key)) return true;
+  }
+  return false;
+}
+
 function splitHidden(raw: string | undefined): ReadonlySet<string> {
   const asked = new Set<string>();
   if (raw === undefined) return asked;

package/src/share/core/index.ts

@@ -3,9 +3,11 @@ export {
   EMBED_PARAM,
   HIDE_PARAM,
   applyShareConfig,
+  formatHiddenParts,
   isHidden,
   isShareConfigured,
   parseShareConfig,
+  readHiddenParts,
   suggestedShareConfig,
   visibleShareParts,
 } from './config.ts';
@@ -17,6 +19,8 @@ export {
   sharePreviewSize,
 } from './devices.ts';
 export { escapeAttribute, escapeText } from './escape.ts';
+export type { KeySetParamOptions } from './keySetParam.ts';
+export { keySetParam } from './keySetParam.ts';
 export type { ShareRegion } from './regions.ts';
 export {
   SHARE_REGIONS_MESSAGE,