@uniflowed/server 0.0.0-alpha.10

package/fetch.js

@@ -0,0 +1,310 @@
+// @flow
+//
+// `@uniflowed/server/fetch`: a built uf application as `Request` → `Response`.
+//
+// This is the seam every deploy adapter is written against, and it is one
+// function: give it the module `uf build` wrote and the asset URLs from the
+// client manifest, and it answers a request. It touches no filesystem, holds
+// no Node types, and imports nothing from `@uniflowed/vite` — so the same
+// handler runs inside `uf start`'s `node:http` loop, inside the `server.js`
+// that `uf build --adapter node` writes, and inside a worker's `fetch` export.
+//
+// # Why it lives here and not where it was written
+//
+// It was `createApplicationHandler` in `@uniflowed/vite/internal/serve.js`,
+// and `tests/library/serve.test.js` said what was wrong with that: "not a
+// package export, deliberately — `internal/serve.js` is the seam a deploy
+// adapter will need, and naming it in `exports` before one exists would be
+// promising an interface nothing has used yet". An adapter exists now, and it
+// may not import the package named after the bundler: the whole claim of
+// deployable output is that the host needs neither Vite nor the toolchain that
+// produced the build. So the seam moved to the package a deployment already
+// links — `@uniflowed/server` — and `internal/serve.js` calls into it, which
+// keeps `uf preview`, `uf start` and every adapter answering out of one
+// function rather than out of copies that agree until they do not.
+//
+// `./standalone.js` is the one front door that does not come through here, and
+// its own header says why: a compiled binary answers from bytes it carries
+// rather than from a directory, and it writes into a Node response directly so
+// that a document is not converted through a `Response` on its way out.
+//
+// # The route cache
+//
+// One `GET` at a time, and only where three things line up: the host passed a
+// `cache` whose `route` is on (`rendering.cache.route` in `uf.config.js`), the
+// render stated a lifetime with `cacheLife`, and the render did not read the
+// request. All three are argued in `./cache.js`; what belongs here is the one
+// cost that is this function's rather than the store's.
+//
+// **A cached route is buffered, and an uncached one is streamed.** The body has
+// to be whole before it can be an entry, so the fill reads the document to its
+// last byte before answering — which gives up the thing the streaming path
+// exists for, on the fill. It buys two things back. The hit is the whole
+// document at once with no render at all, which is faster than streaming a
+// render; and the read of `requestStateReads` is only trustworthy *after* the
+// last byte, because a component inside a `<Suspense>` boundary renders long
+// after the shell resolved and `cookies()` in one of those is exactly the read
+// that must stop the entry being stored. A cache that decided at the shell
+// would cache a document whose tail was about one person.
+//
+// So the trade is per route and stated by the route: say nothing and stream as
+// before, call `cacheLife` and buffer once per lifetime. `HEAD` never
+// participates in either direction — it neither fills an entry nor reads one —
+// because a `HEAD` is a request for a status and a length, and letting it fill
+// a document cache would let a request that wants no body pay for one.
+//
+// # What it deliberately does not do
+//
+// Static files. A build's assets and its prerendered documents are the *host's*
+// half — on a CDN-backed target they are not the application's job at all, and
+// on a Node host they are a directory read, which is why `./node.js` has that
+// half and this module has none of it. That split is the whole reason an
+// adapter can be written for a worker: what is left after the files is exactly
+// this function.
+
+import { noStore } from "./cache.js";
+import type { Application, DocumentAssets } from "./internal/application.js";
+import type { CacheOptions, CacheOutcome } from "./internal/cache-store.js";
+import { newScope, runInScope } from "./internal/cache-store.js";
+import type { RequestContext } from "./internal/context.js";
+import { currentContext } from "./internal/context.js";
+
+export type { Application, DocumentAssets, RenderedDocument } from "./internal/application.js";
+
+/** Everything the application half needs to answer a request. */
+export type FetchHandlerOptions = {|
+  /** The server bundle, as imported. */
+  readonly app: Application,
+  /** The script, stylesheet and preload URLs a rendered document references. */
+  readonly document: DocumentAssets,
+  /**
+   * The cache this host installed, from `rendering.cache` in `uf.config.js`.
+   *
+   * Absent is the default and means no cache at all — every request renders,
+   * exactly as before this option existed. A host that passes one is saying
+   * two separate things with it, `route` and `fetch`, because the two switches
+   * in the configuration are two switches.
+   */
+  readonly cache?: CacheOptions,
+|};
+
+/** A whole document, as an entry: what a hit answers with without rendering. */
+type CachedDocument = {|
+  readonly status: number,
+  readonly headers: { readonly [string]: string },
+  readonly body: Uint8Array,
+|};
+
+/**
+ * The application half: middleware, then route handlers, then rendering.
+ *
+ * Returns `null` for nothing, ever — a request that matches no handler and no
+ * route is a rendered 404, because the renderer is what knows what the
+ * project's `_uf.not-found` page says.
+ *
+ * The order is the dev server's, and has to stay the dev server's: middleware
+ * first, then handlers for every method, because a handler is the only thing
+ * that can answer a `POST` and it may also answer a `GET` for a path that has
+ * no page. A page cannot answer a `POST`, so a non-navigation that no handler
+ * claimed is a 404 rather than a rendered page with a 200.
+ *
+ * Middleware above both, and not inside either: it guards a path, so it has to
+ * run for a page, for a route handler, and for a path under it that matches
+ * neither — `/dashboard/typo` is a 404 that the guard on `/dashboard` still
+ * answers. `app.runMiddleware` is called rather than tested for, so a server
+ * bundle without it is a `TypeError` on the first request instead of an
+ * application whose auth check quietly stopped running once it was built.
+ * That is the whole of ubugeeei-prod/uf#260, and every host that reaches this
+ * function is one more place it could have happened.
+ *
+ * # It must be called inside a request, and does not begin one
+ *
+ * `after()` says "once the response has been sent", and this function has a
+ * `Response` in hand rather than a response on the wire — for a streamed body
+ * those are a document apart. So the host begins the request with
+ * `app.beginRequest`, runs this inside `run`, and settles it after the bytes:
+ * `./node.js`'s `nodeListener` does that for `uf start` and for the `server.js`
+ * an adapter writes, and `@uniflowed/vite`'s `withRequest` does it for `uf dev`
+ * and `uf preview`.
+ *
+ * A worker-shaped host is the one uf does not write, and it has the same two
+ * halves to place. `settle` is what to hand `ctx.waitUntil` where there is one;
+ * without one, the honest moment is when the response body stream closes — and
+ * a runtime that tears the isolate down at that moment drops the callback,
+ * which is worth saying out loud rather than leaving to be discovered.
+ *
+ * A caller that forgets is not left to discover *that*, at least:
+ * `app.runMiddleware` refuses outside a request and names what establishes one.
+ * See ubugeeei-prod/uf#389.
+ *
+ * # And the cache, if the host installed one
+ *
+ * `cache` is `rendering.cache` from `uf.config.js`, and it does two separate
+ * things here. It is put on the request before the guard runs, so that a route
+ * handler or a server action calling `revalidateTag()` reaches the store that
+ * is answering this request; and, when `route` is on, a `GET` goes through
+ * [`cachedDocument`] instead of the streaming path. Both halves are argued in
+ * the module header and in `./cache.js`. With no `cache` at all this function
+ * is what it has always been, one `AsyncLocalStorage.run` aside.
+ */
+export function createFetchHandler(
+  options: FetchHandlerOptions,
+): (request: Request) => Promise<Response> {
+  const { app, cache, document } = options;
+
+  return async function handle(request: Request): Promise<Response> {
+    // Before the guard, not after it. A route handler and a server action both
+    // run inside `dispatch`, and `revalidateTag()` in one of them has to reach
+    // the store that is answering this request — a mutation that invalidates
+    // nothing is the failure this whole seam exists to prevent, and it would
+    // be a silent one.
+    const context = currentContext();
+    if (context != null && cache != null) {
+      context.cache = cache;
+    }
+
+    const guarded = await app.runMiddleware(request);
+    if (guarded != null) return guarded;
+
+    const handled = await app.dispatch(request);
+    if (handled != null) return handled;
+
+    const method = request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD") {
+      return new Response(null, { status: 404 });
+    }
+
+    const url = new URL(request.url);
+    const target = url.pathname + url.search;
+    // Nothing better than the console here: this function is what a worker or
+    // a serverless invocation wraps, and it has no terminal of its own. Losing
+    // a boundary's exception entirely would be worse — it is the only trace a
+    // page that failed after its first byte leaves anywhere.
+    const onError = (error: mixed) => {
+      console.error(error);
+    };
+
+    if (method === "GET" && cache != null && cache.route === true) {
+      return cachedDocument(app, cache, context, url, target, document, onError);
+    }
+
+    // Rendered inside a scope even with no cache in sight, so that a component
+    // calling `cacheLife` is a component that states a lifetime nobody is
+    // honouring rather than a component that throws. Turning the route cache
+    // off must not change what an application is allowed to say.
+    const result = await runInScope(newScope({ key: [] }), () =>
+      app.render(target, document, { onError }),
+    );
+    const headers = new Headers(result.headers ?? {});
+    headers.set("content-type", "text/html; charset=utf-8");
+    // A `HEAD` gets the status and the headers and no body, which is what the
+    // renderer cannot know to do for itself. The stream is cancelled rather
+    // than dropped, so the render behind it stops instead of filling its queue
+    // and waiting for a reader that is never coming.
+    if (method === "HEAD") {
+      await result.stream().cancel();
+      return new Response(null, { status: result.status ?? 200, headers });
+    }
+    // The body is a stream, so the layouts and any `<Suspense>` fallback reach
+    // the browser while the page they surround is still resolving.
+    return new Response(result.stream(), { status: result.status ?? 200, headers });
+  };
+}
+
+/**
+ * Answer a `GET` from the route cache, filling it if it has to.
+ *
+ * The fill is the interesting half, and everything it refuses is refused for a
+ * reason it can name:
+ *
+ * * **The render read the request.** `requestStateReads` is compared across the
+ *   whole document rather than across the shell; see the module header.
+ * * **The render did not answer 200.** A 404 or a 500 is a fact about this
+ *   moment far more often than it is a fact about the URL, and a cached 500 is
+ *   an outage that outlives its cause.
+ * * **The render set a cookie.** A `Set-Cookie` in a shared entry is one
+ *   person's session handed to the next reader. This is belt and braces — a
+ *   render that set a cookie almost certainly read one first — and it is here
+ *   because the cost of being wrong is not symmetric.
+ *
+ * A render that states no lifetime is refused by the store itself, which is
+ * where "no lifetime, no entry" belongs: it is a property of the cache, not of
+ * documents.
+ */
+async function cachedDocument(
+  app: Application,
+  cache: CacheOptions,
+  context: RequestContext | null,
+  url: URL,
+  target: string,
+  document: DocumentAssets,
+  onError: (error: mixed) => void,
+): Promise<Response> {
+  const result = await cache.store.resolve(
+    { key: ["route", "GET", url.pathname, url.search], path: url.pathname },
+    async (): Promise<CachedDocument> => {
+      const before = context?.requestStateReads ?? 0;
+      const rendered = await app.render(target, document, { onError });
+      const body = await drain(rendered.stream());
+      const status = rendered.status ?? 200;
+      const headers: { [string]: string } = { ...(rendered.headers ?? {}) };
+
+      if (status !== 200) {
+        noStore(`the render answered ${status}`);
+      } else if (Object.keys(headers).some((name) => name.toLowerCase() === "set-cookie")) {
+        noStore("the render set a cookie");
+      } else if ((context?.requestStateReads ?? 0) > before) {
+        noStore("the render read cookies(), headers() or draftMode()");
+      }
+      return { status, headers, body };
+    },
+  );
+
+  const headers = new Headers(result.value.headers);
+  headers.set("content-type", "text/html; charset=utf-8");
+  // What this request did to the cache, in one word. It is the only way to see
+  // a cache working from outside the process — a benchmark reads it, and so
+  // does anybody wondering why a page is fast.
+  headers.set("x-uf-cache", label(result.outcome));
+  return new Response(result.value.body, { status: result.value.status, headers });
+}
+
+/** The header word for an outcome. */
+function label(outcome: CacheOutcome): string {
+  return match (outcome) {
+    "hit" => "HIT",
+    "stale" => "STALE",
+    "coalesced" => "COALESCED",
+    "miss" => "MISS",
+    "uncacheable" => "BYPASS",
+  };
+}
+
+/**
+ * Every byte of `stream`, as one array.
+ *
+ * The chunks are collected and joined once rather than concatenated as they
+ * arrive: a document is a few hundred chunks, and growing an array per chunk
+ * copies the whole document per chunk.
+ */
+async function drain(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Array<Uint8Array> = [];
+  let total = 0;
+  for (;;) {
+    const step = await reader.read();
+    if (step.done === true) break;
+    const chunk = step.value;
+    if (chunk != null) {
+      chunks.push(chunk);
+      total += chunk.byteLength;
+    }
+  }
+  const body = new Uint8Array(total);
+  let at = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, at);
+    at += chunk.byteLength;
+  }
+  return body;
+}

package/host.js

@@ -0,0 +1,56 @@
+// @flow
+//
+// `@uniflowed/server/host`: how a host establishes a request.
+//
+// The other half of this package. `@uniflowed/server` is what an application
+// calls *inside* a request; this is what a renderer, a route dispatcher or a
+// server-action bridge calls to say that a request has begun and, later, that
+// the response has gone.
+//
+// Two subpaths rather than one module, because they have opposite audiences and
+// opposite rules. Everything in the root is safe to call from a component and
+// meaningless outside a request; everything here is meaningless *inside* one
+// and must be called exactly once around it. Mixing them would put
+// `runWithContext` in the same import a page reaches for, which is an invitation
+// to nest one request inside another.
+//
+// It is a subpath rather than `internal/` because a sibling package cannot
+// reach another's internals: `@uniflowed/router` renders and dispatches inside
+// a request, and it is a different npm package.
+//
+// # `beginRequest` is the one a host calls
+//
+// The other exports are what it is made of, and they are public because the
+// suite drives them one at a time and because a host with an unusual shape may
+// need them. A host that reaches for them separately is nonetheless doing the
+// thing that produced ubugeeei-prod/uf#389: `@uniflowed/router` used to build a
+// context in its middleware runner and drain it there, and build a second one
+// in its dispatcher, so a request had up to two contexts and `after()` ran
+// before the response existed. One request is one `beginRequest`, and the pair
+// it returns is deliberately awkward to call from a single place — `run` wraps
+// deciding the response, `settle` follows writing it.
+//
+// # Which module's copy
+//
+// This one holds an `AsyncLocalStorage`, so the context is only shared by code
+// that resolved to the *same* copy of it. A host that serves a bundled
+// application must therefore take `beginRequest` from that bundle —
+// `virtual:uf/server` re-exports it for exactly this reason — and not from its
+// own `node_modules`, where it would be a second storage that sees nothing.
+
+export type {
+  CookieStore,
+  DraftMode,
+  HeaderStore,
+  RequestContext,
+  RequestLifecycle,
+} from "./internal/context.js";
+
+export {
+  beginRequest,
+  contextFor,
+  drainDeferred,
+  insideRequest,
+  parseCookies,
+  runWithContext,
+} from "./internal/context.js";

package/index.js

@@ -0,0 +1,133 @@
+// @flow
+//
+// `@uniflowed/server`: what a server function may ask about its request.
+//
+// Every binding here takes no arguments and answers about the request being
+// handled, which is only possible because the renderer establishes a context
+// around each one ([`./internal/context.js`]). Outside a request they throw,
+// and each says what it was that had nowhere to look — a component that calls
+// `cookies()` during a static prerender has made a mistake worth naming, not a
+// mistake worth returning `null` for.
+//
+// This module is server-only. Nothing in it is reachable from a client
+// component, `uf:rsc` classifies it that way, and importing it from one is the
+// error that classification exists to produce.
+
+import type { CookieStore, DraftMode, HeaderStore } from "./internal/context.js";
+import { currentContext } from "./internal/context.js";
+
+export type { CookieStore, DraftMode, HeaderStore } from "./internal/context.js";
+
+/**
+ * Raised when a server function is called with no request to answer about.
+ *
+ * Names the binding, because "no request context" on its own leaves a reader
+ * hunting for which of the six things they called was the one out of place.
+ */
+export class OutsideRequestError extends Error {
+  /** The binding that was called, e.g. `cookies`. */
+  binding: string;
+
+  constructor(binding: string) {
+    super(
+      `@uniflowed/server: ${binding}() was called outside a request. ` +
+        "It answers about the request being handled, and there is not one here — " +
+        "a static prerender, a module's top level, or a client component.",
+    );
+    this.name = "OutsideRequestError";
+    this.binding = binding;
+  }
+}
+
+/** The current request's context, or a named failure. */
+function require$Context(binding: string) {
+  const context = currentContext();
+  if (context == null) {
+    throw new OutsideRequestError(binding);
+  }
+  return context;
+}
+
+/**
+ * The current request's context, counting this as a read of request state.
+ *
+ * The three bindings below that answer about *this* request go through this
+ * one, and `after()` deliberately does not: registering deferred work says
+ * nothing about what the response contains. What the count is for is the route
+ * cache — `./fetch.js` reads it before the render and again after the last
+ * byte, and stores the document only if nothing in between asked who was
+ * asking. A page that read a cookie is a page about one person, and a page
+ * about one person must not be served to the next person from a cache.
+ *
+ * Counted at the call rather than at the value, which is conservative in the
+ * one direction that is safe: `const store = cookies()` followed by no `get`
+ * counts, so such a render is re-rendered rather than cached. Slower, never
+ * wrong — and the alternative, instrumenting the getters, would have to decide
+ * what `has()` on a name that is absent means, which is a question with no
+ * answer that is safe in both directions.
+ */
+function require$VaryingContext(binding: string) {
+  const context = require$Context(binding);
+  context.requestStateReads += 1;
+  return context;
+}
+
+/**
+ * The request's headers, read-only.
+ *
+ * Read-only because a response header set from inside a render has no defined
+ * moment to take effect: the headers may already be on the wire by the time a
+ * component deep in the tree renders.
+ */
+export function headers(): HeaderStore {
+  return require$VaryingContext("headers").headers;
+}
+
+/**
+ * The request's cookies, read-only.
+ *
+ * Setting a cookie belongs to a route handler or a server action, which run
+ * before a response exists and can say so in it.
+ */
+export function cookies(): CookieStore {
+  return require$VaryingContext("cookies").cookies;
+}
+
+/**
+ * Whether this request is rendering draft content.
+ *
+ * The flag lives on the request rather than in a module, so two requests being
+ * handled at once cannot see each other's answer.
+ */
+export function draftMode(): DraftMode {
+  const context = require$VaryingContext("draftMode");
+  return {
+    isEnabled: context.draft,
+    enable: () => {
+      context.draft = true;
+    },
+    disable: () => {
+      context.draft = false;
+    },
+  };
+}
+
+/**
+ * Run `callback` once the response has been sent.
+ *
+ * For the work a request causes but a response does not wait on: recording a
+ * view, flushing a metric, warming a cache. Registered work runs in the order
+ * it was registered, and one task failing does not stop the others — deferred
+ * work is by definition not what the response depended on.
+ *
+ * "Sent" is the host's word to keep, and it keeps it: the request is drained
+ * after `uf dev` has written the document, after `uf preview` and `uf start`
+ * have returned from `send`, and after a compiled binary's `pipe` has resolved
+ * on the last byte. One list per request, whether the callback was registered
+ * by a middleware, a route handler or a page. It was not always so — see
+ * ubugeeei-prod/uf#389 for what it meant before, and
+ * `@uniflowed/server/host`'s `beginRequest` for the half a host supplies.
+ */
+export function after(callback: () => mixed | Promise<mixed>): void {
+  require$Context("after").deferred.push(callback);
+}

package/internal/application.js

@@ -0,0 +1,90 @@
+// @flow
+//
+// Internal to `@uniflowed/server`: what a built uf application is, as a type.
+//
+// Three shapes, and every front door onto a build needs all three — the asset
+// URLs a rendered document references, what one render answers with, and the
+// module `uf build` writes to `.uf/build/server/server.js`.
+//
+// They are here rather than in whichever module happened to be written first
+// because there are now three readers of them: [`../fetch.js`] for a host that
+// speaks `Request` and `Response`, [`../standalone.js`] for a compiled binary,
+// and `@uniflowed/vite`'s preview and start servers through the first of
+// those. A type re-declared once per reader is how two of them come to
+// disagree about what `render` returns, which is a disagreement no test sees
+// until a deployment answers differently from the preview it was checked with.
+
+import type { RequestLifecycle } from "./context.js";
+
+export type { RequestLifecycle } from "./context.js";
+
+/**
+ * Where a document is written, when the host has a Node stream.
+ *
+ * The two methods React's own `pipe` uses and nothing else, declared
+ * structurally so this module holds no Node types: `../fetch.js` is bundled
+ * for hosts that have no `node:stream` to import one from.
+ */
+export type WritableLike = {
+  readonly write: (chunk: string | Uint8Array) => mixed,
+  readonly end: () => mixed,
+  ...
+};
+
+/** The script, stylesheet and preload URLs a rendered document references. */
+export type DocumentAssets = {|
+  readonly scripts: $ReadOnlyArray<string>,
+  readonly styles: $ReadOnlyArray<string>,
+  readonly preloads: $ReadOnlyArray<string>,
+|};
+
+/**
+ * A document that has begun.
+ *
+ * `status` and `headers` are known once the shell is ready, which is why a
+ * streaming renderer can still answer with a status line. The body arrives
+ * afterwards through exactly one of `pipe` and `stream` — each is a single
+ * pass over the same chunks, so calling both would read a document twice.
+ */
+export type RenderedDocument = {|
+  readonly status: number,
+  readonly headers?: { readonly [string]: string },
+  readonly pipe: (destination: WritableLike) => mixed,
+  readonly stream: () => ReadableStream<Uint8Array>,
+|};
+
+/** What the project's server bundle exports; see `virtual:uf/server`. */
+export type Application = {|
+  /** Render `url`, resolving when the shell is ready. */
+  readonly render: (
+    url: string,
+    assets: DocumentAssets,
+    options?: {| readonly onError?: (error: mixed) => void |},
+  ) => Promise<RenderedDocument>,
+  /** The route handler for this request, or `null` when no handler claims it. */
+  readonly dispatch: (request: Request) => Promise<Response | null>,
+  /**
+   * The guard on the path, run before anything under it answers.
+   *
+   * Called rather than tested for: a server bundle without it is a `TypeError`
+   * on the first request, not an application whose auth check quietly stopped
+   * running once it was built. See ubugeeei-prod/uf#260.
+   */
+  readonly runMiddleware: (request: Request) => Promise<Response | null>,
+  /**
+   * Begin the request everything above runs inside.
+   *
+   * A host calls this, runs the whole of answering the request inside `run`,
+   * and calls `settle` once the response has been written — which is what
+   * `after()` means by "sent" and is a different line in every host.
+   *
+   * It is on the bundle rather than importable beside this type, and that is
+   * the one thing about it that looks wrong and is not: the request lives in an
+   * `AsyncLocalStorage` belonging to a module *instance*, and the instance the
+   * application reads is the one bundled into its own `server.js`. A host that
+   * began a request in any other copy would fail silently — the guard would
+   * run, the page would render, and every `cookies()` in it would throw as
+   * though no host had run at all. See ubugeeei-prod/uf#389.
+   */
+  readonly beginRequest: (request: Request) => RequestLifecycle,
+|};

package/internal/cache-key.js

@@ -0,0 +1,79 @@
+// @flow
+//
+// Internal to `@uniflowed/server`: what makes two lookups the same lookup.
+//
+// A cache key here is a list of **strings**, reduced to one string that is the
+// entry's identity. That is narrower than the two keys this repository already
+// has, and the narrowing is the whole design decision, so it is argued rather
+// than asserted.
+//
+// # Where it departs from `@uniflowed/query/key`, and why
+//
+// `hashKey` there takes `$ReadOnlyArray<mixed>` and serialises it with object
+// members sorted, because a *client* key is written inline in two components
+// by two people and `["users", {page: 1, size: 20}]` has to be the same entry
+// as `["users", {size: 20, page: 1}]`. Its own header then spends a paragraph
+// on what that admits: a `Date` or a class instance serialises through
+// whatever `toJSON` it happens to have, `1` and `"1"` are deliberately
+// different entries, and both are traps you are told to avoid rather than
+// prevented from writing.
+//
+// A server cache key is not written that way. It is built by uf — a method, a
+// pathname and a query string — or by a caller naming a URL it is about to
+// fetch. Every one of those is already a string, so admitting `mixed` would
+// buy nothing and would import the whole `toJSON` question into a cache whose
+// wrong answers are *other people's data*. Strings only, and a key that is not
+// a list of strings is a `TypeError` at the call rather than an entry filed
+// under a name nobody can predict.
+//
+// Prefix matching does not come across either, and for a reason rather than an
+// omission: invalidation here is by **tag**, not by key shape. A caller that
+// wants "everything about users" gone says `cacheTag("users")` when the entry
+// is filled and `revalidateTag("users")` when it changes, which is a statement
+// about meaning; `matchesKey`'s structural prefix is a statement about
+// spelling, and the two only agree while one person is writing both ends.
+//
+// # Where it departs from the two disk caches, and why
+//
+// `crates/uf_check`'s cache and `@uniflowed/host`'s transform cache both put
+// **the identity of the `uf` that produced the entry** in the key, and both
+// headers say the same thing about it: a content-addressed cache has no
+// invalidation to get wrong only if every other input is a constant, and the
+// largest one is the compiler. Neither of them can leave it out, because both
+// outlive the process that wrote them — the entry on disk is read by the next
+// build, which may be a different build.
+//
+// This one cannot outlive the process, so the identity of the code that
+// produced an entry is fixed for the whole life of the store and there is
+// nothing to put in the key. That is not a shortcut around their lesson; it is
+// the same lesson pointing the other way, and it is the reason the store is in
+// memory and stays there until something durable exists to hold it. The day an
+// adapter offers a store that survives a restart, this key gains a generation
+// — the build id — before that store is written to, because on that day the
+// entry outlives the build and every word of those two headers applies.
+
+/** A cache key, as a caller writes it: `["route", "GET", "/posts"]`. */
+export type CacheKey = $ReadOnlyArray<string>;
+
+/**
+ * A key as one string, exactly and totally.
+ *
+ * `JSON.stringify` over an array of strings is unambiguous — the quoting and
+ * escaping are what separate the members — so two different keys cannot
+ * collide and one key cannot spell itself two ways. Joining with a separator
+ * would do neither: a path containing the separator is a second key wearing
+ * the first one's name, and on a route cache that is one URL served the
+ * document of another.
+ */
+export function hashCacheKey(key: CacheKey): string {
+  for (let index = 0; index < key.length; index += 1) {
+    if (typeof key[index] !== "string") {
+      throw new TypeError(
+        `@uniflowed/server: a cache key is a list of strings, and member ${index} is ` +
+          `${typeof key[index]}. Spell it out — String(id) — rather than leaving the ` +
+          "entry's name to whatever serialisation the value happens to have.",
+      );
+    }
+  }
+  return JSON.stringify(key);
+}