react-cheminfo 0.64.0 → 0.65.0

package/src/server/listenSite.ts

@@ -0,0 +1,90 @@
+import type { FastifyInstance } from 'fastify';
+
+/** Options of {@link listenSite}. */
+export interface ListenSiteOptions {
+  /** The port to listen on. */
+  port: number;
+  /**
+   * The interface to listen on.
+   * @default '0.0.0.0' - every interface, as a container needs
+   */
+  host?: string;
+  /**
+   * Run once the server has closed on a signal: stop what the server does not
+   * own itself, such as a scheduler or a write queue started beside it.
+   * @default undefined - nothing more is stopped
+   */
+  onClose?: () => void | Promise<void>;
+  /**
+   * The signals that close the server.
+   * @default ['SIGTERM', 'SIGINT'] - what `docker stop` and a terminal send
+   */
+  signals?: readonly NodeJS.Signals[];
+}
+
+/**
+ * Listen, and close cleanly when the container is stopped.
+ *
+ * On the first signal the server closes — its `onClose` hooks stop the worker
+ * pools it owns — then `onClose` runs. A close that fails is logged and leaves
+ * `process.exitCode` at 1 rather than surfacing as an unhandled rejection, and
+ * the process ends on its own once nothing is left running. A server that
+ * cannot listen is logged, closed and reported the same way.
+ *
+ *   await listenSite(app, { port: config.port, host: config.host });
+ * @param app - The server, built and not yet listening.
+ * @param options - Where to listen, and what else to stop.
+ * @throws {Error} When the server cannot listen, after it has been closed.
+ */
+export async function listenSite(
+  app: FastifyInstance,
+  options: ListenSiteOptions,
+): Promise<void> {
+  const {
+    port,
+    host = '0.0.0.0',
+    onClose,
+    signals = ['SIGTERM', 'SIGINT'],
+  } = options;
+
+  const stop = () => {
+    for (const signal of signals) process.off(signal, stop);
+    void shutDown(app, onClose);
+  };
+  for (const signal of signals) process.once(signal, stop);
+
+  try {
+    await app.listen({ port, host });
+  } catch (error) {
+    for (const signal of signals) process.off(signal, stop);
+    app.log.error(error, `the server could not listen on ${host}:${port}`);
+    process.exitCode = 1;
+    await shutDown(app, onClose);
+    throw error;
+  }
+}
+
+/**
+ * Close the server, then run what else has to stop, reporting a failure of
+ * either through the log and the exit code.
+ * @param app - The server.
+ * @param onClose - What else to stop.
+ */
+async function shutDown(
+  app: FastifyInstance,
+  onClose: (() => void | Promise<void>) | undefined,
+): Promise<void> {
+  try {
+    await app.close();
+  } catch (error) {
+    app.log.error(error, 'the server did not close cleanly');
+    process.exitCode = 1;
+  }
+  if (onClose === undefined) return;
+  try {
+    await onClose();
+  } catch (error) {
+    app.log.error(error, 'what runs beside the server did not stop cleanly');
+    process.exitCode = 1;
+  }
+}

package/src/server/mcpServer.ts

@@ -0,0 +1,14 @@
+import { createRequire } from 'node:module';
+
+import type * as McpServer from 'cheminfo-mcp-server';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * `cheminfo-mcp-server`, an optional peer, loaded when a helper first needs
+ * it, so `react-cheminfo/server` imports on a site that serves no tools.
+ * @returns The module.
+ */
+export function mcpServer(): typeof McpServer {
+  return require('cheminfo-mcp-server') as typeof McpServer;
+}

package/src/server/repositoryVersion.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { UNRELEASED_VERSION } from '../build/core/buildInfo.ts';
+import { findRepositoryRoot } from '../build/vite/buildInfo.ts';
+
+/**
+ * The release a server's repository is at, as release-please writes it.
+ *
+ * Read from the `package.json` at the repository root, found by the same
+ * climbing rule `cheminfoBuildInfo` follows: a `backend` or `server` directory
+ * keeps the `0.0.0` it was scaffolded with, or none at all, while the root is
+ * the manifest a release bumps. A manifest that cannot be read is not a reason
+ * to refuse to start, so it reads as unreleased instead.
+ *
+ *   const version = readRepositoryVersion(import.meta.dirname);
+ * @param fromDirectory - Where to start climbing, usually the server's own
+ * directory.
+ * @returns The version, or `'0.0.0'` when the root manifest carries none.
+ */
+export function readRepositoryVersion(fromDirectory: string): string {
+  const root = findRepositoryRoot(fromDirectory);
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  } catch {
+    return UNRELEASED_VERSION;
+  }
+  const version = (manifest as { version?: unknown } | null)?.version;
+  return typeof version === 'string' && version !== ''
+    ? version
+    : UNRELEASED_VERSION;
+}

package/src/server/routeOptions.ts

@@ -0,0 +1,26 @@
+/**
+ * What every route the serving helpers register shares: how it is cached, who
+ * may read it, and that it stays out of the API's documentation.
+ */
+
+import type { FastifySchema } from 'fastify';
+
+/** A page is checked on every visit: it names the bundles of its own build. */
+export const PAGE_CACHE = 'no-cache';
+
+/** A bundle is named by its content, so it never changes under its name. */
+export const BUNDLE_CACHE = 'public, max-age=31536000, immutable';
+
+/**
+ * The header that opens an answer to every origin. 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 do these servers.
+ */
+export const ALLOW_ORIGIN = 'access-control-allow-origin';
+
+/** Kept out of the API's documentation (`@fastify/swagger` reads `hide`). */
+export const HIDDEN: FastifySchema & { hide: boolean } = { hide: true };
+
+/** The addresses an API and its documentation answer, never a page. */
+export const DEFAULT_RESERVED: readonly string[] = ['/v1/', '/docs'];

package/src/server/routeTable.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ROUTE_TABLE_FILE, parseRouteTable } from '../seo/core/routeTable.ts';
+import type { RouteMeta } from '../seo/core/routes.ts';
+
+/**
+ * Every address the frontend routes itself, from the `routes.json` its build
+ * wrote beside the page (`cheminfoRouteTable` in `react-cheminfo/vite`).
+ *
+ * The pages that exist whatever the build wrote are the fallback, so a server
+ * started before the frontend was built, or against a build of an older shape,
+ * still titles them.
+ * @param root - The directory holding the built frontend.
+ * @param fallback - The routes when the build wrote no table this can read.
+ * @returns The routes, the home page first.
+ */
+export function readRouteTable(
+  root: string,
+  fallback: readonly RouteMeta[],
+): RouteMeta[] {
+  let text: string;
+  try {
+    text = readFileSync(join(root, ROUTE_TABLE_FILE), 'utf8');
+  } catch {
+    return [...fallback];
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [...fallback];
+  }
+  return parseRouteTable(parsed) ?? [...fallback];
+}

package/src/server/siteView.ts

@@ -0,0 +1,42 @@
+import type { AppResource } from 'cheminfo-mcp-server';
+
+import type { AnswerAddressesInput } from './answerAddresses.ts';
+import { viewOrigins } from './answerAddresses.ts';
+import { mcpServer } from './mcpServer.ts';
+
+/** What {@link siteView} names, and where its pages come from. */
+export interface SiteViewOptions {
+  /** Its address, which the tools name in `ui.resourceUri`: `ui://lcao/page`. */
+  uri: string;
+  /** For people: the site's host, `lcao.cheminfo.org`. */
+  name: string;
+  /** For people: what the card shows inline, and the page over the screen. */
+  description: string;
+  /** Where the site and this server are: the view frames both, and no other. */
+  addresses: AnswerAddressesInput;
+  /**
+   * The height of the frame, in pixels, for a page that cannot report its
+   * own.
+   * @default undefined - the page reports its height, as `CardFrame` does
+   */
+  height?: number;
+}
+
+/**
+ * The MCP App showing an answer on the site's own page: inline the answer's
+ * card, the page itself over the full screen, framed from this server or from
+ * the static site. One per tool server, named by every tool whose answer
+ * carries a `meta` from `cardMeta` or `pageAnswer`.
+ * @param options - Its address, its name, and the two addresses it frames.
+ * @returns The resource, for `createToolRoutes({ resources })`.
+ */
+export function siteView(options: SiteViewOptions): AppResource {
+  const { uri, name, description, addresses, height } = options;
+  return mcpServer().embedView({
+    uri,
+    name,
+    description,
+    origins: viewOrigins(addresses),
+    height,
+  });
+}

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 };
+}