@tinvar/react 0.0.0-stage → 0.4.1

package/src/fragment-client.js

@@ -0,0 +1,510 @@
+// Fetching one deferred subtree.
+//
+// tinvar-spec.md, "Deferred components": "On the trigger, the client requests
+// `GET /_fragment/<token>` with `RSC: 1`. ... The response is RSC payload
+// only, sent `private, no-store` with a refreshed token."
+//
+// This module owns the request and the token lifecycle, and nothing else. It
+// does not know about React, triggers or the DOM, so the retry and refresh
+// rules can be read -- and tested -- without mounting anything.
+
+import { BootstrapError, bootstrapToken, isPlaceholder } from './bootstrap.js';
+import { LIVE_TOKEN_HEADER } from './router.js';
+
+export const FRAGMENT_PREFIX = '/_fragment/';
+export const TOKEN_HEADER = 'x-fragment-token';
+
+/** What the endpoint promises to answer with. Anything else is not a fragment. */
+export const FRAGMENT_CONTENT_TYPE = 'text/x-component';
+
+/** The shape a token the server issued always has. */
+const TOKEN_SHAPE = /^v1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+
+/** Floor between two loads of one boundary, and the base for backoff. */
+export const MIN_INTERVAL_MS = 250;
+
+/** After this many consecutive failures a boundary stops trying. */
+export const MAX_FAILURES = 5;
+
+export class FragmentError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} status
+   * @param {string | null} [digest] what the server logged a 5xx under
+   */
+  constructor(message, status, digest = null) {
+    super(message);
+    this.name = 'FragmentError';
+    this.status = status;
+    this.digest = digest;
+  }
+}
+
+/** What a digest the server sends looks like; anything else is not shown. */
+const DIGEST_SHAPE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * Whether a failed load was the server's render throwing -- and so already
+ * reported, with a digest -- rather than a request that never got a proper
+ * answer. Only that is what a boundary's `rescue` slot is for
+ * (tinvar-spec.md, "Rescue and reloading"): an offline blip or a 429 is
+ * retried, and a 404 means the page has to be reloaded.
+ *
+ * Two shapes reach here. PHP failing -- the render channel, the renderer
+ * process, the route's own code -- is a 5xx from the exception handler.
+ * A component throwing inside the renderer is an error row React writes in
+ * the payload, which surfaces as an error carrying the digest the renderer
+ * gave it: when the payload is decoded, if it was the fragment's root, or
+ * when it renders, if it was further down.
+ *
+ * @param {unknown} error
+ * @returns {{ digest: string | null } | null}
+ */
+export function serverFailure(error) {
+  if (error instanceof FragmentError) {
+    return error.status >= 500 ? { digest: error.digest } : null;
+  }
+  const digest = /** @type {{ digest?: unknown } | null} */ (error)?.digest;
+  return typeof digest === 'string' ? { digest: DIGEST_SHAPE.test(digest) ? digest : null } : null;
+}
+
+/**
+ * Holds one boundary's token across refetches.
+ *
+ * The token rotates: every response carries a replacement, so a boundary that
+ * refreshes on a timer outlives the original hour. Keeping the LATEST one is
+ * the whole mechanism -- reusing the first token forever would start failing
+ * at the expiry, which is exactly the case refresh boundaries exist for.
+ */
+export class FragmentHandle {
+  #token;
+  #fetch;
+  #inFlight = null;
+  /** The signal the request in flight was started under. */
+  #inFlightSignal = undefined;
+  #failures = 0;
+  #notBefore = 0;
+  #terminal = null;
+  /** The status a terminal handle keeps answering with. */
+  #terminalStatus = 404;
+  /** What the last load's render read, signed: the boundary listens with it. */
+  #liveToken = null;
+
+  /**
+   * @param {string} token
+   * @param {typeof fetch} [fetchImpl]
+   */
+  constructor(token, fetchImpl) {
+    this.#token = token;
+    this.#fetch = fetchImpl ?? globalThis.fetch?.bind(globalThis);
+  }
+
+  get token() {
+    return this.#token;
+  }
+
+  /**
+   * The live token the last successful load came with -- the topics of the
+   * tags its render read -- or null when it read none, or the server has no
+   * live updates. A group's members share their one render's.
+   *
+   * @returns {string | null}
+   */
+  get liveToken() {
+    return this.#liveToken;
+  }
+
+  /** Whether this handle has given up: a 404, a 401, or too many failures. */
+  get terminal() {
+    return this.#terminal !== null;
+  }
+
+  /**
+   * Takes a token the server issued afresh for the same boundary -- a
+   * re-render of the page mints a new one each time. The backoff and the
+   * gap between requests carry over; a 404 does not, since it was this
+   * server's answer to the OLD token and the new one has not been tried, and
+   * neither does the failure count.
+   *
+   * @param {string} token
+   */
+  adopt(token) {
+    this.#token = token;
+    this.#terminal = null;
+    // A fresh token earns a fresh count. Kept, a handle that had reached the
+    // limit went terminal again after one try with the new token. The
+    // pacing -- the earliest next request -- is kept.
+    this.#failures = 0;
+  }
+
+  /**
+   * Fetches the subtree.
+   *
+   * Concurrent calls share one request. A boundary can be asked to load by a
+   * trigger and by a revalidation in the same tick, and two requests would
+   * mean two renders of the same subtree racing to mount.
+   *
+   * With `decode`, the body is decoded here and the load resolves with what
+   * it returns. A 200 that cannot be decoded is a failed load as much as a
+   * 500 is; decoded by the caller after the handle had counted the 200 as a
+   * success, it reset the failure count and was retried every 250 ms for
+   * good. Shared requests share the decoded result, so one stream is never
+   * read twice.
+   *
+   * `headers` are the claims the request makes: X-Have-Shared alone is sent.
+   *
+   * @template [T=ReadableStream<Uint8Array>]
+   * @param {{signal?: AbortSignal, decode?: (stream: ReadableStream<Uint8Array>) => T | Promise<T>, headers?: Record<string, string>}} [options]
+   * @returns {Promise<T>}
+   */
+  load(options = {}) {
+    // A boundary the server has finished with stops asking. The 404 it
+    // answers covers every reason -- expired, wrong session, revoked build --
+    // and none of them get better by retrying.
+    if (this.#terminal) {
+      return Promise.reject(new FragmentError(this.#terminal, this.#terminalStatus));
+    }
+
+    // Shared, unless whoever started it has since abandoned it. React's
+    // Strict Mode mounts a boundary, unmounts it -- aborting its load -- and
+    // mounts it again at once; handing the second mount the first one's
+    // aborted request left it reporting an abort it never asked for, with
+    // the fallback on screen for good.
+    if (this.#inFlight && !this.#inFlightSignal?.aborted) return this.#inFlight;
+
+    // `always` boundaries refetch on every intersection, and an element that
+    // oscillates across the rootMargin edge -- a sticky header, an animation,
+    // momentum scroll -- would otherwise be a request storm, each request a
+    // full server render. Backoff after a failure, a floor between successes.
+    const wait = Math.max(0, this.#notBefore - Date.now());
+
+    const attempt = (wait > 0 ? sleep(wait) : Promise.resolve())
+      .then(() => {
+        // Abandoned during the wait -- the boundary was destroyed. Nothing
+        // is sent: a native fetch would refuse an aborted signal, but an
+        // injected one need not honour it.
+        if (options.signal?.aborted) {
+          throw new DOMException('The fragment load was aborted.', 'AbortError');
+        }
+        return this.#request(options);
+      })
+      .finally(() => {
+        // Only its own slot: an abandoned request settling late must not
+        // clear the one that replaced it.
+        if (this.#inFlight !== attempt) return;
+        this.#inFlight = null;
+      });
+
+    // The stored promise can reject while a caller is still waiting on a
+    // timer before it attaches its handler, and Node reports that as an
+    // unhandled rejection even though the caller does handle it a tick later.
+    // The swallowing handler is on a derived promise, so the one returned
+    // still rejects for whoever asked.
+    attempt.catch(() => {});
+    this.#inFlight = attempt;
+    this.#inFlightSignal = options.signal;
+
+    return attempt;
+  }
+
+  #request(options) {
+    return FragmentHandle.#send([this], options);
+  }
+
+  /**
+   * Fetches the boundaries of one <Deferred group> in one request:
+   * `GET /_fragment/<token>/<token>/...` (ADR 0018).
+   *
+   * The handles' own rules hold for all of them at once: none is sent while
+   * one has given up -- the server refuses a group for any token it will
+   * not act on -- the wait is the longest any of them owes, and a failure is
+   * counted against each. The payload's root is the list of their subtrees
+   * in the order of the handles, which is what this resolves with.
+   *
+   * @param {FragmentHandle[]} handles two or more, from one provider
+   * @param {{signal?: AbortSignal, decode: (stream: ReadableStream<Uint8Array>) => unknown, headers?: Record<string, string>}} options
+   * @returns {Promise<unknown[]>}
+   */
+  static loadGroup(handles, options) {
+    const done = handles.find((handle) => handle.#terminal !== null);
+    if (done) {
+      return Promise.reject(new FragmentError(done.#terminal, done.#terminalStatus));
+    }
+
+    const wait = Math.max(0, ...handles.map((handle) => handle.#notBefore - Date.now()));
+
+    return (wait > 0 ? sleep(wait) : Promise.resolve()).then(() => {
+      if (options.signal?.aborted) {
+        throw new DOMException('The fragment load was aborted.', 'AbortError');
+      }
+      return FragmentHandle.#send(handles, options);
+    });
+  }
+
+  /**
+   * One request for one boundary or a group's, and what each handle makes
+   * of the answer -- one path, so a group cannot drift from the rules a lone
+   * boundary has had to learn.
+   *
+   * @param {FragmentHandle[]} handles
+   * @param {{signal?: AbortSignal, decode?: (stream: ReadableStream<Uint8Array>) => unknown, headers?: Record<string, string>}} options
+   *   `headers` are the claims the request makes: X-Have-Shared, the
+   *   once-shared values' holds (ADR 0074), and nothing else
+   */
+  static async #send(handles, { signal, decode, headers: claims = {} }) {
+    const fetchImpl = handles[0].#fetch;
+    if (!fetchImpl) {
+      throw new FragmentError('No fetch implementation available.', 0);
+    }
+
+    const failed = () => {
+      for (const handle of handles) handle.#fail();
+    };
+
+    // A statically built page's boundaries carry a placeholder, not a token:
+    // the visitor's own come from /_bootstrap, the first time each loads,
+    // and are kept -- and rotated -- from then on like any other.
+    try {
+      await Promise.all(
+        handles.map(async (handle) => {
+          if (isPlaceholder(handle.#token)) handle.#token = await bootstrapToken(handle.#token, fetchImpl);
+        }),
+      );
+    } catch (error) {
+      if (isAbort(error, signal)) throw error;
+      failed();
+      // The server knows no such built page: an old copy, which no retry
+      // makes current.
+      if (error instanceof BootstrapError && error.status === 404) {
+        for (const handle of handles) {
+          handle.#terminal = 'This page is out of date; reload it.';
+          handle.#terminalStatus = 404;
+        }
+      }
+      throw new FragmentError(
+        error instanceof Error ? error.message : 'Bootstrap failed.',
+        error?.status ?? 0,
+      );
+    }
+
+    const sent = handles.map((handle) => handle.#token);
+
+    let response;
+    try {
+      response = await fetchImpl(FRAGMENT_PREFIX + sent.map(encodeURIComponent).join('/'), {
+        method: 'GET',
+        // "with RSC: 1" -- the same header a page's payload request uses, so
+        // caches that key on it keep the two apart.
+        headers: { ...sharedClaims(claims), RSC: '1', accept: FRAGMENT_CONTENT_TYPE },
+        credentials: 'same-origin',
+        // credentials governs COOKIES, not origin. Without these two, a
+        // cross-origin redirect anywhere in front of /_fragment/* -- a global
+        // middleware bouncing an expired session to an external IdP is the
+        // realistic shape -- would be followed, and a permissive destination
+        // could then supply both the body and the rotated token. An RSC payload
+        // carries client-module rows, so a forged stream is a module-loading
+        // primitive: the one path in this feature that reaches script execution.
+        mode: 'same-origin',
+        redirect: 'error',
+        cache: 'no-store',
+        signal,
+      });
+    } catch (error) {
+      // A request that never got an answer -- offline, a reset connection,
+      // the redirect refused just above -- is a failure like any status. It
+      // skipped the count, so a boundary on screen re-armed and asked again
+      // at once, every frame, with no backoff and no limit. Being abandoned
+      // is not a failure: nothing was wrong with the fragment.
+      if (!isAbort(error, signal)) failed();
+      throw error;
+    }
+
+    if (!response.ok) {
+      // The server says one thing for every rejection -- expired, wrong
+      // session, revoked build, no such fragment -- so there is nothing to
+      // branch on and nothing worth showing a user. A 404 is final: the page
+      // has to be reloaded to get a token this server will act on.
+      failed();
+      for (const handle of handles) {
+        if (response.status === 404) {
+          handle.#terminal = 'This fragment is no longer available; reload the page.';
+          handle.#terminalStatus = 404;
+        }
+
+        // A 401 is final too, and about the session rather than the token:
+        // "session revocation, which the server signals with a 401"
+        // (tinvar-spec.md, "Client-held data"). Retried as an ordinary
+        // failure, the boundary went on asking with a session the server had
+        // refused. Whoever holds the handle reloads the page; see
+        // DeferredBoundary.
+        if (response.status === 401) {
+          handle.#terminal = 'The session has ended; reload the page.';
+          handle.#terminalStatus = 401;
+        }
+      }
+
+      // A 5xx is the exception handler's answer, which carries the digest
+      // the failure was logged under -- the reference a rescue slot shows.
+      const digest = response.status >= 500 ? await loggedDigest(response) : null;
+
+      throw new FragmentError(`Fragment request failed with ${response.status}.`, response.status, digest);
+    }
+
+    // Rotated only on success, and only if it looks like a token this server
+    // issued. The endpoint deliberately withholds the header on a failure, so
+    // a replacement arriving with one came from somewhere else -- and storing
+    // it bricked the boundary until reload.
+    // The rotation of the token this request SENT. If a fresher token was
+    // adopted while it was in flight -- a re-render of the page -- that one
+    // wins: the rotation descends from the old token and keeps its older
+    // absolute lifetime.
+    // A group's arrive comma-separated in the order they were sent, all or
+    // none; a list of any other length cannot be paired with its boundaries.
+    const refreshed = (response.headers.get(TOKEN_HEADER) ?? '').split(',');
+    if (refreshed.length === handles.length && refreshed.every((token) => TOKEN_SHAPE.test(token))) {
+      handles.forEach((handle, i) => {
+        if (handle.#token === sent[i]) handle.#token = refreshed[i];
+      });
+    }
+
+    // The endpoint answers one content type. Anything else is not a fragment,
+    // and handing it to the mount callback would feed it to the RSC reader.
+    const type = response.headers.get('content-type') ?? '';
+    if (!type.startsWith(FRAGMENT_CONTENT_TYPE)) {
+      failed();
+
+      throw new FragmentError(
+        `Fragment response was ${type || 'untyped'}, not ${FRAGMENT_CONTENT_TYPE}.`,
+        response.status,
+      );
+    }
+
+    if (!response.body) {
+      failed();
+
+      throw new FragmentError('Fragment response had no body.', response.status);
+    }
+
+    for (const handle of handles) handle.#notBefore = Date.now() + MIN_INTERVAL_MS;
+
+    if (!decode) {
+      const live = response.headers.get(LIVE_TOKEN_HEADER);
+      for (const handle of handles) {
+        handle.#failures = 0;
+        handle.#liveToken = live !== null && TOKEN_SHAPE.test(live) ? live : null;
+      }
+      return response.body;
+    }
+
+    let decoded;
+    try {
+      decoded = await decode(response.body);
+    } catch (error) {
+      if (!isAbort(error, signal)) failed();
+      throw error;
+    }
+
+    // A group's payload is the list of its subtrees, one per boundary. Any
+    // other root cannot be shared out, and is a failed load like any other.
+    if (handles.length > 1 && (!Array.isArray(decoded) || decoded.length !== handles.length)) {
+      failed();
+
+      throw new FragmentError('A group response did not carry one subtree per boundary.', response.status);
+    }
+
+    // Only now is the load a success: the count resets once there is
+    // something to show -- and what it read is what the boundary listens to.
+    const live = response.headers.get(LIVE_TOKEN_HEADER);
+    for (const handle of handles) {
+      handle.#failures = 0;
+      handle.#liveToken = live !== null && TOKEN_SHAPE.test(live) ? live : null;
+    }
+
+    return decoded;
+  }
+
+  #fail() {
+    this.#failures++;
+
+    if (this.#failures >= MAX_FAILURES) {
+      this.#terminal = `This fragment failed ${this.#failures} times and will not be retried.`;
+      this.#terminalStatus = 404;
+      return;
+    }
+
+    // Exponential, from the same floor a successful load uses.
+    this.#notBefore = Date.now() + MIN_INTERVAL_MS * 2 ** this.#failures;
+  }
+}
+
+/**
+ * Whether a load ended because its caller left rather than because it failed.
+ *
+ * @param {unknown} error
+ * @param {AbortSignal | undefined} signal
+ */
+function isAbort(error, signal) {
+  return signal?.aborted === true || /** @type {{ name?: unknown } | null} */ (error)?.name === 'AbortError';
+}
+
+/**
+ * The digest in the exception handler's JSON body, or null for any other
+ * body -- a proxy's HTML page, nothing at all.
+ *
+ * @param {Response} response
+ * @returns {Promise<string | null>}
+ */
+async function loggedDigest(response) {
+  if (!(response.headers.get('content-type') ?? '').includes('application/json')) return null;
+  try {
+    const digest = (await response.json())?.error?.digest;
+    return typeof digest === 'string' && DIGEST_SHAPE.test(digest) ? digest : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {number} ms */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * The claims a fragment request may carry: X-Have-Shared, the once-shared
+ * values' holds, and nothing else -- whatever else a caller passed is not a
+ * claim, and a fragment request has no business sending it.
+ *
+ * @param {Record<string, string>} claims
+ * @returns {Record<string, string>}
+ */
+function sharedClaims(claims) {
+  for (const [name, value] of Object.entries(claims ?? {})) {
+    if (name.toLowerCase() === 'x-have-shared' && typeof value === 'string' && value !== '') {
+      return { 'X-Have-Shared': value };
+    }
+  }
+  return {};
+}
+
+/**
+ * What a fragment token is FOR, without when it was issued or expires: its
+ * signed claims minus `i` and `e`. Two tokens with the same identity name the
+ * same component, props, route and binding. Read without verifying -- the
+ * payload is plain base64url JSON, and nothing here trusts it; it only
+ * decides whether a boundary already on screen can keep what it shows.
+ *
+ * @param {string | null} token
+ * @returns {string | null}
+ */
+export function tokenIdentity(token) {
+  if (token === null) return null;
+  try {
+    const body = token.split('.')[1] ?? '';
+    const json = atob(body.replace(/-/g, '+').replace(/_/g, '/'));
+    const { i: _issued, e: _expires, ...claims } = JSON.parse(json);
+    return JSON.stringify(claims);
+  } catch {
+    // Not a shape this understands: only an identical token is the same.
+    return token;
+  }
+}

package/src/head.d.ts

@@ -0,0 +1,85 @@
+import type { ReactNode } from 'react';
+
+/** Marks a tag PHP rendered for a component's to replace. */
+export declare const FALLBACK_ATTRIBUTE: 'data-tinvar-head';
+export declare const FALLBACK: 'fallback';
+/** The key a tag is deduplicated by, on the element. */
+export declare const KEY_ATTRIBUTE: 'data-tinvar-key';
+/** Its depth in the route, on the element. */
+export declare const DEPTH_ATTRIBUTE: 'data-tinvar-depth';
+/** The key every title shares. */
+export declare const TITLE_KEY: 'title';
+
+/** The key a meta tag is deduplicated by, or null for one never deduplicated. */
+export declare function metaKey(props: Record<string, unknown>): string | null;
+
+/**
+ * The key a link is deduplicated by: `headKey`; canonical by its rel alone;
+ * alternate with an hreflang by its language; an icon by its sizes, media
+ * and type; anything else by its rel and href. Null for a stylesheet, which is
+ * React's, and for a link with nothing to key it by.
+ */
+export declare function linkKey(props: Record<string, unknown>): string | null;
+
+export interface HeadStore {
+  register(id: string, key: string, depth: number): () => void;
+  wins(id: string): boolean;
+  subscribe(listener: () => void): () => void;
+}
+
+export declare function createHeadStore(): HeadStore;
+
+/**
+ * Puts the winning title first in the head -- the deepest, a raw <title> at
+ * the document's depth, a fallback below all -- moving it, never removing
+ * any. Returns the winner, or null for a head with no title.
+ */
+export declare function arrangeTitles(head: HTMLHeadElement): Element | null;
+
+/**
+ * The title template and default around the document. `titleTemplate` holds
+ * `%s` where a <Title>'s text goes; `defaultTitle` is the title when no
+ * component names one.
+ */
+export declare function HeadProvider(props: {
+  titleTemplate?: string;
+  defaultTitle?: string;
+  children?: ReactNode;
+}): ReactNode;
+
+/** The document's title: one, the deepest in the route, through the template. */
+export declare function Title(props: { children: string | number | readonly (string | number)[] }): ReactNode;
+
+/** A meta tag: one per name, property or http-equiv, or per `headKey`. */
+export declare function Meta(
+  props: {
+    name?: string;
+    property?: string;
+    httpEquiv?: string;
+    charSet?: string;
+    content?: string;
+    headKey?: string;
+  } & Record<string, string | undefined>,
+): ReactNode;
+
+/**
+ * A link in the head: one canonical URL, one icon per size, media and type, one
+ * alternate per language, no link written twice -- or one per `headKey`.
+ * The deepest in the route wins. A stylesheet renders as React's own
+ * <link>, deduplicated and ordered by React.
+ */
+export declare function HeadLink(
+  props: {
+    rel: string;
+    href?: string;
+    hrefLang?: string;
+    sizes?: string;
+    media?: string;
+    type?: string;
+    as?: string;
+    crossOrigin?: '' | 'anonymous' | 'use-credentials';
+    title?: string;
+    precedence?: string;
+    headKey?: string;
+  } & Record<string, string | undefined>,
+): ReactNode;