@uniflowed/server 0.0.0-alpha.7 → 0.0.0-alpha.8

package/fetch.js

@@ -0,0 +1,135 @@
+// @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.
+//
+// # 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 type { Application, DocumentAssets } from "./internal/application.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 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.
+ */
+export function createFetchHandler(
+  options: FetchHandlerOptions,
+): (request: Request) => Promise<Response> {
+  const { app, document } = options;
+
+  return async function handle(request: Request): Promise<Response> {
+    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 result = await app.render(url.pathname + url.search, document, {
+      // 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.
+      onError: (error: mixed) => {
+        console.error(error);
+      },
+    });
+    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 });
+  };
+}

package/host.js

@@ -15,9 +15,42 @@
 // to nest one request inside another.
 //
 // It is a subpath rather than `internal/` because a sibling package cannot
-// reach another's internals: `@uniflowed/router` is where a request begins, and
-// it is a different npm package.
+// 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 } from "./internal/context.js";
+export type {
+  CookieStore,
+  DraftMode,
+  HeaderStore,
+  RequestContext,
+  RequestLifecycle,
+} from "./internal/context.js";
 
-export { contextFor, drainDeferred, parseCookies, runWithContext } from "./internal/context.js";
+export {
+  beginRequest,
+  contextFor,
+  drainDeferred,
+  insideRequest,
+  parseCookies,
+  runWithContext,
+} from "./internal/context.js";

package/index.js

@@ -95,6 +95,14 @@ export function draftMode(): DraftMode {
  * 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/context.js

@@ -55,6 +55,26 @@ export type RequestContext = {
   readonly deferred: Array<() => mixed | Promise<mixed>>,
 };
 
+/**
+ * One request, from the moment a host has one to the moment its bytes are gone.
+ *
+ * Two functions rather than one, because they are called from two places and
+ * that is the whole point rather than an inconvenience. `run` wraps everything
+ * that *decides* the response — the guard, the dispatcher, the render — and
+ * `settle` happens after the response has been *written*, which in every host
+ * uf has is a different line in a different module. A single
+ * `handle(request, body)` that drained when `body` returned would be the bug
+ * this exists to fix, spelled once instead of twice.
+ */
+export type RequestLifecycle = {|
+  /** The context `run` establishes, for a host that needs to read it. */
+  readonly context: RequestContext,
+  /** Run the whole request inside it. */
+  readonly run: <T>(body: () => Promise<T>) => Promise<T>,
+  /** The response has gone: run what `after()` deferred. */
+  readonly settle: () => Promise<void>,
+|};
+
 const storage: AsyncLocalStorage<RequestContext> = new AsyncLocalStorage();
 
 /**
@@ -68,6 +88,19 @@ export function currentContext(): RequestContext | null {
   return storage.getStore() ?? null;
 }
 
+/**
+ * Whether a request has been established around this call.
+ *
+ * For a caller that is not a server function and has nothing to answer about
+ * the request — the router's dispatcher and its middleware runner, which need
+ * to know that a host established one *before* anything they call asks for
+ * cookies. They must not be handed the context itself: a module that can reach
+ * it can drain it, which is how the drain came to be in the wrong place.
+ */
+export function insideRequest(): boolean {
+  return storage.getStore() != null;
+}
+
 /**
  * Run `body` with `context` as the current request.
  *
@@ -84,10 +117,19 @@ export function runWithContext<T>(context: RequestContext, body: () => T): T {
  * touches `cookies().get(…)` as often as it has components that care, and
  * re-parsing the cookie header each time would be the kind of cost nobody
  * looks for.
+ *
+ * Parsed on the first read rather than here, and that changed when the host
+ * became the thing that begins a request: a host begins one before it knows
+ * whether the path is an embedded chunk or a page, so every asset a compiled
+ * binary serves now builds a context. Splitting a `Cookie` header for a
+ * request that never asks about cookies is exactly the cost the paragraph
+ * above refuses to pay per read, and there is no reason to pay it per request
+ * either.
  */
 export function contextFor(request: Request): RequestContext {
   const headers = request.headers;
-  const cookies = parseCookies(headers.get("cookie"));
+  let cookies: { [string]: string } | null = null;
+  const parsed = () => (cookies ??= parseCookies(headers.get("cookie")));
 
   return {
     headers: {
@@ -95,14 +137,45 @@ export function contextFor(request: Request): RequestContext {
       has: (name) => headers.has(name),
     },
     cookies: {
-      get: (name) => (Object.hasOwn(cookies, name) ? cookies[name] : null),
-      has: (name) => Object.hasOwn(cookies, name),
+      get: (name) => (Object.hasOwn(parsed(), name) ? parsed()[name] : null),
+      has: (name) => Object.hasOwn(parsed(), name),
     },
     draft: false,
     deferred: [],
   };
 }
 
+/**
+ * Begin a request, and hand back the two halves of owning it.
+ *
+ * The one function a host calls. `contextFor`, `runWithContext` and
+ * `drainDeferred` are still here because they are what this is made of and
+ * because the suite drives them one at a time, but a *host* reaching for them
+ * separately is how uf got two contexts on one request and a drain that ran
+ * before the response: the middleware runner built one and drained it, and the
+ * dispatcher underneath it built another. See ubugeeei-prod/uf#389.
+ *
+ * `settle` runs once. A host learns that a response is finished more than once
+ * — the body stream closed, and then the socket did — and draining twice would
+ * run whatever the first drain's callbacks registered, at a moment nothing
+ * asked for.
+ */
+export function beginRequest(request: Request): RequestLifecycle {
+  const context = contextFor(request);
+  let settling: Promise<void> | null = null;
+
+  function run<T>(body: () => Promise<T>): Promise<T> {
+    return runWithContext(context, body);
+  }
+
+  function settle(): Promise<void> {
+    settling ??= drainDeferred(context);
+    return settling;
+  }
+
+  return { context, run, settle };
+}
+
 /**
  * Parse a `Cookie` header into a plain object.
  *

package/node.js

@@ -0,0 +1,460 @@
+// @flow
+//
+// `@uniflowed/server/node`: the Node half of serving a build.
+//
+// [`../fetch.js`] answers the application's half of a request and touches no
+// filesystem, because that is the half a worker runs. This is everything that
+// is left, and all of it is host-specific: reading a file out of a directory,
+// translating between Node's request objects and the platform's, and taking a
+// socket.
+//
+// Three things use it, and the point of it being one module is that they
+// cannot answer differently:
+//
+//   * `uf start`, through `@uniflowed/vite`'s `internal/serve.js`;
+//   * `uf preview`, through the same;
+//   * the `server.js` that `uf build --adapter node` writes, which imports
+//     this directly — a deployed application must not link the package named
+//     after the bundler, and before this module existed the only copy of the
+//     static half was inside `@uniflowed/vite`.
+//
+// The exception is `./standalone.js`, which serves from bytes it carries
+// instead of from a directory; its header says why it is a second
+// implementation rather than a caller of this one.
+//
+// # Who owns the request
+//
+// This module does, for every host that reaches it: [`nodeListener`] begins
+// the request, runs the whole of answering it inside `run`, and settles it on
+// the line after the last byte — after its own 500, when it wrote one. That is
+// what `after()` promises and it is not something a `Request` → `Response`
+// handler can promise for itself, because such a handler has a `Response` in
+// hand and not a response on the wire.
+//
+// `beginRequest` is passed in rather than imported from `./internal/context.js`
+// beside this file, and that is the one thing about this module 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 `.uf/build/server/server.js` — not the one this file resolves from the
+// host's `node_modules`. A host that began a request in the wrong storage
+// 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. So the
+// bundle hands it out, `@uniflowed/router/server` re-exports it, and a caller
+// passes it here. See ubugeeei-prod/uf#389.
+//
+// # The order is Vite's
+//
+// Static files first, then the application. That is a compatibility
+// requirement rather than a preference: Vite's preview server runs its own
+// file middleware before anything mounted behind it can see a request, so
+// `uf preview` serves a file first whether or not anything here agrees — and a
+// deployment that disagreed would mean a 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.
+
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import { Readable } from "node:stream";
+
+import type { RequestLifecycle } from "./internal/context.js";
+
+export type { RequestLifecycle } from "./internal/context.js";
+
+/**
+ * Content types for what a uf build emits.
+ *
+ * A closed table rather than a dependency, and deliberately short: every entry
+ * is an extension `uf build` actually writes or a project actually puts in
+ * `public/`. Anything else is `application/octet-stream`, which a browser
+ * downloads rather than executes — the safe answer for a file whose type we do
+ * not know, and the reason this is not a guess based on the bytes.
+ */
+const CONTENT_TYPES: { readonly [string]: string } = Object.freeze({
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webmanifest": "application/manifest+json",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8",
+});
+
+/**
+ * The pieces of a Node request this module touches.
+ *
+ * Declared structurally rather than imported from a `node:http` libdef, for
+ * the same reason `./standalone.js` does it: the set is small, and naming it
+ * here is what lets the file be read without knowing which host's types are in
+ * scope. `originalUrl` is Connect's, and it is here because `uf preview` runs
+ * this behind Vite's middleware stack, which sets it.
+ */
+export type NodeRequest = {
+  readonly method?: string,
+  readonly url?: string,
+  readonly originalUrl?: string,
+  readonly headers: { readonly [string]: string | Array<string> | void },
+  ...
+};
+
+/** The pieces of a Node response this module writes. */
+export type NodeResponse = {
+  statusCode: number,
+  statusMessage: string,
+  headersSent: boolean,
+  setHeader(name: string, value: string): mixed,
+  write(chunk: Uint8Array | string): boolean,
+  end(chunk?: Uint8Array | string): mixed,
+  destroy(error?: mixed): mixed,
+  // `send` paces itself against the socket and stops when the client hangs
+  // up, so it needs the events as well as the writes. `write` returns a
+  // `boolean` for the same reason — `mixed` would have made the back-pressure
+  // check unwritable, which is one way this was lost.
+  on(event: string, listener: () => mixed): mixed,
+  once(event: string, listener: () => mixed): mixed,
+  off(event: string, listener: () => mixed): mixed,
+  ...
+};
+
+/**
+ * A Node request as a `Request`.
+ *
+ * The body is passed as a stream where the host allows it, so a handler that
+ * accepts an upload does not need the whole thing buffered before it starts.
+ * `duplex` is required by the specification whenever a body is a stream, and
+ * Node throws without it.
+ */
+export function toRequest(
+  incoming: NodeRequest,
+  options?: {| readonly secure?: boolean |},
+): Request {
+  const host = incoming.headers.host;
+  const authority = typeof host === "string" && host !== "" ? host : "localhost";
+  const protocol = options?.secure === true ? "https" : "http";
+  const url = new URL(incoming.originalUrl ?? incoming.url ?? "/", `${protocol}://${authority}`);
+
+  const headers = new Headers();
+  for (const name of Object.keys(incoming.headers)) {
+    const value = incoming.headers[name];
+    if (value == null) continue;
+    for (const entry of Array.isArray(value) ? value : [value]) {
+      headers.append(name, entry);
+    }
+  }
+
+  const method = (incoming.method ?? "GET").toUpperCase();
+  const init: { [string]: mixed } = { method, headers };
+  if (method !== "GET" && method !== "HEAD") {
+    init.body = incoming;
+    init.duplex = "half";
+  }
+  // $FlowFixMe[incompatible-call] - `incoming` is a stream, which `Request` accepts.
+  return new Request(url, init);
+}
+
+/** Write a `Response` to a Node response. */
+export async function send(outgoing: NodeResponse, result: Response): Promise<void> {
+  outgoing.statusCode = result.status;
+  if (result.statusText !== "") {
+    outgoing.statusMessage = result.statusText;
+  }
+  for (const [name, value] of result.headers) {
+    outgoing.setHeader(name, value);
+  }
+  if (result.body == null) {
+    outgoing.end();
+    return;
+  }
+  // Streamed rather than buffered, so a handler returning a large or
+  // open-ended body is not read into memory first.
+  //
+  // Which was only half true while this loop read as fast as the body would
+  // give: `write` answers `false` when the kernel buffer is full and the rest
+  // is being held in *this process's* memory, and a reader that ignores that
+  // turns a slow client into a heap the size of everything it has not
+  // acknowledged. Streaming in shape and buffering in fact — the same failure
+  // `ChunkQueue` exists to avoid a layer up, in the renderer.
+  const reader = result.body.getReader();
+  // And a client that hangs up is the other half. Nothing written after that
+  // goes anywhere, and the producer behind the body — a render, a proxied
+  // upstream, an event stream — keeps producing for a reader that is never
+  // coming back. `cancel()` is what tells it to stop; `releaseLock()` would
+  // only detach this end.
+  let open = true;
+  const onClose = () => {
+    open = false;
+  };
+  outgoing.on("close", onClose);
+  try {
+    while (open) {
+      const { done, value } = await reader.read();
+      if (done === true || !open) break;
+      if (value != null && outgoing.write(value) === false) {
+        await writable(outgoing);
+      }
+    }
+  } finally {
+    outgoing.off("close", onClose);
+  }
+  if (open) {
+    outgoing.end();
+    return;
+  }
+  // Best effort, and the only place in this function where a rejection is
+  // dropped: the connection is already gone, so there is nobody left to report
+  // to and no response left to fail.
+  await reader.cancel().catch(() => {});
+}
+
+/**
+ * Resolve once `outgoing` can take more — or once it cannot ever again.
+ *
+ * `drain` alone would be a deadlock waiting to happen: a client that hangs up
+ * while the buffer is full emits `close` and never `drain`, and a writer
+ * waiting only for the latter waits for the life of the process, holding the
+ * body's producer open with it.
+ */
+function writable(outgoing: NodeResponse): Promise<void> {
+  return new Promise((resolve) => {
+    const settle = () => {
+      outgoing.off("drain", settle);
+      outgoing.off("close", settle);
+      resolve();
+    };
+    outgoing.once("drain", settle);
+    outgoing.once("close", settle);
+  });
+}
+
+/**
+ * The static half: a file under `root`, or `null` for the caller to carry on.
+ *
+ * `GET` and `HEAD` only. A `POST` to a path that happens to have a file under
+ * it belongs to a route handler, and answering it with the file's bytes would
+ * be the same mistake as rendering a page for it.
+ *
+ * # The path is checked once, after it is resolved
+ *
+ * `docs/security.md` rule 2: never authorize against a raw request string or a
+ * partially decoded path. The pathname is decoded first, then resolved against
+ * the root, and *then* checked to be inside it — so `%2e%2e%2f`, a backslash
+ * on Windows, and a symlinked directory all reduce to the same question, asked
+ * once, of the value that is actually opened.
+ */
+export function createStaticHandler(options: {|
+  readonly root: string,
+|}): (request: Request) => Promise<Response | null> {
+  const rootDir = path.resolve(options.root);
+
+  return async function serveStatic(request: Request): Promise<Response | null> {
+    const method = request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD") return null;
+
+    const pathname = decodePathname(new URL(request.url).pathname);
+    if (pathname == null) return null;
+
+    const resolved = path.resolve(rootDir, `.${pathname}`);
+    if (resolved !== rootDir && !resolved.startsWith(rootDir + path.sep)) return null;
+
+    // `/guide/` and `/guide` are the same prerendered document, and neither
+    // spelling is the one a person types. `<path>.html` is last because a
+    // build writes `guide/index.html`, and only a hand-placed file in
+    // `public/` is ever `guide.html`.
+    const candidates =
+      pathname.endsWith("/") === true
+        ? [path.join(resolved, "index.html")]
+        : [resolved, path.join(resolved, "index.html"), `${resolved}.html`];
+
+    for (const candidate of candidates) {
+      const info = await statFile(candidate);
+      if (info == null || !info.isFile()) continue;
+      const headers = {
+        "content-type":
+          CONTENT_TYPES[path.extname(candidate).toLowerCase()] ?? "application/octet-stream",
+        "content-length": String(info.size),
+      };
+      if (method === "HEAD") return new Response(null, { headers });
+      // Streamed rather than read into memory, so serving a large asset costs
+      // a buffer rather than the file.
+      // $FlowFixMe[incompatible-call] - a Node web stream is a `BodyInit`.
+      return new Response(Readable.toWeb(createReadStream(candidate)), { headers });
+    }
+    return null;
+  };
+}
+
+function decodePathname(pathname: string): string | null {
+  try {
+    const decoded = decodeURIComponent(pathname);
+    // A NUL truncates the name every C-level `open` sees, so a path holding
+    // one is refused rather than normalised into something shorter.
+    return decoded.includes("\0") ? null : decoded;
+  } catch {
+    // A percent escape that is not one. There is no file behind it.
+    return null;
+  }
+}
+
+async function statFile(file: string) {
+  try {
+    return await stat(file);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A `Request`/`Response` handler as a Node request listener.
+ *
+ * The handler contract is the platform's, so this adapter belongs here rather
+ * than in every host that wants to run one.
+ *
+ * `beginRequest` is required, and it comes from the application bundle for the
+ * reason in "Who owns the request" above. A listener built without one fails on
+ * its first request, which is the same trade `createFetchHandler` makes about
+ * `app.runMiddleware`: an optional lifecycle is a lifecycle somebody forgets,
+ * and what is lost when they do is every `after()` in the application.
+ *
+ * A handler that throws is answered with a bare 500 and reported on stderr:
+ * the body must not carry the stack, because the body goes to whoever asked,
+ * and stderr is where the operator is already looking. The drain is in a
+ * `finally` below the `catch`, so a middleware that logged the request sees its
+ * callback run once that 500 is on the wire rather than once the handler gave
+ * up — and a request that failed is still a request that happened, which is why
+ * it is drained at all.
+ */
+export function nodeListener(
+  handle: (request: Request) => Promise<Response>,
+  options: {|
+    readonly beginRequest: (request: Request) => RequestLifecycle,
+    readonly secure?: boolean,
+  |},
+): (incoming: NodeRequest, outgoing: NodeResponse) => Promise<void> {
+  return async function listener(incoming: NodeRequest, outgoing: NodeResponse): Promise<void> {
+    // Declared out here because `toRequest` is inside the `try`: a request that
+    // could not even be built has no lifecycle to settle.
+    let lifecycle: RequestLifecycle | null = null;
+    try {
+      const request = toRequest(incoming, options);
+      lifecycle = options.beginRequest(request);
+      await lifecycle.run(async () => {
+        await send(outgoing, await handle(request));
+      });
+    } catch (error) {
+      console.error(error);
+      if (outgoing.headersSent) {
+        outgoing.destroy();
+      } else {
+        outgoing.statusCode = 500;
+        outgoing.setHeader("content-type", "text/plain; charset=utf-8");
+        outgoing.end("500 Internal Server Error\n");
+      }
+    } finally {
+      if (lifecycle != null) await lifecycle.settle();
+    }
+  };
+}
+
+/**
+ * Static files, then the application: the whole of what a built uf app serves.
+ *
+ * `staticDir` is the directory `uf build` wrote — `dist/` in a checkout, and
+ * the `static/` copied beside `server.js` in an adapter's output.
+ */
+export function createServeHandler(options: {|
+  readonly staticDir: string,
+  readonly handle: (request: Request) => Promise<Response>,
+|}): (request: Request) => Promise<Response> {
+  const serveStatic = createStaticHandler({ root: options.staticDir });
+  return async function handle(request: Request): Promise<Response> {
+    return (await serveStatic(request)) ?? (await options.handle(request));
+  };
+}
+
+/**
+ * Serve the application until the process is stopped.
+ *
+ * What `uf build --adapter node` writes calls this and nothing else. It
+ * resolves once the socket is listening, with the address it took, because a
+ * caller that asked for port 0 has no other way to learn which port it got —
+ * and because a test that has to drive a deployed directory needs exactly
+ * that.
+ *
+ * `PORT` and `HOST` are read from the environment because that is how every
+ * process manager and container platform says which socket to take, and a
+ * production server that could only be told on the command line would need a
+ * wrapper script everywhere it ran. The command line wins over both, and the
+ * default address is every interface: a container that bound loopback would be
+ * a container nothing outside it can reach.
+ */
+export async function serve(options: {|
+  readonly staticDir: string,
+  readonly handle: (request: Request) => Promise<Response>,
+  /**
+   * The application bundle's own `beginRequest`.
+   *
+   * The generated `handler.js` re-exports it beside `fetch` so that
+   * `server.js` has one to pass; see "Who owns the request" above for why it
+   * cannot be imported here instead.
+   */
+  readonly beginRequest: (request: Request) => RequestLifecycle,
+  readonly host?: string,
+  readonly port?: number,
+|}): Promise<{|
+  readonly host: string,
+  readonly port: number,
+  readonly close: () => Promise<void>,
+|}> {
+  const listener = nodeListener(
+    createServeHandler({ staticDir: options.staticDir, handle: options.handle }),
+    { beginRequest: options.beginRequest },
+  );
+  const server = createServer((request, response) => {
+    void listener(request, response);
+  });
+
+  const host = options.host ?? argument("--host") ?? process.env.HOST ?? "0.0.0.0";
+  const port = options.port ?? Number(argument("--port") ?? process.env.PORT ?? 3000);
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+
+  const address = server.address();
+  const bound = typeof address === "object" && address != null ? address.port : port;
+  // `0.0.0.0` is not a URL anybody can open, so the loopback spelling is what
+  // is printed — the same split `uf dev` and `uf start` print, and for the
+  // same reason: one of the two is a link and the other is a fact about the
+  // socket.
+  const shown = host === "0.0.0.0" || host === "::" ? "localhost" : host;
+  process.stdout.write(`uf: listening on http://${shown}:${String(bound)}\n`);
+
+  return {
+    host,
+    port: bound,
+    close: () =>
+      new Promise((resolve) => {
+        server.close(() => resolve());
+      }),
+  };
+}
+
+/** The value of a `--flag value` pair on the command line, if it is there. */
+function argument(name: string): string | null {
+  const at = process.argv.indexOf(name);
+  return at === -1 ? null : (process.argv[at + 1] ?? null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/server",
-  "version": "0.0.0-alpha.7",
+  "version": "0.0.0-alpha.8",
   "description": "Request-scoped server functions for the Unified Toolchain for Flow (React).",
   "type": "module",
   "license": "MIT",
@@ -12,12 +12,16 @@
   },
   "exports": {
     ".": "./index.js",
+    "./fetch": "./fetch.js",
     "./host": "./host.js",
+    "./node": "./node.js",
     "./standalone": "./standalone.js"
   },
   "files": [
+    "fetch.js",
     "index.js",
     "host.js",
+    "node.js",
     "standalone.js",
     "internal/*.js"
   ]

package/standalone.js

@@ -52,6 +52,8 @@
 import { Buffer } from "node:buffer";
 import { createServer } from "node:http";
 
+import { send } from "./node.js";
+
 /**
  * The pieces of a Node request and response this module touches.
  *
@@ -71,6 +73,19 @@ type NodeResponse = {
   setHeader(name: string, value: string): mixed,
   write(chunk: Uint8Array | string): mixed,
   end(chunk?: Uint8Array | string): mixed,
+  // Required rather than optional, because the one case it exists for is the
+  // one where nothing else will do: a render that fails after the shell has
+  // gone out cannot be answered with a status, and dropping the socket is the
+  // only way left to tell the client the document it received is not whole.
+  destroy(error?: mixed): mixed,
+  // The events a writer has to listen to rather than assume: `drain`, so a body
+  // is paced by what the socket will take, and `close`, so a client that hung
+  // up stops the producer instead of being written at. Named individually, like
+  // `stream.js`'s `NodeDestination`, so that a host missing one of them fails
+  // to compile rather than to serve.
+  on(event: string, listener: (...args: Array<mixed>) => mixed): mixed,
+  once(event: string, listener: (...args: Array<mixed>) => mixed): mixed,
+  off(event: string, listener: (...args: Array<mixed>) => mixed): mixed,
   ...
 };
 
@@ -94,15 +109,57 @@ export type DocumentAssets = {|
 
 /** What the project's server bundle exports; see `virtual:uf/server`. */
 export type StandaloneApp = {|
+  /**
+   * Render `url`, resolving when the *shell* is ready.
+   *
+   * The same `{ status, headers?, pipe }` the router hands `uf start` and
+   * every adapter — not a finished string. A binary that collected the whole
+   * document before answering would be the one deployment target that does not
+   * stream, and the reason `renderToString` was replaced is that the wait is
+   * the slowest thing on the page.
+   */
   readonly render: (
     url: string,
     assets: DocumentAssets,
+    options?: {| readonly onError?: (error: mixed) => void |},
   ) => Promise<{|
     readonly status: number,
-    readonly html: string,
     readonly headers?: { readonly [string]: string },
+    // A promise, and not `void`: `DocumentBody.pipe` resolves on the last byte
+    // and rejects when the render fails after the shell. Typing it away was
+    // how the rejection below came to be dropped.
+    readonly pipe: (destination: NodeResponse) => Promise<void>,
+    readonly stream: () => ReadableStream<Uint8Array>,
   |}>,
   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 compiled. See ubugeeei-prod/uf#260, and
+   * `@uniflowed/vite`'s `createApplicationHandler`, which says the same thing
+   * about `uf preview` and `uf start`.
+   */
+  readonly runMiddleware: (request: Request) => Promise<Response | null>,
+  /**
+   * Begin the request everything above runs inside.
+   *
+   * From the application bundle rather than from this module's own import of
+   * `@uniflowed/server/host`, and that is not a stylistic choice: the request
+   * lives in an `AsyncLocalStorage` belonging to one module instance, and the
+   * instance that matters is the one the bundled router, middleware and pages
+   * resolved to. Beginning a request in a second storage would leave every
+   * `cookies()` in the application outside one, silently.
+   *
+   * `run` wraps everything that decides the response; `settle` is called after
+   * the last byte, which here is after `send`, after `sendBytes`, and after
+   * `pipe` resolves. See ubugeeei-prod/uf#389.
+   */
+  readonly beginRequest: (request: Request) => {|
+    readonly run: <T>(body: () => Promise<T>) => Promise<T>,
+    readonly settle: () => Promise<void>,
+  |},
 |};
 
 /** Everything an application needs to answer a request, all of it built in. */
@@ -292,40 +349,114 @@ export function createHandler(
       }
     }
 
-    const handled = await app.dispatch(toRequest(request, url));
-    if (handled != null) {
-      await send(response, method, handled);
-      return;
-    }
+    // The request begins here rather than at the top of the handler, and the
+    // two lookups above are why: an embedded chunk and a prerendered document
+    // are answered without any application code running at all, so there is
+    // nothing that could ask for cookies and nothing that could defer work.
+    // What is below is the application, and it is what a request is for.
+    //
+    // `app.beginRequest` and not this module's own import: the storage that
+    // holds a request belongs to one copy of `@uniflowed/server`, and the copy
+    // that matters is the one linked into the bundle beside this file.
+    //
+    // `settle` is in a `finally` and it is the last thing the handler does, so
+    // every `after()` runs after the response has been written — after `send`,
+    // after `sendBytes`, and after `pipe` resolves — which is what `after()`
+    // promises and what the other three hosts do. A request that failed is
+    // still a request that happened, so the drain is owed either way; see
+    // ubugeeei-prod/uf#389.
+    const asRequest = toRequest(request, url);
+    const { run, settle } = app.beginRequest(asRequest);
+    try {
+      await run(async () => {
+        // Middleware above the dispatcher and above the render, and below the two
+        // lookups on purpose. It guards a path, so it must run for a page, for a
+        // route handler, and for a path under it that matches neither — but an
+        // embedded asset and a prerendered document are answered before it, which
+        // is exactly what `uf preview` does, because Vite's file middleware runs
+        // before anything mounted behind it. The three front doors have to give
+        // one answer; that a prerendered page under a guard ships unguarded is
+        // true of all of them and is ubugeeei-prod/uf#342.
+        const guarded = await app.runMiddleware(asRequest);
+        if (guarded != null) {
+          await sendUnlessHead(response, method, guarded);
+          return;
+        }
 
-    if (method !== "GET" && method !== "HEAD") {
-      // A page supports exactly `GET` and `HEAD`, which is why the `Allow` the
-      // specification requires on every 405 can be written here even though
-      // this side of the handler knows nothing about methods. A *handler* path
-      // with the wrong method never reaches this line: the dispatcher answers
-      // that one itself, with the methods that module really exports.
-      response.setHeader("allow", "GET, HEAD");
-      sendBytes(
-        response,
-        method,
-        405,
-        "text/plain; charset=utf-8",
-        DOCUMENT_CACHE_CONTROL,
-        Buffer.from("method not allowed\n"),
-      );
-      return;
-    }
+        const handled = await app.dispatch(asRequest);
+        if (handled != null) {
+          await sendUnlessHead(response, method, handled);
+          return;
+        }
 
-    const rendered = await app.render(url.pathname + url.search, document);
-    response.statusCode = rendered.status;
-    response.setHeader("content-type", "text/html; charset=utf-8");
-    response.setHeader("cache-control", DOCUMENT_CACHE_CONTROL);
-    for (const name of Object.keys(rendered.headers ?? {})) {
-      response.setHeader(name, (rendered.headers ?? {})[name]);
+        if (method !== "GET" && method !== "HEAD") {
+          // A page supports exactly `GET` and `HEAD`, which is why the `Allow` the
+          // specification requires on every 405 can be written here even though
+          // this side of the handler knows nothing about methods. A *handler* path
+          // with the wrong method never reaches this line: the dispatcher answers
+          // that one itself, with the methods that module really exports.
+          response.setHeader("allow", "GET, HEAD");
+          sendBytes(
+            response,
+            method,
+            405,
+            "text/plain; charset=utf-8",
+            DOCUMENT_CACHE_CONTROL,
+            Buffer.from("method not allowed\n"),
+          );
+          return;
+        }
+
+        const rendered = await app.render(url.pathname + url.search, document, {
+          // There is no terminal to render into: this is a binary somebody started
+          // with `./app`, possibly under a supervisor. The console is where a
+          // supervisor looks, and losing a boundary's exception entirely would be
+          // worse — it is the only trace a page that failed after its first byte
+          // leaves anywhere.
+          onError: (error) => {
+            console.error(error);
+          },
+        });
+        response.statusCode = rendered.status;
+        response.setHeader("content-type", "text/html; charset=utf-8");
+        response.setHeader("cache-control", DOCUMENT_CACHE_CONTROL);
+        for (const name of Object.keys(rendered.headers ?? {})) {
+          response.setHeader(name, (rendered.headers ?? {})[name]);
+        }
+        // No `content-length`: the length is not known until the last byte, and
+        // waiting for it is the whole of what streaming is not. `HEAD` gets the
+        // status and the headers, and 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 rendered.stream().cancel();
+          response.end();
+          return;
+        }
+        // Awaited, because `pipe` rejects: React hands a post-shell failure to the
+        // destination's `destroy(error)`, `ChunkQueue.fail` records it, and the
+        // generator `pipe` is iterating rethrows it. Called and dropped, that
+        // rejection escapes this handler — `serve`'s `handle(…).catch` has already
+        // resolved — and lands on the process, where `--unhandled-rejections=throw`
+        // is the default and a binary someone started with `./app` exits in the
+        // middle of a request that was otherwise recoverable.
+        //
+        // It cannot become a 500. The shell went out with its status and headers
+        // long before this, and `pipe`'s own `finally` has already called `end()`.
+        // What is left is to say so where a supervisor looks, and to drop the
+        // socket: a chunked response that is closed cleanly is a client being told
+        // a truncated document is the whole document, which is the failure this
+        // pull request is named after.
+        try {
+          await rendered.pipe(response);
+        } catch (error) {
+          process.stderr.write(`uf: ${String(error?.stack ?? error)}\n`);
+          response.destroy(error);
+        }
+      });
+    } finally {
+      await settle();
     }
-    const html = Buffer.from(rendered.html, "utf8");
-    response.setHeader("content-length", String(html.byteLength));
-    response.end(method === "HEAD" ? undefined : html);
   };
 }
 
@@ -392,27 +523,41 @@ function toRequest(incoming: NodeRequest, url: URL): Request {
   return new Request(url, init);
 }
 
-/** Write a `Response` to a Node response. */
-async function send(outgoing: NodeResponse, method: string, result: Response): Promise<void> {
-  outgoing.statusCode = result.status;
-  for (const [name, value] of result.headers) {
-    outgoing.setHeader(name, value);
-  }
-  if (result.body == null || method === "HEAD") {
+/** `send`, except that a `HEAD` gets the status and the headers and no body. */
+async function sendUnlessHead(
+  outgoing: NodeResponse,
+  method: string,
+  result: Response,
+): Promise<void> {
+  if (method === "HEAD") {
+    outgoing.statusCode = result.status;
+    for (const [name, value] of result.headers) {
+      outgoing.setHeader(name, value);
+    }
     outgoing.end();
     return;
   }
-  // Streamed rather than buffered, so a handler returning a large or
-  // open-ended body is not read into memory first.
-  const reader = result.body.getReader();
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    outgoing.write(value);
-  }
-  outgoing.end();
+  await send(outgoing, result);
 }
 
+/**
+ * Write a `Response` to a Node response, minding the socket.
+ *
+ * `send` was written a third time here, with a comment saying the three copies
+ * had to answer alike because "a binary that buffered where `uf start` paced
+ * would be the one deployment target whose memory profile nobody had
+ * measured". They did not stay alike — ubugeeei-prod/uf#400 is the copy in
+ * `@uniflowed/server`'s `node.js` losing the pacing while this one kept it.
+ *
+ * The reason not to share was that importing `@uniflowed/vite` into the
+ * artefact a deployment runs is the property `uf start` exists to establish.
+ * That reason is gone: the loop lives in `@uniflowed/server` now, which is the
+ * package this file is *in*.
+ *
+ * `HEAD` stays here, at the call site, because it is a decision about a
+ * request rather than about writing a body.
+ */
+
 /** Write one embedded file, with the length a client needs to reuse a socket. */
 function sendBytes(
   outgoing: NodeResponse,