@uniflowed/vite 0.0.0-alpha.9 → 0.1.0

package/internal/serve.js

@@ -32,7 +32,7 @@
 // module is the part that is genuinely Vite's: finding the build on disk and
 // reading the manifest a Vite build wrote.
 //
-// It moved because of `uf build --adapter`. `tests/library/serve.test.js` said
+// It moved because of `uf build --adapter`. `packages/server/serve.test.js` said
 // what was wrong with the old arrangement while it was still the only one:
 // "`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
@@ -64,17 +64,20 @@
 // settles it on the line after the last byte.
 //
 // It has to be the *entry's* `beginRequest` rather than one imported here: the
-// request lives in an `AsyncLocalStorage` belonging to one copy of
-// `@uniflowed/server`, and the copy that matters is the one inside the
-// application bundle. A host that resolved its own would begin a request the
-// application cannot see, and nothing would fail loudly — 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.
+// request store is shared by every copy of one release of `@uniflowed/server`,
+// and the release that matters is the one inside the application bundle. A
+// host that resolved its own could be holding another release, would begin a
+// request the application cannot see, and nothing would fail loudly — 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.
 
+import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
+import { localImageEndpoint, servesRemoteImages } from "./image-endpoint.js";
+
 /**
  * `@uniflowed/server`'s two halves, loaded once.
  *
@@ -86,10 +89,133 @@ function deployment() {
   deploymentModules ??= Promise.all([
     import("@uniflowed/server/fetch"),
     import("@uniflowed/server/node"),
-  ]).then(([application, host]) => ({ ...application, ...host }));
+    import("@uniflowed/server/cache"),
+  ]).then(([application, host, cache]) => ({ ...application, ...host, ...cache }));
   return deploymentModules;
 }
 
+/**
+ * The cache `rendering.cache` describes, or `undefined` for no cache at all.
+ *
+ * `undefined` rather than a store with both switches off, and the difference is
+ * visible from an application: a handler with no `cache` installs nothing on
+ * the request, so `revalidateTag()` raises "there is not one here" instead of
+ * reporting that it expired nothing. A project that turned the cache off should
+ * be told that it did, not handed a cache that quietly does nothing.
+ *
+ * One store per server process, built when the handler is. With no
+ * `rendering.cache.store` that is the whole of what "in memory, per process"
+ * means in practice: `uf preview` and `uf start` each hold one, and two of them
+ * running at once share nothing. With one, the two processes share whatever the
+ * provider is in front of — see [`providerFor`].
+ *
+ * The store's remaining options are still not configurable from `uf.config.js`
+ * and are still not named here: `maxEntries` and `now` are facts about one
+ * process's heap and one process's clock, and a parameter threaded through for
+ * a setting nobody can set would be the shape of configurability with none of
+ * the substance.
+ *
+ * @param {{route?: boolean, fetch?: boolean, data?: boolean, store?: string, storeDir?: string} | undefined} declared
+ * @param {(options?: object) => object} createCacheStore
+ * @param {{root: string, build: string | null}} where
+ */
+async function cacheFor(declared, createCacheStore, where) {
+  const route = declared?.route === true;
+  const fetchCache = declared?.fetch === true;
+  const data = declared?.data === true;
+  if (!route && !fetchCache && !data) return undefined;
+  const provider = await providerFor(declared, where);
+  const store =
+    provider == null ? createCacheStore() : createCacheStore({ provider, build: where.build });
+  return { store, route, fetch: fetchCache, data };
+}
+
+/**
+ * Where `/__uf/image` keeps its variants: over the provider
+ * `rendering.cache.store` names, or `undefined` for the endpoint's own memory.
+ *
+ * The same provider as the route cache, because it is the one a project
+ * already said survives a restart and is shared between processes — a second
+ * setting for "where do image variants go" would be a second answer to a
+ * question the project answered once. Asked only when a store is named, so a
+ * project that names none needs no build identity for its images.
+ *
+ * @param {{store?: string, storeDir?: string} | undefined} declared
+ * @param {(options?: object) => object} createCacheStore
+ * @param {{root: string, build: string | null}} where
+ */
+async function imageStoreFor(declared, createCacheStore, where) {
+  const named = declared?.store ?? "memory";
+  if (named === "memory") return undefined;
+  const provider = await providerFor(declared, where);
+  if (provider == null) return undefined;
+  const { MAX_MEMORY_VARIANTS } = await import("@uniflowed/server/image");
+  return createCacheStore({ provider, build: where.build, maxEntries: MAX_MEMORY_VARIANTS });
+}
+
+/**
+ * The durable provider `rendering.cache.store` names, or `null` for memory.
+ *
+ * Three answers, and the third is the one that matters to
+ * `docs/red-lines.md`'s third line. `"memory"` — the default, and what every
+ * project that says nothing gets — keeps the store exactly as it was.
+ * `"filesystem"` is uf's built-in, and it is a convenience rather than an
+ * architecture. Anything else is a **module specifier**, resolved from the
+ * project, exporting `createCacheProvider`: the same shape `builder.module`
+ * has, chosen for the same reason that document gives — "a provider a project
+ * can replace has to be a name it can write, and an enum with one variant
+ * cannot become one without a release of uf".
+ *
+ * So a project with a Redis, a KV namespace or an S3 bucket writes twenty lines
+ * against `@uniflowed/server/cache`'s `CacheProvider` type, names the module
+ * here, and uf never learns which of those it was.
+ *
+ * # Why a missing build identity is a refusal
+ *
+ * Because the alternatives are both worse. Falling back to memory would give a
+ * project that asked for a cache surviving restarts one that does not, and the
+ * symptom is a `MISS` on every cold request — indistinguishable from a cache
+ * that is simply cold. Generating an identity per process would be worse again:
+ * four servers would write four copies of everything into one directory and
+ * read none of each other's. The deployment rules say a target that cannot
+ * provide a durable store has to say so, and this is a host saying so.
+ *
+ * @param {{store?: string, storeDir?: string} | undefined} declared
+ * @param {{root: string, build: string | null}} where
+ */
+async function providerFor(declared, { root, build, regenerates }) {
+  // A build that regenerates pages keeps what it regenerated on disk unless the
+  // project named a store. A restart that took every regenerated page back to
+  // the build's copy would be a server whose pages went back in time, which is
+  // the one thing regeneration is for not doing. `"memory"`, said out loud, is
+  // still memory.
+  const named = declared?.store ?? (regenerates === true ? "filesystem" : "memory");
+  if (named === "memory") return null;
+  if (build == null) {
+    throw new Error(
+      `uf: rendering.cache.store is ${JSON.stringify(named)}, which keeps entries between ` +
+        "restarts, and there is no build identity to key them by. `uf build` writes one " +
+        "beside the server bundle; set UF_BUILD_ID to name it yourself. Without one, a " +
+        "deploy would answer the new build's URLs with the previous build's documents.",
+    );
+  }
+  const directory = path.resolve(root, declared?.storeDir ?? path.join(".uf", "cache", "route"));
+  if (named === "filesystem") {
+    const { createFilesystemCache } = await import("@uniflowed/server/cache/filesystem");
+    return createFilesystemCache({ directory });
+  }
+  const provider = await import(providerSpecifier(root, named));
+  const create = provider.createCacheProvider ?? provider.default;
+  if (typeof create !== "function") {
+    throw new Error(
+      `uf: rendering.cache.store names ${JSON.stringify(named)}, which exports no ` +
+        "`createCacheProvider`. A durable cache provider is a module exporting that " +
+        "function; see @uniflowed/server/cache's CacheProvider type for what it returns.",
+    );
+  }
+  return create({ build, directory });
+}
+
 /**
  * Everything a served build consists of.
  *
@@ -118,7 +244,184 @@ export async function loadBuild({ root, outDir, serverDir }) {
   const manifest = JSON.parse(await readFile(manifestFile, "utf8"));
   const entry = await import(pathToFileURL(entryFile).href);
   await deployment();
-  return { entry, assets: assetsFromManifest(manifest), distDir };
+  const build = await buildIdentity(root, serverDir);
+  const regeneration = await readRegeneration(path.resolve(root, serverDir));
+  const partial = await readPartialPrerenders(path.resolve(root, serverDir));
+  return {
+    entry,
+    assets: await documentAssetsFor(path.resolve(root, serverDir), manifest),
+    distDir,
+    root,
+    build,
+    regeneration,
+    partial,
+  };
+}
+
+/** What `uf build` records a document's tags in, beside the server bundle. */
+export const DOCUMENT_ASSETS_FILE = "uf-document-assets.json";
+
+/**
+ * The tags a served document needs: the ones `uf build` recorded, or — for a
+ * build from before it recorded them — the client manifest's.
+ *
+ * Recorded rather than recomputed, because the client manifest is no longer the
+ * whole answer. An application React Server Components render links the
+ * stylesheets its rsc graph emitted and the ones each client module's chunk
+ * carries, and neither is reachable from the client entry the manifest is walked
+ * from — so a server that recomputed the tags rendered every page without the
+ * stylesheets its prerendered pages had. `uf start`, `uf preview`, `--adapter`
+ * and `--compile` all read them from here.
+ *
+ * @param {string} serverDir absolute path of the server bundle's directory
+ * @param {object} manifest the client build's Vite manifest
+ */
+export async function documentAssetsFor(serverDir, manifest) {
+  const file = path.join(serverDir, DOCUMENT_ASSETS_FILE);
+  let recorded;
+  try {
+    recorded = await readFile(file, "utf8");
+  } catch {
+    return assetsFromManifest(manifest);
+  }
+  try {
+    return JSON.parse(recorded);
+  } catch {
+    throw new Error(`uf: ${file} is not the JSON \`uf build\` writes; run \`uf build\` again`);
+  }
+}
+
+/**
+ * The file beside the server bundle that names the pages a build regenerates.
+ *
+ * Written by `driver.js`'s build, and only for a build that has such a page.
+ */
+export const REGENERATION_FILE = "regenerate.json";
+
+/**
+ * Where a regenerated page's document goes, under the build's output directory.
+ *
+ * Somewhere no static half answers the page's own URL, which is the point: a
+ * file at `dist/posts/a/index.html` would be served by every host before the
+ * server saw the request, forever, whatever the page's lifetime said.
+ */
+export const REGENERATED_DIRECTORY = "__uf/regenerate";
+
+/**
+ * The pages this build regenerates, or `undefined` for a build that has none.
+ *
+ * `undefined` rather than an empty manifest, so a build with nothing to
+ * regenerate serves exactly as every build did before regeneration existed.
+ */
+export async function readRegeneration(serverDir) {
+  let text;
+  try {
+    text = await readFile(path.join(serverDir, REGENERATION_FILE), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * The file beside the server bundle that holds the static shells of the pages a
+ * build prerendered partially.
+ *
+ * Beside the server bundle rather than under the output directory, because a
+ * shell is not a document anybody should be sent on its own: its holes are
+ * filled by the server that reads this file, and a file server would send it
+ * with every hole showing its fallback forever.
+ */
+export const PARTIAL_PRERENDER_FILE = "partial-prerender.json";
+
+/**
+ * The pages this build prerendered partially, or `undefined` for a build with
+ * none — which then serves exactly as every build did before partial
+ * prerendering existed.
+ */
+export async function readPartialPrerenders(serverDir) {
+  let text;
+  try {
+    text = await readFile(path.join(serverDir, PARTIAL_PRERENDER_FILE), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * What `import()` should be given for a provider a project named.
+ *
+ * A relative path in `uf.config.js` is relative to *the project*, which is what
+ * anybody writing `"./cache/redis.js"` means and is not what `import()` from
+ * this module would do — it would look beside `@uniflowed/vite`, find nothing,
+ * and report a missing module the config file does not mention. `builder.module`
+ * settled the same question the same way in `uf_cli`'s `project_directory`.
+ *
+ * A bare specifier is left alone: `"@acme/uf-cache-redis"` is a package, and
+ * resolving it is Node's job and not this function's.
+ *
+ * @param {string} root
+ * @param {string} named
+ */
+export function providerSpecifier(root, named) {
+  if (!named.startsWith(".") && !path.isAbsolute(named)) return named;
+  return pathToFileURL(path.resolve(root, named)).href;
+}
+
+/** What `uf build` writes its identity into, beside the server bundle. */
+export const BUILD_ID_FILE = "uf-build-id";
+
+/**
+ * The identity of the build being served, or `null`.
+ *
+ * Only a durable cache reads it, and only a durable cache needs it: an entry
+ * that cannot outlive the process cannot outlive the build either, so every
+ * command that keeps its cache in memory is entitled to `null` here and never
+ * looks. `packages/server/internal/cache-key.js` argues the rest.
+ *
+ * `UF_BUILD_ID` first, then the file `uf build` wrote. The environment wins for
+ * the reason it wins in `crates/uf_rsc`'s `BuildId::from_env_or_generate`,
+ * which reads the same variable for the same kind of fact: a deployment that
+ * needs two artefacts to *be* one build — a blue/green pair, a rebuild of a
+ * tagged commit — has no other way to say so.
+ *
+ * `null` rather than a generated fallback, and that is the whole point of the
+ * function. A per-process identity would give four servers four caches with a
+ * shared disk between them, which is worse than four memories: it would write
+ * four copies of everything and read none of them. Whoever asked for a durable
+ * store is told there is no build to key it by, and gets to fix it.
+ */
+export async function buildIdentity(root, serverDir) {
+  const named = process.env.UF_BUILD_ID;
+  if (typeof named === "string" && named !== "") return named;
+  try {
+    const file = path.join(path.resolve(root, serverDir), BUILD_ID_FILE);
+    const value = (await readFile(file, "utf8")).trim();
+    return value === "" ? null : value;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The id a build's documents publish, derived from the build id.
+ *
+ * A browser names it on every action call and payload request, and a front
+ * door on another build refuses rather than answering; see
+ * `@uniflowed/server`'s `internal/deployment.js`. It has to be public — it is
+ * in every document — and the build id must not be: it is the key the action
+ * ids are an HMAC under whenever `UF_BUILD_ID` names both. So this is a
+ * digest of it, under a label of its own, and sixteen hex characters of that:
+ * the same for two artefacts that are one build, different for any two that
+ * are not, and no help to anybody guessing the key.
+ *
+ * @param {string} buildId
+ */
+export function deploymentIdFor(buildId) {
+  return createHash("sha256").update("uf:deployment\0").update(buildId).digest("hex").slice(0, 16);
 }
 
 async function readable(file, message) {
@@ -153,8 +456,15 @@ async function readable(file, message) {
  * the rest moved to `@uniflowed/server`. `uf build --adapter` calls it too,
  * at build time, and bakes the answer into what it emits.
  */
-export function assetsFromManifest(manifest) {
-  const entry = Object.values(manifest).find((chunk) => chunk.isEntry);
+export function assetsFromManifest(manifest, base = "") {
+  // `client` by name first. An application React Server Components render
+  // gives the client build one entry per client module as well, and the
+  // document's script is the application's entry, not whichever of those the
+  // manifest happens to list first.
+  const chunks = Object.values(manifest);
+  const entry =
+    chunks.find((chunk) => chunk.isEntry && chunk.name === "client") ??
+    chunks.find((chunk) => chunk.isEntry);
   if (entry == null) throw new Error("uf: the client manifest has no entry chunk");
 
   const styles = new Set(entry.css ?? []);
@@ -182,10 +492,12 @@ export function assetsFromManifest(manifest) {
   };
   collectPreloads(entry);
 
+  // Under `app.router.basePath` when there is one: a prerendered document is
+  // written outside Vite's HTML transform, so nothing else would put it there.
   return {
-    scripts: [`/${entry.file}`],
-    styles: [...styles].map((file) => `/${file}`),
-    preloads: [...preloads].map((file) => `/${file}`),
+    scripts: [`${base}/${entry.file}`],
+    styles: [...styles].map((file) => `${base}/${file}`),
+    preloads: [...preloads].map((file) => `${base}/${file}`),
   };
 }
 
@@ -198,10 +510,10 @@ export function assetsFromManifest(manifest) {
  * its callback whether the render threw or not, and `drainDeferred` already
  * reports a failing task rather than propagating it.
  *
- * `entry.beginRequest` and not an import: the request lives in an
- * `AsyncLocalStorage` belonging to one copy of `@uniflowed/server`, and the
- * copy that matters is the one inside the application bundle. See
- * `serverModuleSource` in `./routes.js`.
+ * `entry.beginRequest` and not an import: the request store is shared by every
+ * copy of one release of `@uniflowed/server`, and the release that matters is
+ * the one inside the application bundle. See `serverModuleSource` in
+ * `./routes.js`.
  *
  * The one case this cannot be exact about is a request uf hands back rather
  * than answers: a caller whose `catch` is `next(error)` gives the response to
@@ -211,12 +523,12 @@ export function assetsFromManifest(manifest) {
  * naming rather than papering over, and it is the failure path of a request
  * that already went wrong — not the ordinary one this exists for.
  *
- * @param {{beginRequest: (request: Request) => {run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
+ * @param {{beginRequest: (request: Request) => {context: object, run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
  * @param {Request} request
  * @param {() => Promise<mixed>} body
  */
 export async function withRequest(entry, request, body) {
-  const { run, settle } = entry.beginRequest(request);
+  const { run, settle } = await beginRequest(entry, request);
   try {
     return await run(body);
   } finally {
@@ -224,6 +536,44 @@ export async function withRequest(entry, request, body) {
   }
 }
 
+/**
+ * Begin a request on this host, with what this host can do already on it.
+ *
+ * The half of [`withRequest`] that a caller which may *not* answer needs.
+ * `uf dev` runs the application's middleware, its action endpoint and its
+ * dispatcher for every request, and hands the ones none of them claimed back
+ * to Vite's chain — at which point the response is written somewhere this
+ * module cannot see, so settling has to wait for the socket rather than for a
+ * `finally` here. A caller that always answers should use [`withRequest`] and
+ * not think about it.
+ *
+ * `entry.beginRequest` and not an import: the request store is shared by every
+ * copy of one release of `@uniflowed/server`, and the release that matters is
+ * the one inside the application bundle. See `serverModuleSource` in
+ * `./routes.js`.
+ *
+ * What this host can do is put on the request the way `createFetchHandler`
+ * puts it on the one it owns. `uf dev` and `uf build --compile` reach a route
+ * handler without going through that function, and a handler that streams
+ * events or queues work has to get the same answer from all four front doors —
+ * a capability that is present under `uf start` and absent under `uf dev` is
+ * the difference this whole seam exists to remove.
+ *
+ * `nodeCapabilities`, because both of those *are* a Node process with a
+ * socket: a body reaches the client as it is written, and the process is still
+ * there afterwards. Neither passes an upgrader or a queue, because uf defines
+ * both and implements neither.
+ *
+ * @param {{beginRequest: (request: Request) => {context: object, run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
+ * @param {Request} request
+ */
+export async function beginRequest(entry, request) {
+  const lifecycle = entry.beginRequest(request);
+  const { nodeCapabilities } = await deployment();
+  lifecycle.context.capabilities ??= nodeCapabilities();
+  return lifecycle;
+}
+
 /**
  * The application half: route handlers, then rendering.
  *
@@ -238,11 +588,67 @@ export async function withRequest(entry, request, body) {
  * forgets is not left to discover it: `entry.runMiddleware` refuses outside a
  * request and names what establishes one. See "Who owns the request" above.
  *
- * @param {{entry: object, assets: object}} build
+ * `cache` is `rendering.cache` from `uf.config.js`, straight through: this is
+ * the point where four switches that used to reach a JSON file and nothing else
+ * become a store a request can hit. See ubugeeei-prod/uf#277.
+ *
+ * `root` and `build` come with it, and only the cache reads either: `root` is
+ * where a `storeDir` is resolved from and `build` is what a durable entry is
+ * keyed by. Both are `undefined` for a caller that constructs a handler by
+ * hand, which is the memory-only store and needs neither.
+ *
+ * `images` is `app.builtins.images`, and it adds `/__uf/image` to what the
+ * handler answers when it lists remote hosts; see `./image-endpoint.js`.
+ *
+ * @param {{entry: object, assets: object, cache?: object, root?: string, build?: string | null, regeneration?: object, images?: object, partial?: object}} build
  */
-export function createApplicationHandler({ entry, assets }) {
-  const ready = deployment().then(({ createFetchHandler }) =>
-    createFetchHandler({ app: entry, document: assets }),
+export function createApplicationHandler({
+  entry,
+  assets,
+  cache,
+  root,
+  build,
+  regeneration,
+  images,
+  partial,
+}) {
+  const ready = deployment().then(
+    async ({ createFetchHandler, createCacheStore, nodeCapabilities }) =>
+      createFetchHandler({
+        app: entry,
+        document: assets,
+        cache: await cacheFor(cache, createCacheStore, {
+          root: root ?? process.cwd(),
+          build: build ?? null,
+          regenerates: regeneration != null,
+        }),
+        // `/__uf/image`, for a project that listed remote hosts. See
+        // `./image-endpoint.js`.
+        ...(servesRemoteImages(images)
+          ? {
+              images: await localImageEndpoint({
+                images,
+                root: root ?? process.cwd(),
+                store: await imageStoreFor(cache, createCacheStore, {
+                  root: root ?? process.cwd(),
+                  build: build ?? null,
+                }),
+              }),
+            }
+          : {}),
+        // The pages this build regenerates, from the manifest beside the server
+        // bundle. Absent for a build with none, which then serves exactly as it
+        // did before regeneration existed.
+        ...(regeneration == null ? {} : { regeneration }),
+        // And the static shells of the pages it prerendered partially, from the
+        // file beside the server bundle, for the same reason.
+        ...(partial == null ? {} : { partial }),
+        // `uf preview` and `uf start` are a Node process with a socket, which is
+        // what a deployed `--adapter node` build is too — so a route handler
+        // that streams events answers the same way in the preview it is checked
+        // in and in the deployment it ends up as. See `withRequest` above.
+        capabilities: nodeCapabilities(),
+      }),
   );
   return async function handle(request) {
     return (await ready)(request);
@@ -272,13 +678,161 @@ export function createStaticHandler({ root }) {
  * project whose handler path collides with a file in `public/` behaves one way
  * when it is checked and the other way when it is deployed.
  *
- * @param {{entry: object, assets: object, distDir: string}} build
+ * It is `@uniflowed/server/node`'s own `createServeHandler`, the one a deployed
+ * `server.js` runs, rather than the two halves composed a second time here.
+ * That one also hands the application the build's files when the static half
+ * has nothing, which is how a regenerated page starts from the document the
+ * build wrote; a composition of its own here would be a `uf start` whose
+ * regenerated pages rendered on their first request while a deployment's did
+ * not.
+ *
+ * It is handed the bundle's `routing` too, so `app.router`'s redirects answer
+ * before the files and its headers go on whatever answers, here exactly as in
+ * a deployment. `uf preview` puts the same two in front of Vite's file
+ * middleware as well; see [`answerRouting`].
+ *
+ * @param {{entry: object, assets: object, distDir: string, cache?: object, root?: string, build?: string | null, regeneration?: object, partial?: object}} build
  */
-export function createServeHandler({ entry, assets, distDir }) {
-  const serveStatic = createStaticHandler({ root: distDir });
-  const application = createApplicationHandler({ entry, assets });
+export function createServeHandler({
+  entry,
+  assets,
+  distDir,
+  cache,
+  root,
+  build,
+  regeneration,
+  images,
+  partial,
+}) {
+  const application = createApplicationHandler({
+    entry,
+    assets,
+    cache,
+    root,
+    build,
+    regeneration,
+    images,
+    partial,
+  });
+  const ready = deployment().then(({ createServeHandler: create }) =>
+    create({ staticDir: distDir, handle: application, routing: entry.routing }),
+  );
   return async function handle(request) {
-    return (await serveStatic(request)) ?? (await application(request));
+    return (await ready)(request);
+  };
+}
+
+/**
+ * Whether `routing` has anything to say in front of a file server.
+ *
+ * Redirects and headers are the two that do; a rewrite is the application's.
+ * Asked before a middleware is mounted at all, so a project with no rules pays
+ * nothing per request under `uf dev` or `uf preview`.
+ *
+ * @param {{redirects?: unknown[], headers?: unknown[]} | undefined} routing
+ */
+export function answersInFrontOfFiles(routing) {
+  return (
+    (routing?.redirects?.length ?? 0) > 0 ||
+    (routing?.headers?.length ?? 0) > 0 ||
+    (routing?.basePath ?? "") !== "" ||
+    (routing?.trailingSlash ?? "ignore") !== "ignore"
+  );
+}
+
+/**
+ * `app.router`'s headers and redirects, for a door whose files Vite serves.
+ *
+ * `uf dev` and `uf preview` mount this in front of Vite's own middleware:
+ * the headers are pinned on the Node response, so they survive the
+ * `writeHead` Vite's file server writes its own with, and a redirect is
+ * answered before any file is looked for. `true` when it answered.
+ *
+ * @param {object} routing the bundle's `routing`
+ * @param {Request} request the address alone; see `toAddressRequest`
+ * @param {import("node:http").ServerResponse} response
+ */
+export async function answerRouting(routing, request, response) {
+  const { admit, headersFor, pinHeaders, send: write } = await deployment();
+  pinHeaders(response, headersFor(routing, request));
+  // A request outside the base path, the other spelling of a path, or a
+  // redirect rule: answered here, before Vite's own base middleware would
+  // answer the first in its words rather than uf's.
+  const admitted = admit(routing, request);
+  if (admitted.kind !== "answer") return false;
+  await write(response, admitted.response);
+  return true;
+}
+
+/**
+ * A request [`answerRouting`] let through, spelled so Vite's own middleware
+ * recognises it.
+ *
+ * Vite serves under its `base` with the trailing slash, `/docs/`, and its base
+ * middleware answers every other path with a 404 of its own, the bare `/docs`
+ * included. But `/docs` is the application's root under `app.router.basePath`,
+ * and the only spelling of it unless the trailing-slash policy is `"always"`,
+ * which has already answered `/docs` with a `308` by the time this is asked.
+ * So a request for exactly the base goes on to Vite as `/docs/`, which Vite
+ * takes the base off and hands on as the root. The application is handed the
+ * root either way.
+ *
+ * @param {{basePath?: string} | undefined} routing the bundle's `routing`
+ * @param {import("node:http").IncomingMessage} request
+ */
+export function forViteBase(routing, request) {
+  const base = routing?.basePath ?? "";
+  const url = request.url ?? "/";
+  if (base === "") return;
+  const queryAt = url.indexOf("?");
+  const pathname = queryAt === -1 ? url : url.slice(0, queryAt);
+  if (pathname === base) {
+    request.url = `${base}/${queryAt === -1 ? "" : url.slice(queryAt)}`;
+  }
+}
+
+/**
+ * `app.router.rewrites` for this request, for `uf dev`: the rewritten request,
+ * or `null`.
+ *
+ * `@uniflowed/server`'s `rewriteFor`, which `createFetchHandler` asks for every
+ * other front door at the same point — after the files, before the guard.
+ *
+ * @param {object | undefined} routing the bundle's `routing`
+ * @param {Request} request
+ */
+export async function rewriteRouting(routing, request) {
+  const { rewriteFor } = await deployment();
+  return rewriteFor(routing, request);
+}
+
+/**
+ * Whether a file server may answer this request, or uf has to go first.
+ *
+ * `@uniflowed/server`'s `prerenderedMayAnswer`, reached the same way
+ * `createStaticHandler` is. It exists out here because of the one request
+ * `uf preview` may not leave to Vite: `createServeHandler` above is mounted
+ * *behind* Vite's static middleware, which is fine for everything except a
+ * request carrying the draft cookie. `createStaticHandler` declines a
+ * prerendered document for such a request and, under `uf preview`, never sees
+ * it — so draft mode appeared to be off there while it worked under `uf dev`
+ * and `uf start`. That is ubugeeei-prod/uf#620.
+ *
+ * `driver.js` asks this in a middleware mounted in *front* of Vite's, and
+ * mounts `createServeHandler` behind it for the answer, so a draft request
+ * goes through the same handler `uf start` uses and gets the same answer —
+ * including its stylesheets and chunks, which that handler still serves off
+ * disk. Every other request is untouched and Vite's file middleware runs as
+ * before.
+ *
+ * A gate rather than a second handler, because the caller has a request
+ * lifecycle to open and must not open one for a request it is about to hand
+ * on.
+ */
+export function createPrerenderGate() {
+  const ready = deployment().then(({ prerenderedMayAnswer }) => prerenderedMayAnswer);
+  return async function prerenderedMayAnswer(cookieHeader) {
+    return (await ready)(cookieHeader ?? null);
   };
 }