react-cheminfo 0.64.1 → 0.65.0

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,

package/src/share/core/keySetParam.ts

@@ -0,0 +1,92 @@
+import type { ShareParamCodec } from './params.ts';
+
+/** What {@link keySetParam} is configured with. */
+export interface KeySetParamOptions<Key extends string> {
+  /**
+   * The word an empty set is written as. An empty value is dropped from the
+   * address, so a link switching every key off has to say so in a word.
+   * @default 'none'
+   */
+  none?: string;
+  /**
+   * The set a link carrying nothing stands for, and the one deleted rather
+   * than written. `null` means the link then says nothing about the keys, so
+   * whatever the visitor stored is left alone.
+   * @default null
+   */
+  default?: readonly Key[] | null;
+  /**
+   * The set deleted from a link rather than written, when it is not the
+   * default — a site whose absent parameter leaves the visitor's stored keys
+   * alone, and whose own initial keys must not grow a plain visit a query
+   * string.
+   * @default the default set
+   */
+  omitted?: readonly Key[];
+}
+
+/**
+ * A set of keys a link switches on — the layers a figure draws,
+ * `?flags=breakdown,working` — written comma separated, in the order the keys
+ * are listed, so one selection always produces one link.
+ *
+ * A key the tool does not list is dropped rather than refused, so a link
+ * written before a key was renamed still opens; the word for nothing, `none`
+ * by default, reads as the empty set, and an absent or empty parameter as the
+ * default.
+ * @param keys - Every key the tool understands, in the order links write them.
+ * @param options - The word for nothing, and the default set.
+ * @returns The codec.
+ */
+export function keySetParam<Key extends string>(
+  keys: readonly Key[],
+  options: KeySetParamOptions<Key> = {},
+): ShareParamCodec<ReadonlySet<Key> | null> {
+  const none = options.none ?? 'none';
+  const fallback =
+    options.default === undefined || options.default === null
+      ? null
+      : orderKeys(new Set<string>(options.default), keys);
+  const omitted =
+    options.omitted === undefined
+      ? fallback
+      : orderKeys(new Set<string>(options.omitted), keys);
+  const omittedText = omitted === null ? null : writeKeys(omitted, keys);
+  return {
+    parse(raw) {
+      if (raw === null || raw.trim() === '') return fallback;
+      if (raw.trim() === none) return new Set<Key>();
+      const asked = new Set<string>();
+      for (const name of raw.split(',')) asked.add(name.trim());
+      return orderKeys(asked, keys);
+    },
+    serialize(value) {
+      if (value === null) return null;
+      const text = writeKeys(value, keys);
+      if (text === omittedText) return null;
+      return text === '' ? none : text;
+    },
+  };
+}
+
+function orderKeys<Key extends string>(
+  asked: ReadonlySet<string>,
+  keys: readonly Key[],
+): ReadonlySet<Key> {
+  const ordered = new Set<Key>();
+  for (const key of keys) {
+    if (asked.has(key)) ordered.add(key);
+  }
+  return ordered;
+}
+
+function writeKeys<Key extends string>(
+  value: ReadonlySet<Key>,
+  keys: readonly Key[],
+): string {
+  const on: string[] = [];
+  for (const key of keys) {
+    if (value.has(key)) on.push(key);
+  }
+  return on.join(',');
+}

package/src/share/core/vocabulary.ts

@@ -65,4 +65,12 @@ export interface ShareVocabulary<
    * @default {}
    */
   params?: Codecs;
+  /**
+   * The `?hide=` keys older links dropped the chrome with, before the site
+   * spoke `?embed` — `header`, `menu`. A link naming one still opens framed,
+   * because course pages built then must keep opening bare; the key is no part
+   * of the page, so it is never offered and never written back.
+   * @default []
+   */
+  legacyEmbedParts?: readonly string[];
 }

package/src/shell/ui/ShareControl.tsx

@@ -0,0 +1,150 @@
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { siteById } from '../../ecosystem/core/lookup.ts';
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { ShareParamCodecs } from '../../share/core/index.ts';
+import type { ShareButtonVariant } from '../../share/ui/ShareButton.tsx';
+import { ShareButton } from '../../share/ui/ShareButton.tsx';
+import type { ShareDialogProps } from '../../share/ui/ShareDialog.tsx';
+import { ShareDialog } from '../../share/ui/ShareDialog.tsx';
+
+/** What {@link ShareControl} needs: the dialog's props, and the button's. */
+export interface ShareControlProps<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> extends Omit<
+  ShareDialogProps<Codecs>,
+  'isOpen' | 'onClose' | 'search' | 'frameTitle'
+> {
+  /**
+   * The site the page belongs to, which names the frame `<host> — <title>`.
+   * @default undefined — the frame is named by the title alone
+   */
+  siteId?: SiteId;
+  /**
+   * What a screen reader announces the frame as.
+   * @default `<host> — <title>` with a `siteId`, the title without one
+   */
+  frameTitle?: string;
+  /**
+   * The address as it stands, so the tool's inputs travel with the link. A
+   * function is called only while the dialog is open, so a value that is costly
+   * to write — a pinned preference, a list of molecules — is written when a
+   * link is asked for and not on every render of the header.
+   * @default the query string of the page
+   */
+  search?: string | (() => string | undefined);
+  /**
+   * Whether the button keeps only its icon, in a bar that has run out of room.
+   * @default false
+   */
+  compact?: boolean;
+  /**
+   * Text of the button.
+   * @default the chrome's own word for it, in the language of the page
+   */
+  buttonLabel?: string;
+  /**
+   * What the pointer is told over the button.
+   * @default the chrome's own line, in the language of the page
+   */
+  buttonTitle?: string;
+  /**
+   * A plain bar entry, or a Blueprint button for a toolbar made of them.
+   * @default 'nav-link'
+   */
+  variant?: ShareButtonVariant;
+  /**
+   * Whether the dialog is open, for a page that has to know — to compute what
+   * the dialog shows only while it is. Pass it with `onOpenChange`.
+   * @default undefined — the control keeps the state itself
+   */
+  open?: boolean;
+  /**
+   * Called when the dialog opens or closes.
+   * @default undefined
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * Called as the button is pressed, before the dialog opens — to write the
+   * page's state into the address the link is read from.
+   * @default undefined
+   */
+  onOpen?: () => void;
+}
+
+/**
+ * The Share entry of a header and the dialog it opens: the page handed out as a
+ * link, or as the iframe that frames it in somebody else's site.
+ *
+ * It is what a header's `share` prop takes, so the entry lands after Contact on
+ * every site. Everything the dialog can be told is passed straight through; the
+ * control adds the open state, and the frame's name read off the site.
+ * @param props - The dialog's props, and how the button is dressed.
+ * @returns The button, and the dialog while it is open.
+ */
+export function ShareControl<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(props: ShareControlProps<Codecs>): ReactElement {
+  const {
+    siteId,
+    frameTitle,
+    search,
+    compact = false,
+    buttonLabel,
+    buttonTitle,
+    variant,
+    open,
+    onOpenChange,
+    onOpen,
+    title,
+    ...dialog
+  } = props;
+  const t = useChromeT();
+  const [ownOpen, setOwnOpen] = useState(false);
+  const isOpen = open ?? ownOpen;
+
+  function setOpen(next: boolean): void {
+    if (open === undefined) setOwnOpen(next);
+    onOpenChange?.(next);
+  }
+
+  const host = siteId === undefined ? undefined : siteById(siteId).host;
+  const named =
+    frameTitle ??
+    (host === undefined ? title : t('share.frameTitle', { site: host, title }));
+
+  return (
+    <>
+      <ShareButton
+        compact={compact}
+        label={buttonLabel}
+        title={buttonTitle}
+        variant={variant}
+        onClick={() => {
+          onOpen?.();
+          setOpen(true);
+        }}
+      />
+      <ShareDialog<Codecs>
+        {...dialog}
+        title={title}
+        frameTitle={named}
+        search={
+          isOpen && typeof search === 'function' ? search() : searchText(search)
+        }
+        isOpen={isOpen}
+        onClose={() => {
+          setOpen(false);
+        }}
+      />
+    </>
+  );
+}
+
+function searchText(
+  search: string | (() => string | undefined) | undefined,
+): string | undefined {
+  return typeof search === 'string' ? search : undefined;
+}