react-cheminfo 0.64.0 → 0.65.0

package/src/seo/core/routeTable.ts

@@ -0,0 +1,103 @@
+/**
+ * The route table a build writes beside its page, for the server that hands the
+ * page out: it titles every address from it, lists it in `sitemap.xml` and links
+ * it from the crawl path. The app's own table is the one thing that knows the
+ * pages, so there is one table rather than two that drift.
+ */
+
+import type { RouteMeta } from './routes.ts';
+import { assertRoutes } from './routes.ts';
+
+/** The file the table is written to, next to `index.html`. */
+export const ROUTE_TABLE_FILE = 'routes.json';
+
+/** A field of a route the table can carry. */
+export type RouteField = keyof RouteMeta;
+
+/** Every field of a route, in the order they are written. */
+export const ROUTE_FIELDS: readonly RouteField[] = [
+  'path',
+  'title',
+  'description',
+  'short',
+  'note',
+  'indexed',
+  'prefix',
+];
+
+/** The fields a route cannot be read without. */
+const REQUIRED_FIELDS: readonly RouteField[] = ['path', 'title', 'description'];
+
+/**
+ * Write a route table as the file a server reads back.
+ * @param routes - Every address the site answers.
+ * @param fields - The fields written; `path`, `title` and `description` are
+ * always written, since a route cannot be read without them.
+ * @returns The JSON document, ending with a newline.
+ */
+export function serializeRouteTable(
+  routes: readonly RouteMeta[],
+  fields: readonly RouteField[] = ROUTE_FIELDS,
+): string {
+  const written = new Set<RouteField>([...REQUIRED_FIELDS, ...fields]);
+  const order = ROUTE_FIELDS.filter((field) => written.has(field));
+  const table = routes.map((route) => {
+    const entry: Record<string, unknown> = {};
+    for (const field of order) {
+      if (route[field] !== undefined) entry[field] = route[field];
+    }
+    return entry;
+  });
+  return `${JSON.stringify(table, null, 2)}\n`;
+}
+
+/**
+ * Read a route table back, refusing anything the build did not write: an empty
+ * table, an entry missing its path, title or description, a field of the wrong
+ * type, or a table `assertRoutes` refuses.
+ * @param value - The parsed JSON.
+ * @returns The routes, carrying only the fields a route has, or `undefined`
+ * when the value is not a route table.
+ */
+export function parseRouteTable(value: unknown): RouteMeta[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  const routes: RouteMeta[] = [];
+  for (const entry of value) {
+    const route = readRoute(entry);
+    if (route === undefined) return undefined;
+    routes.push(route);
+  }
+  try {
+    assertRoutes(routes);
+  } catch {
+    return undefined;
+  }
+  return routes;
+}
+
+function readRoute(value: unknown): RouteMeta | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const entry = value as Record<string, unknown>;
+  const { path, title, description, short, note, indexed, prefix } = entry;
+  if (
+    typeof path !== 'string' ||
+    typeof title !== 'string' ||
+    typeof description !== 'string' ||
+    !isOptional(short, 'string') ||
+    !isOptional(note, 'string') ||
+    !isOptional(indexed, 'boolean') ||
+    !isOptional(prefix, 'boolean')
+  ) {
+    return undefined;
+  }
+  const route: RouteMeta = { path, title, description };
+  if (typeof short === 'string') route.short = short;
+  if (typeof note === 'string') route.note = note;
+  if (typeof indexed === 'boolean') route.indexed = indexed;
+  if (typeof prefix === 'boolean') route.prefix = prefix;
+  return route;
+}
+
+function isOptional(value: unknown, type: 'string' | 'boolean'): boolean {
+  return value === undefined || typeof value === type;
+}

package/src/seo/vite/index.ts

@@ -2,3 +2,5 @@ export type { OgCardOptions } from './ogCard.ts';
 export { OG_HEIGHT, OG_WIDTH, ogCardHtml } from './ogCard.ts';
 export type { PrerenderOptions } from './prerender.ts';
 export { cheminfoPrerender } from './prerender.ts';
+export type { RouteTableOptions } from './routeTable.ts';
+export { cheminfoRouteTable } from './routeTable.ts';

package/src/seo/vite/prerender.ts

@@ -36,6 +36,8 @@ import { withLanguagePath } from '../../language/core/languagePath.ts';
 import { trimTrailingSlash } from '../../router/core/address.ts';
 import type { NoscriptText } from '../core/noscript.ts';
 import { noscriptIndex } from '../core/noscript.ts';
+import type { PageContentRecord } from '../core/pageContent.ts';
+import { pageContentOf } from '../core/pageContent.ts';
 import { pageHeadTags } from '../core/pageMeta.ts';
 import type { PageContent } from '../core/pageProse.ts';
 import type { RobotsDisallow } from '../core/robots.ts';
@@ -124,6 +126,15 @@ export interface PrerenderOptions {
    * @default undefined — every page carries the menu alone
    */
   content?: (route: RouteMeta, language: Language) => PageContent | undefined;
+  /**
+   * The pages written for, by path — or a function giving them per language —
+   * for a site that would otherwise write `content` only to look a path up in
+   * them. Every other address then says the name and the sentence its route
+   * is indexed under, so none ships the bare menu. `content`, when given, is
+   * read instead.
+   * @default undefined — `content` alone decides
+   */
+  pages?: PageContentRecord;
   /**
    * Every language the site is written in, the default one included.
    *
@@ -306,7 +317,7 @@ function crawlPathOf(
   const noscript =
     typeof declared === 'function' ? declared(language) : declared;
   if (noscript === false) return '';
-  const content = options.content?.(route, language);
+  const content = contentOf(options, route, language);
   const { routes: listed, ...prose } = noscript === true ? {} : noscript;
   // The crawl path of a translated page links to that language's addresses: a
   // French page listing the English ones is a crawler's only route out of it,
@@ -351,3 +362,17 @@ function withHtmlLang(template: string, language: Language): string {
     `<html$<attributes> lang="${language}"`,
   );
 }
+
+// What a page says for itself: the site's own function when it wrote one, and
+// otherwise the page it wrote for that path, or the route's name and sentence.
+function contentOf(
+  options: PrerenderOptions,
+  route: RouteMeta,
+  language: Language,
+): PageContent | undefined {
+  const { content, pages } = options;
+  if (content !== undefined) return content(route, language);
+  return pages === undefined
+    ? undefined
+    : pageContentOf(pages)(route, language);
+}

package/src/seo/vite/routeTable.ts

@@ -0,0 +1,79 @@
+/**
+ * Write the route table beside the page a server hands out.
+ *
+ * A site with a backend titles every address it answers, lists it in
+ * `sitemap.xml` and links it from the crawl path — and the app's own route table
+ * is the one thing that knows those addresses. So the build writes it next to
+ * `index.html`, from the very table the app reads, and `readRouteTable` in
+ * `react-cheminfo/server` reads it back: a page added to the site is indexed
+ * without anybody remembering to.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Plugin } from 'vite';
+
+import type { RouteField } from '../core/routeTable.ts';
+import {
+  ROUTE_FIELDS,
+  ROUTE_TABLE_FILE,
+  serializeRouteTable,
+} from '../core/routeTable.ts';
+import type { RouteMeta } from '../core/routes.ts';
+import { assertRoutes } from '../core/routes.ts';
+
+/** Options of {@link cheminfoRouteTable}. */
+export interface RouteTableOptions {
+  /** Every address the site answers, each with its title and description. */
+  routes: readonly RouteMeta[];
+  /**
+   * The fields written for each route. `path`, `title` and `description` are
+   * always written: a server cannot read a route without them.
+   * @default every field of a route
+   */
+  fields?: readonly RouteField[];
+  /**
+   * The file written in the build.
+   * @default 'routes.json'
+   */
+  fileName?: string;
+}
+
+/**
+ * The Vite plugin writing the route table.
+ *
+ * The table is author configuration, so it is checked when the build starts —
+ * an address written twice, or one climbing out of the site, fails the build
+ * rather than shipping two sitemap entries for one page.
+ * @param options - The table, and which fields it carries.
+ * @returns The Vite plugin.
+ */
+export function cheminfoRouteTable(options: RouteTableOptions): Plugin {
+  const {
+    routes,
+    fields = ROUTE_FIELDS,
+    fileName = ROUTE_TABLE_FILE,
+  } = options;
+  let root = process.cwd();
+  let outDir = 'dist';
+
+  return {
+    name: 'cheminfo-route-table',
+    apply: 'build',
+    configResolved(config) {
+      root = config.root;
+      outDir = config.build.outDir;
+    },
+    buildStart() {
+      assertRoutes(routes);
+    },
+    writeBundle(output) {
+      const directory = output.dir ?? resolve(root, outDir);
+      writeFileSync(
+        join(directory, fileName),
+        serializeRouteTable(routes, fields),
+      );
+    },
+  };
+}

package/src/server/answerAddresses.ts

@@ -0,0 +1,92 @@
+/**
+ * Where an answer of a site's tool server points: the static site people
+ * share, which an answer's `link` names, and this server, whose copy of the
+ * same pages a chat frames.
+ *
+ * The two are written however the deployment writes them — an origin, an
+ * origin and a mount, with or without a trailing slash — and a page is named
+ * from the site's own root, `/titration` and `titration` alike: every helper
+ * joins the two with exactly one slash, so `https://www.cheminfo.org/surge`
+ * and `https://www.cheminfo.org/surge/` both put `/generator` at
+ * `https://www.cheminfo.org/surge/generator`.
+ */
+
+import { trimTrailingSlash } from '../router/core/address.ts';
+import { joinBasePath } from '../router/core/basePath.ts';
+
+/** Where the pages of an answer are served, as a deployment writes them. */
+export interface AnswerAddressesInput {
+  /** The static site an answer links to, the address people share. */
+  siteUrl: string | URL;
+  /** This server, as a browser reaches it: the view frames its pages. */
+  publicUrl: string | URL;
+}
+
+/** Where the pages of an answer are served, checked and written alike. */
+export interface AnswerAddresses {
+  /** The static site, ending in `/`: `https://equilibrium.cheminfo.org/`. */
+  readonly siteUrl: string;
+  /** This server, ending in `/`: `https://equilibrium.c6h6.org/`. */
+  readonly publicUrl: string;
+}
+
+/**
+ * Check the two addresses of a tool server's answers, and write them alike:
+ * absolute, `http` or `https`, without a query or a fragment, ending in `/`.
+ * @param input - The site and this server, as the deployment gives them.
+ * @returns The two addresses.
+ * @throws {Error} When either is not an http or https address.
+ */
+export function answerAddresses(input: AnswerAddressesInput): AnswerAddresses {
+  return {
+    siteUrl: baseAddress(input.siteUrl, 'siteUrl'),
+    publicUrl: baseAddress(input.publicUrl, 'publicUrl'),
+  };
+}
+
+/**
+ * The origins a view may frame: this server's, which a chat frames, and the
+ * shared site's, which a link opens. A server that is the site gives one.
+ * @param addresses - The two addresses.
+ * @returns Each origin once, this server's first.
+ */
+export function viewOrigins(addresses: AnswerAddressesInput): string[] {
+  return [
+    ...new Set([
+      new URL(addresses.publicUrl).origin,
+      new URL(addresses.siteUrl).origin,
+    ]),
+  ];
+}
+
+/**
+ * A page under a base address, joined with exactly one slash.
+ * @param base - An origin, or an origin and a mount, with or without its
+ *   trailing slash.
+ * @param page - A page from the site's own root, with or without its leading
+ *   slash, and with its query: `/titration?ind=phenolphthalein`.
+ * @returns The page's absolute address.
+ */
+export function joinAddress(base: string | URL, page: string): string {
+  return `${trimTrailingSlash(String(base))}${joinBasePath('', page)}`;
+}
+
+/**
+ * One address of a deployment, checked.
+ * @param value - The address.
+ * @param name - What it is, for the error.
+ * @returns The address without its query or fragment, ending in `/`.
+ */
+function baseAddress(value: string | URL, name: string): string {
+  const text = String(value).trim();
+  if (!URL.canParse(text)) {
+    throw new Error(`${name} is not an address: ${text}`);
+  }
+  const url = new URL(text);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`${name} is not an http or https address: ${text}`);
+  }
+  url.search = '';
+  url.hash = '';
+  return url.href.endsWith('/') ? url.href : `${url.href}/`;
+}

package/src/server/cardMeta.ts

@@ -0,0 +1,88 @@
+/**
+ * What a tool server's answer carries for a chat to show it: the link to the
+ * site's page people share, and the `meta` naming that page framed on this
+ * server — its card inline, the page itself over the full screen.
+ */
+
+import type { CardPageOptions } from '../card/core/cardPageUrl.ts';
+import { cardPageUrl, framedPageUrl } from '../card/core/cardPageUrl.ts';
+import { formatQueryString } from '../router/core/query.ts';
+
+import type { AnswerAddressesInput } from './answerAddresses.ts';
+import { joinAddress } from './answerAddresses.ts';
+import { mcpServer } from './mcpServer.ts';
+
+/** How {@link cardMeta} writes the card and the page. */
+export interface CardMetaOptions extends CardPageOptions {
+  /**
+   * The longest card address an answer carries. Browsers take far more, but a
+   * proxy reading the request line stops at 8 to 16 KB; past this length the
+   * answer carries no card, and the chat draws the answer itself.
+   * @default 8000
+   */
+  maxLength?: number;
+}
+
+/** The page an answer is shown on. */
+export interface PageAnswer {
+  /** The page on the static site people share: what `result.link` says. */
+  link: string;
+  /**
+   * The answer's `meta`: the card on this server, framed inline, and the same
+   * page whole for when the reader asks for more. Undefined when the card's
+   * address would be longer than `maxLength`.
+   */
+  meta: Record<string, unknown> | undefined;
+}
+
+/**
+ * What an answer carries for the view to show a page of this server: inline
+ * its card, drawing only the answer; over the full screen the page itself.
+ * Both are without the site's chrome, and without the parts `hide` names.
+ * @param addresses - Where the site and this server are; only this server's
+ *   is read.
+ * @param page - The page from the site's own root, with its own query and
+ *   without `embed`, `hide` or `card`: `/titration?ind=phenolphthalein`.
+ * @param options - The parts left out, what the card draws, and the longest
+ *   card address carried.
+ * @returns The answer's `meta`, or undefined when the card's address is too
+ *   long to carry.
+ */
+export function cardMeta(
+  addresses: AnswerAddressesInput,
+  page: string,
+  options: CardMetaOptions = {},
+): Record<string, unknown> | undefined {
+  const { maxLength = 8000, ...written } = options;
+  const framed = joinAddress(addresses.publicUrl, page);
+  const card = cardPageUrl(framed, written);
+  if (card.length > maxLength) return undefined;
+  return mcpServer().embedMeta(card, { page: framedPageUrl(framed, written) });
+}
+
+/**
+ * A page with its query: the link people share, on the static site, and the
+ * `meta` the view frames this server's copy of it with. The query is written
+ * by `formatQueryString`, so a `+` is escaped, a comma stays a comma, and a
+ * parameter left `undefined` or empty is not written: the page reads its own
+ * default.
+ * @param addresses - Where the site and this server are.
+ * @param path - The page, from the site's own root: `/titration`.
+ * @param params - Its query, in the order it is written.
+ * @param options - The parts left out, what the card draws, and the longest
+ *   card address carried.
+ * @returns The link and the meta.
+ */
+export function pageAnswer(
+  addresses: AnswerAddressesInput,
+  path: string,
+  params: Readonly<Record<string, string | undefined>> = {},
+  options: CardMetaOptions = {},
+): PageAnswer {
+  const query = formatQueryString(params);
+  const page = query === '' ? path : `${path}?${query}`;
+  return {
+    link: joinAddress(addresses.siteUrl, page),
+    meta: cardMeta(addresses, page, options),
+  };
+}

package/src/server/config.ts

@@ -0,0 +1,125 @@
+import { siteById } from '../ecosystem/core/lookup.ts';
+import type { SiteId } from '../ecosystem/core/sites.ts';
+import { siteUrl } from '../ecosystem/core/sites.ts';
+import { normalizeBasePath } from '../router/core/basePath.ts';
+
+import { readEnvNumber } from './envNumber.ts';
+import { parseTrustProxy } from './trustProxy.ts';
+
+/** An environment, as `process.env` holds it. */
+export type ServerEnvironment = Readonly<Record<string, string | undefined>>;
+
+/** What a site's server knows before it reads its environment. */
+export interface ServerConfigOptions {
+  /** The site, as `ECOSYSTEM_SITES` names it: its address is the default `SITE_URL`. */
+  siteId: SiteId;
+  /** The port derived from the site's creation date, the one compose publishes. */
+  port: number;
+  /**
+   * The build served when `SERVER_ROOT` names none, usually
+   * `join(import.meta.dirname, '../dist')`.
+   * @default 'dist' - resolved from the directory the process runs in
+   */
+  root?: string;
+}
+
+/** What a site's server is started with, every default filled in. */
+export interface ServerConfig {
+  /** Where it listens: `PORT`, or the site's own port. */
+  port: number;
+  /** The interface it listens on: `HOST`, or every interface, as a container needs. */
+  host: string;
+  /** `TRACKING_SCRIPT`, verbatim; `undefined` loads nothing. */
+  trackingScript: string | undefined;
+  /**
+   * `SITE_URL`: the static site people share, which every answer links to,
+   * ending in `/`.
+   */
+  siteUrl: string;
+  /**
+   * `PUBLIC_URL`: this server's own address, whose pages a chat frames, ending
+   * in `/`.
+   */
+  publicUrl: string;
+  /** `TRUST_PROXY`: the reverse proxies whose `X-Forwarded-For` is believed. */
+  trustProxy: boolean | string;
+  /** `SERVER_ROOT`: the build it serves. */
+  root: string;
+  /**
+   * `BASE_PATH`: where the deployment is mounted behind a proxy that takes the
+   * path off, `/osiris`, or `''` on a host of its own.
+   */
+  basePath: string;
+}
+
+/**
+ * Read a site's server configuration from its environment, once, at startup.
+ *
+ * A malformed value refuses to start rather than handing out links that lead
+ * nowhere. Both addresses keep their path — a site may be mounted under one,
+ * and its pages are written relative to it — and lose their query and their
+ * fragment; each ends in `/`.
+ *
+ *   const config = readServerConfig(process.env, { siteId: 'osiris', port: 10_620 });
+ * @param env - The environment, e.g. `process.env`.
+ * @param options - The site and its port.
+ * @returns The configuration.
+ * @throws {Error} When `PORT`, `SITE_URL` or `PUBLIC_URL` cannot be read, or
+ * `TRUST_PROXY` is a hop count.
+ */
+export function readServerConfig(
+  env: ServerEnvironment,
+  options: ServerConfigOptions,
+): ServerConfig {
+  const port = readEnvNumber(env, 'PORT', options.port, {
+    min: 1,
+    max: 65_535,
+    integer: true,
+  });
+  return {
+    port,
+    host: env.HOST?.trim() || '0.0.0.0',
+    trackingScript: env.TRACKING_SCRIPT?.trim() || undefined,
+    siteUrl: readHttpAddress(
+      env,
+      'SITE_URL',
+      siteUrl(siteById(options.siteId)),
+    ),
+    publicUrl: readHttpAddress(env, 'PUBLIC_URL', `http://localhost:${port}/`),
+    trustProxy: parseTrustProxy(env.TRUST_PROXY),
+    root: env.SERVER_ROOT?.trim() || options.root || 'dist',
+    basePath: normalizeBasePath(env.BASE_PATH ?? ''),
+  };
+}
+
+/**
+ * Read an http or https address from the environment, the way a link is built
+ * on it: its path kept and ended with `/`, its query and its fragment dropped.
+ * @param env - The environment, e.g. `process.env`.
+ * @param name - The variable, e.g. `SITE_URL`.
+ * @param fallback - The address when the variable is unset or blank.
+ * @returns The address, ending in `/`.
+ * @throws {Error} When the value, or the fallback, is not an http or https
+ * address.
+ */
+export function readHttpAddress(
+  env: ServerEnvironment,
+  name: string,
+  fallback: string,
+): string {
+  const text = env[name]?.trim() || fallback;
+  const message = `${name} must be an http(s) address, not "${text}".`;
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch (error) {
+    throw new Error(message, { cause: error });
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(message);
+  }
+  url.search = '';
+  url.hash = '';
+  if (!url.pathname.endsWith('/')) url.pathname = `${url.pathname}/`;
+  return url.href;
+}

package/src/server/envNumber.ts

@@ -0,0 +1,65 @@
+/** The bounds a number read from the environment must keep. */
+export interface ReadEnvNumberOptions {
+  /**
+   * The smallest value accepted.
+   * @default undefined - no lower bound
+   */
+  min?: number;
+  /**
+   * The largest value accepted.
+   * @default undefined - no upper bound
+   */
+  max?: number;
+  /**
+   * Whether the value must be a whole number.
+   * @default false
+   */
+  integer?: boolean;
+}
+
+/**
+ * Read a number from the environment.
+ *
+ * The compose files forward every variable as `${NAME:-}`, so a deployment that
+ * sets nothing hands the process an empty string rather than no variable — and
+ * `Number('')` is 0, which turned an indexer's interval into a busy loop. Unset,
+ * empty and blank all mean the fallback here. A value that says something but is
+ * not an accepted number refuses to start rather than running on a guess.
+ * @param env - The environment, e.g. `process.env`.
+ * @param name - The variable, e.g. `INDEX_INTERVAL`.
+ * @param fallback - The value when the variable says nothing.
+ * @param options - The bounds the value must keep.
+ * @returns The number written, or the fallback.
+ * @throws {Error} When the value is not a finite number, or breaks a bound.
+ */
+export function readEnvNumber(
+  env: Readonly<Record<string, string | undefined>>,
+  name: string,
+  fallback: number,
+  options: ReadEnvNumberOptions = {},
+): number {
+  const text = env[name]?.trim();
+  if (!text) return fallback;
+  const value = Number(text);
+  const { min, max, integer = false } = options;
+  if (
+    !Number.isFinite(value) ||
+    (integer && !Number.isInteger(value)) ||
+    (min !== undefined && value < min) ||
+    (max !== undefined && value > max)
+  ) {
+    throw new Error(`${name} must be ${expected(options)}, not "${text}".`);
+  }
+  return value;
+}
+
+function expected(options: ReadEnvNumberOptions): string {
+  const { min, max, integer = false } = options;
+  const kind = integer ? 'an integer' : 'a number';
+  if (min !== undefined && max !== undefined) {
+    return `${kind} from ${min} to ${max}`;
+  }
+  if (min !== undefined) return `${kind} of at least ${min}`;
+  if (max !== undefined) return `${kind} of at most ${max}`;
+  return kind;
+}

package/src/server/healthRoute.ts

@@ -0,0 +1,42 @@
+import type { FastifyInstance } from 'fastify';
+
+import { ALLOW_ORIGIN, HIDDEN } from './routeOptions.ts';
+
+/** Options of {@link healthRoute}. */
+export interface HealthRouteOptions {
+  /**
+   * More fields for the answer, read locally and cheaply: a probe every 30 s
+   * must never wait on another service, or a dependency that is down rolls back
+   * a good release. `status` is always `ok`, whatever this returns.
+   * @default undefined - the answer is `{ status: 'ok' }`
+   */
+  extra?: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+
+/**
+ * Answer `GET /health`, what the container's health check and the server's
+ * deploy script probe before they keep a new container.
+ *
+ * It is at the root, never versioned, because it probes the process rather than
+ * the API contract. It logs nothing, or a probe every 30 s fills the log; it is
+ * kept out of the API's documentation; and it is open to any origin, like
+ * everything else a site serves.
+ *
+ *   await healthRoute(app);
+ * @param fastify - The server.
+ * @param options - Extra fields for the answer.
+ */
+export async function healthRoute(
+  fastify: FastifyInstance,
+  options: HealthRouteOptions = {},
+): Promise<void> {
+  const { extra } = options;
+  fastify.get(
+    '/health',
+    { logLevel: 'silent', schema: HIDDEN },
+    async (_request, reply) => {
+      const fields = extra === undefined ? {} : await extra();
+      return reply.header(ALLOW_ORIGIN, '*').send({ ...fields, status: 'ok' });
+    },
+  );
+}