react-cheminfo 0.58.0 → 0.60.0

package/src/moleculesToken/core/moleculesToken.ts

@@ -0,0 +1,256 @@
+import { trimTrailingSlash } from '../../router/core/address.ts';
+
+/**
+ * What molecules.cheminfo.org says of a token a site holds:
+ *
+ * - `ok`: issued for a source the site writes, and not revoked;
+ * - `otherSource`: valid, but issued for another source, so what the site
+ *   sends is credited to that one;
+ * - `refused`: never issued, or revoked;
+ * - `unset`: the site holds none;
+ * - `uncheckable`: molecules.cheminfo.org answers, but cannot check a token
+ *   yet;
+ * - `unanswered`: it did not answer, or failed.
+ */
+export type MoleculesTokenVerdict =
+  'ok' | 'otherSource' | 'refused' | 'unset' | 'uncheckable' | 'unanswered';
+
+/** A token a site holds, to be checked. */
+export interface MoleculesTokenToCheck {
+  /** The environment variable it is read from, e.g. `MOLECULES_TOKEN_LOTUS`. */
+  variable: string;
+  /** The token, or undefined when the variable is unset or blank. */
+  token: string | undefined;
+  /**
+   * The sources it may have been issued for, as molecules.cheminfo.org names
+   * them: any one of them is right, whatever its case.
+   * @default [] — any source
+   */
+  sources?: readonly string[];
+}
+
+/** A token, as molecules.cheminfo.org checked it. Never the token itself. */
+export interface MoleculesTokenCheck {
+  /** The environment variable it is read from. */
+  variable: string;
+  /** The sources it may have been issued for; empty for any source. */
+  sources: string[];
+  /** What molecules.cheminfo.org says of it. */
+  verdict: MoleculesTokenVerdict;
+  /**
+   * What molecules.cheminfo.org said, or why it could not be asked; null when
+   * the verdict says it all.
+   */
+  message: string | null;
+  /** The source molecules.cheminfo.org knows it for, once it answered. */
+  source: string | null;
+  /**
+   * Its first characters, as molecules.cheminfo.org shows them: what tells two
+   * tokens apart without showing either.
+   */
+  hint: string | null;
+  /** Who it was issued to. */
+  email: string | null;
+  /** When it was issued, in epoch milliseconds. */
+  issuedAt: number | null;
+  /** When it last read or wrote, in epoch milliseconds, to within a minute. */
+  lastUsedAt: number | null;
+  /** When it was checked, in epoch milliseconds. */
+  checkedAt: number;
+}
+
+/** Where molecules.cheminfo.org answers, and how patiently it is asked. */
+export interface CheckMoleculesTokenOptions {
+  /** Where it answers, e.g. `https://molecules.cheminfo.org`. */
+  baseUrl: string;
+  /**
+   * How long one check may take.
+   * @default 5000
+   */
+  timeoutMs?: number;
+  /**
+   * The fetch to use, for tests.
+   * @default globalThis.fetch
+   */
+  fetch?: typeof fetch;
+  /**
+   * The clock the checks are stamped with, for tests.
+   * @default Date.now
+   */
+  now?: () => number;
+}
+
+/**
+ * Ask molecules.cheminfo.org about a token: `GET /v1/token`, which says which
+ * source it was issued for and never counts as using it. A token pasted in
+ * another source's place, revoked, or never issued shows here before an import
+ * sends anything with it. Never throws: a molecules.cheminfo.org that does not
+ * answer is a verdict too.
+ * @param entry - The token, where it is read from, and the sources it may be for.
+ * @param options - Where molecules.cheminfo.org answers, and how patiently.
+ * @returns What it says of the token.
+ */
+export async function checkMoleculesToken(
+  entry: MoleculesTokenToCheck,
+  options: CheckMoleculesTokenOptions,
+): Promise<MoleculesTokenCheck> {
+  const {
+    baseUrl,
+    timeoutMs = 5000,
+    fetch: fetchImplementation = globalThis.fetch,
+    now = Date.now,
+  } = options;
+  const sources = entry.sources === undefined ? [] : [...entry.sources];
+  const verdict = (
+    value: MoleculesTokenVerdict,
+    message: string | null = null,
+  ): MoleculesTokenCheck => ({
+    variable: entry.variable,
+    sources,
+    verdict: value,
+    message,
+    source: null,
+    hint: null,
+    email: null,
+    issuedAt: null,
+    lastUsedAt: null,
+    checkedAt: now(),
+  });
+
+  const token = entry.token?.trim();
+  if (!token) return verdict('unset');
+
+  let response: Response;
+  try {
+    response = await fetchImplementation(
+      `${trimTrailingSlash(baseUrl)}/v1/token`,
+      {
+        headers: {
+          accept: 'application/json',
+          authorization: `Bearer ${token}`,
+        },
+        signal: AbortSignal.timeout(timeoutMs),
+      },
+    );
+  } catch (error: unknown) {
+    return verdict('unanswered', whyUnanswered(error, timeoutMs));
+  }
+
+  if (response.status === 401) {
+    return verdict('refused', await messageOf(response));
+  }
+  if (response.status === 404) {
+    await response.body?.cancel();
+    return verdict('uncheckable', 'GET /v1/token answered 404');
+  }
+  if (!response.ok) {
+    await response.body?.cancel();
+    return verdict('unanswered', `GET /v1/token answered ${response.status}`);
+  }
+
+  const record = await recordOf(response);
+  if (record === null) {
+    return verdict('unanswered', 'GET /v1/token answered no token');
+  }
+  const known = {
+    source: record.source,
+    hint: record.hint,
+    email: record.email,
+    issuedAt: record.createdAt * 1000,
+    lastUsedAt: record.lastUsedAt === null ? null : record.lastUsedAt * 1000,
+  };
+  if (record.revokedAt !== null) {
+    return { ...verdict('refused', 'this token was revoked'), ...known };
+  }
+  const wanted = record.source.toLowerCase();
+  const expected =
+    sources.length === 0 ||
+    sources.some((source) => source.toLowerCase() === wanted);
+  return { ...verdict(expected ? 'ok' : 'otherSource'), ...known };
+}
+
+/**
+ * Check every token a site holds, all at once.
+ * @param entries - The tokens. See {@link checkMoleculesToken}.
+ * @param options - See {@link CheckMoleculesTokenOptions}.
+ * @returns What molecules.cheminfo.org says of each, in the order given.
+ */
+export async function checkMoleculesTokens(
+  entries: readonly MoleculesTokenToCheck[],
+  options: CheckMoleculesTokenOptions,
+): Promise<MoleculesTokenCheck[]> {
+  return Promise.all(
+    entries.map((entry) => checkMoleculesToken(entry, options)),
+  );
+}
+
+/**
+ * What a page anyone can open may show of a check: the verdict and the source,
+ * without who the token was issued to or its first characters.
+ * @param check - The check.
+ * @returns The check, without them.
+ */
+export function publicTokenCheck(
+  check: MoleculesTokenCheck,
+): MoleculesTokenCheck {
+  return { ...check, email: null, hint: null };
+}
+
+/** What `GET /v1/token` answers, as far as a check reads it. */
+interface TokenRecord {
+  source: string;
+  email: string;
+  hint: string;
+  createdAt: number;
+  lastUsedAt: number | null;
+  revokedAt: number | null;
+}
+
+async function recordOf(response: Response): Promise<TokenRecord | null> {
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    return null;
+  }
+  if (typeof body !== 'object' || body === null) return null;
+  const record = body as Partial<Record<keyof TokenRecord, unknown>>;
+  if (
+    typeof record.source !== 'string' ||
+    typeof record.email !== 'string' ||
+    typeof record.hint !== 'string' ||
+    typeof record.createdAt !== 'number' ||
+    !isOptionalNumber(record.lastUsedAt) ||
+    !isOptionalNumber(record.revokedAt)
+  ) {
+    return null;
+  }
+  return {
+    source: record.source,
+    email: record.email,
+    hint: record.hint,
+    createdAt: record.createdAt,
+    lastUsedAt: record.lastUsedAt,
+    revokedAt: record.revokedAt,
+  };
+}
+
+function isOptionalNumber(value: unknown): value is number | null {
+  return value === null || typeof value === 'number';
+}
+
+async function messageOf(response: Response): Promise<string | null> {
+  try {
+    const body = (await response.json()) as { message?: unknown };
+    return typeof body.message === 'string' ? body.message : null;
+  } catch {
+    return null;
+  }
+}
+
+function whyUnanswered(error: unknown, timeoutMs: number): string {
+  if ((error as { name?: unknown } | null)?.name === 'TimeoutError') {
+    return `no answer within ${timeoutMs} ms`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}

package/src/moleculesToken/core/tokenFix.ts

@@ -0,0 +1,37 @@
+import type {
+  MoleculesTokenCheck,
+  MoleculesTokenVerdict,
+} from './moleculesToken.ts';
+
+/** The verdicts only a new token, written in the server's `.env`, fixes. */
+const NEEDS_NEW_TOKEN: ReadonlySet<MoleculesTokenVerdict> = new Set([
+  'unset',
+  'refused',
+  'otherSource',
+]);
+
+/**
+ * The checks whose token has to be replaced: none is set, molecules.cheminfo.org
+ * refuses it, or it was issued for another source. A token that could not be
+ * checked is not among them, since nothing written in the `.env` fixes that.
+ * @param checks - The last checks.
+ * @returns Those to fix, in the order given.
+ */
+export function tokensToFix(
+  checks: readonly MoleculesTokenCheck[],
+): MoleculesTokenCheck[] {
+  return checks.filter((check) => NEEDS_NEW_TOKEN.has(check.verdict));
+}
+
+/**
+ * The command molecules.cheminfo.org issues a check's token with, on its
+ * server. The source is quoted, since a name like `NP Atlas` holds a space;
+ * the email is left for the reader to write.
+ * @param check - The check, whose first source the token is issued for.
+ * @returns The command.
+ */
+export function issueTokenCommand(
+  check: Pick<MoleculesTokenCheck, 'sources'>,
+): string {
+  return `npm run tokens -- issue '${check.sources[0] ?? 'SOURCE'}' EMAIL`;
+}

package/src/moleculesToken/ui/MoleculesTokenFix.tsx

@@ -0,0 +1,95 @@
+import { Callout } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { CodeBlock } from '../../clipboard/ui/CodeBlock.tsx';
+import { useLanguage } from '../../i18n/ui/useLanguage.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { trimTrailingSlash } from '../../router/core/address.ts';
+import type { MoleculesTokenCheck } from '../core/moleculesToken.ts';
+import { issueTokenCommand, tokensToFix } from '../core/tokenFix.ts';
+
+/** Where molecules.cheminfo.org answers when the site names no other. */
+const DEFAULT_MOLECULES_URL = 'https://molecules.cheminfo.org';
+
+/** What {@link MoleculesTokenFix} shows. */
+export interface MoleculesTokenFixProps {
+  /** The last checks. */
+  checks: readonly MoleculesTokenCheck[];
+  /**
+   * Where molecules.cheminfo.org answers, whose Admin page issues tokens.
+   * @default 'https://molecules.cheminfo.org'
+   */
+  moleculesUrl?: string;
+}
+
+/**
+ * What to do about the tokens that have to be replaced — none set, refused, or
+ * issued for another source — in the three steps it takes: issue one on
+ * molecules.cheminfo.org, write it in the server's `.env`, restart. Nothing
+ * when every token is fine.
+ * @param props - See {@link MoleculesTokenFixProps}.
+ * @returns The steps, or null.
+ */
+export function MoleculesTokenFix(
+  props: MoleculesTokenFixProps,
+): ReactElement | null {
+  const { checks, moleculesUrl = DEFAULT_MOLECULES_URL } = props;
+  const t = useChromeT();
+  const language = useLanguage();
+  const toFix = tokensToFix(checks);
+  if (toFix.length === 0) return null;
+
+  const one = toFix.length === 1;
+  const variables = new Intl.ListFormat(language, {
+    type: 'conjunction',
+  }).format(toFix.map((check) => check.variable));
+  const admin = `${trimTrailingSlash(moleculesUrl)}/admin`;
+  const unsetOnly = toFix.every((check) => check.verdict === 'unset');
+
+  return (
+    <Callout
+      intent={unsetOnly ? 'warning' : 'danger'}
+      icon="key"
+      title={t('moleculesToken.fix.title', { variables })}
+      className="molecules-tokens__fix"
+      data-testid="molecules-tokens-fix"
+    >
+      <ol>
+        <li>
+          <p>
+            {t(
+              one
+                ? 'moleculesToken.fix.issueOne'
+                : 'moleculesToken.fix.issueMany',
+            )}{' '}
+            <a href={admin} target="_blank" rel="noreferrer">
+              {admin}
+            </a>
+          </p>
+          <p>{t('moleculesToken.fix.issueOnServer')}</p>
+          <CodeBlock
+            tone="muted"
+            copyable
+            code={[...new Set(toFix.map(issueTokenCommand))].join('\n')}
+          />
+        </li>
+        <li>
+          <p>
+            {t(
+              one ? 'moleculesToken.fix.envOne' : 'moleculesToken.fix.envMany',
+            )}
+          </p>
+          <CodeBlock
+            tone="muted"
+            copyable
+            code={toFix.map((check) => `${check.variable}=mct_…`).join('\n')}
+          />
+        </li>
+        <li>
+          <p>{t('moleculesToken.fix.restart')}</p>
+          <CodeBlock tone="muted" copyable code="docker compose up -d" />
+        </li>
+      </ol>
+    </Callout>
+  );
+}

package/src/moleculesToken/ui/MoleculesTokenTable.tsx

@@ -0,0 +1,175 @@
+import type { Intent } from '@blueprintjs/core';
+import { Button, Callout, HTMLTable, Tag } from '@blueprintjs/core';
+import { useMemo } from 'react';
+
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import { useLanguage } from '../../i18n/ui/useLanguage.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type {
+  MoleculesTokenCheck,
+  MoleculesTokenVerdict,
+} from '../core/moleculesToken.ts';
+import { tokensToFix } from '../core/tokenFix.ts';
+
+import { MoleculesTokenFix } from './MoleculesTokenFix.tsx';
+import { tokenDetails } from './tokenDetails.tsx';
+
+/** What {@link MoleculesTokenTable} shows. */
+export interface MoleculesTokenTableProps {
+  /** The last checks, or null before the first one was made. */
+  checks: readonly MoleculesTokenCheck[] | null;
+  /**
+   * Whether a check was asked for and is not made yet.
+   * @default false
+   */
+  pending?: boolean;
+  /**
+   * Asks for every token to be checked again. Left out, there is no button:
+   * a page anyone can open shows the last checks and asks for none.
+   * @default undefined
+   */
+  onCheckAgain?: () => void;
+  /**
+   * Why asking for a check failed.
+   * @default undefined
+   */
+  error?: string;
+  /**
+   * Where molecules.cheminfo.org answers, whose Admin page issues tokens.
+   * @default 'https://molecules.cheminfo.org'
+   */
+  moleculesUrl?: string;
+}
+
+const INTENT: Record<MoleculesTokenVerdict, Intent> = {
+  ok: 'success',
+  otherSource: 'danger',
+  refused: 'danger',
+  unset: 'warning',
+  uncheckable: 'warning',
+  unanswered: 'warning',
+};
+
+/** How each verdict reads in the table. */
+const LABEL: Record<MoleculesTokenVerdict, ChromeKey> = {
+  ok: 'moleculesToken.verdict.ok',
+  otherSource: 'moleculesToken.verdict.otherSource',
+  refused: 'moleculesToken.verdict.refused',
+  unset: 'moleculesToken.verdict.unset',
+  uncheckable: 'moleculesToken.verdict.uncheckable',
+  unanswered: 'moleculesToken.verdict.unanswered',
+};
+
+/** The command a token is issued with, on molecules.cheminfo.org. */
+const ISSUE_COMMAND = 'npm run tokens -- issue SOURCE EMAIL';
+
+/**
+ * The tokens a site holds for molecules.cheminfo.org, one row each, with what
+ * molecules.cheminfo.org said of it when it was last checked: valid, another
+ * source's, refused, not set. A token is changed in the server's `.env`, never
+ * here, so the table says where, and above it how, when one has to be.
+ * @param props - See {@link MoleculesTokenTableProps}.
+ * @returns The table.
+ */
+export function MoleculesTokenTable(props: MoleculesTokenTableProps) {
+  const { checks, pending = false, onCheckAgain, error, moleculesUrl } = props;
+  const t = useChromeT();
+  const language = useLanguage();
+  const formats = useMemo(
+    () => ({
+      instant: new Intl.DateTimeFormat(language, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+      }),
+      sources: new Intl.ListFormat(language, { type: 'disjunction' }),
+    }),
+    [language],
+  );
+  const checkedAt =
+    checks === null || checks.length === 0
+      ? null
+      : Math.min(...checks.map((check) => check.checkedAt));
+
+  return (
+    <section
+      className="molecules-tokens"
+      aria-label={t('moleculesToken.title')}
+      data-testid="molecules-tokens"
+    >
+      <div className="molecules-tokens__head">
+        <span className="molecules-tokens__title">
+          {t('moleculesToken.title')}
+        </span>
+        {checkedAt !== null && (
+          <span className="molecules-tokens__muted">
+            {t('moleculesToken.checkedAt', {
+              when: formats.instant.format(checkedAt),
+            })}
+          </span>
+        )}
+        {onCheckAgain !== undefined && (
+          <Button
+            size="small"
+            variant="minimal"
+            icon="refresh"
+            loading={pending}
+            text={t('moleculesToken.checkAgain')}
+            onClick={onCheckAgain}
+            data-testid="molecules-tokens-check"
+          />
+        )}
+      </div>
+      {error !== undefined && (
+        <Callout compact intent="danger">
+          {error}
+        </Callout>
+      )}
+      {checks !== null && (
+        <MoleculesTokenFix checks={checks} moleculesUrl={moleculesUrl} />
+      )}
+      {checks === null ? (
+        <p className="molecules-tokens__muted">
+          {t('moleculesToken.notChecked')}
+        </p>
+      ) : (
+        <div className="molecules-tokens__scroll">
+          <HTMLTable compact striped className="molecules-tokens__table">
+            <thead>
+              <tr>
+                <th>{t('moleculesToken.column.variable')}</th>
+                <th>{t('moleculesToken.column.source')}</th>
+                <th>{t('moleculesToken.column.status')}</th>
+                <th>{t('moleculesToken.column.details')}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {checks.map((check) => (
+                <tr key={check.variable} data-verdict={check.verdict}>
+                  <td>
+                    <code>{check.variable}</code>
+                  </td>
+                  <td>
+                    {check.sources.length === 0
+                      ? t('moleculesToken.anySource')
+                      : formats.sources.format(check.sources)}
+                  </td>
+                  <td>
+                    <Tag minimal intent={INTENT[check.verdict]}>
+                      {t(LABEL[check.verdict])}
+                    </Tag>
+                  </td>
+                  <td>{tokenDetails(check, t, formats.instant)}</td>
+                </tr>
+              ))}
+            </tbody>
+          </HTMLTable>
+        </div>
+      )}
+      {(checks === null || tokensToFix(checks).length === 0) && (
+        <p className="molecules-tokens__muted">
+          {t('moleculesToken.howToChange')} <code>{ISSUE_COMMAND}</code>
+        </p>
+      )}
+    </section>
+  );
+}

package/src/moleculesToken/ui/index.ts

@@ -0,0 +1,4 @@
+export type { MoleculesTokenFixProps } from './MoleculesTokenFix.tsx';
+export { MoleculesTokenFix } from './MoleculesTokenFix.tsx';
+export type { MoleculesTokenTableProps } from './MoleculesTokenTable.tsx';
+export { MoleculesTokenTable } from './MoleculesTokenTable.tsx';

package/src/moleculesToken/ui/tokenDetails.tsx

@@ -0,0 +1,91 @@
+import type { ReactNode } from 'react';
+
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { Translate } from '../../i18n/ui/useT.ts';
+import type { MoleculesTokenCheck } from '../core/moleculesToken.ts';
+
+/**
+ * What a row says besides its verdict.
+ * @param check - The check.
+ * @param t - The chrome's translator.
+ * @param instant - How an instant is written.
+ * @returns The cell's content.
+ */
+export function tokenDetails(
+  check: MoleculesTokenCheck,
+  t: Translate<ChromeKey>,
+  instant: Intl.DateTimeFormat,
+): ReactNode {
+  const hint: Fact | null =
+    check.hint === null
+      ? null
+      : ['hint', <code key="hint">{check.hint}…</code>];
+  switch (check.verdict) {
+    case 'ok':
+      return facts([
+        check.sources.length === 1 || check.source === null
+          ? null
+          : ['source', t('moleculesToken.forSource', { source: check.source })],
+        check.issuedAt === null
+          ? null
+          : [
+              'issued',
+              check.email === null
+                ? t('moleculesToken.issued', {
+                    when: instant.format(check.issuedAt),
+                  })
+                : t('moleculesToken.issuedTo', {
+                    email: check.email,
+                    when: instant.format(check.issuedAt),
+                  }),
+            ],
+        [
+          'used',
+          check.lastUsedAt === null
+            ? t('moleculesToken.neverUsed')
+            : t('moleculesToken.lastUsed', {
+                when: instant.format(check.lastUsedAt),
+              }),
+        ],
+        hint,
+      ]);
+    case 'otherSource':
+      return facts([
+        [
+          'source',
+          t('moleculesToken.otherSourceDetail', {
+            source: check.source ?? '',
+          }),
+        ],
+        hint,
+      ]);
+    case 'refused':
+      return check.message ?? t('moleculesToken.refusedDetail');
+    case 'unset':
+      return t('moleculesToken.unsetDetail', { variable: check.variable });
+    case 'uncheckable':
+      return t('moleculesToken.uncheckableDetail');
+    case 'unanswered':
+      return check.message;
+    default:
+      return null;
+  }
+}
+
+/** One fact about a token, and the key it is drawn under. */
+type Fact = readonly [key: string, content: ReactNode];
+
+/**
+ * Facts about a token, one after the other.
+ * @param parts - The facts; null ones are left out.
+ * @returns The facts, separated by a middle dot.
+ */
+function facts(parts: ReadonlyArray<Fact | null>): ReactNode {
+  const shown = parts.filter((part) => part !== null);
+  return shown.map(([key, content], index) => (
+    <span key={key}>
+      {index > 0 && ' · '}
+      {content}
+    </span>
+  ));
+}

package/src/ui.ts

@@ -18,6 +18,8 @@ export * from './help/ui/index.ts';
 export * from './hooks/ui/index.ts';
 export * from './i18n/ui/index.ts';
 export * from './language/ui/index.ts';
+export * from './moleculesSources/ui/index.ts';
+export * from './moleculesToken/ui/index.ts';
 export * from './number/ui/index.ts';
 export * from './overlay/ui/index.ts';
 export * from './panel/ui/index.ts';