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

package/edge.js

@@ -0,0 +1,158 @@
+// @flow
+//
+// `@uniflowed/server/edge`: the Cloudflare Workers 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 on a worker, and there is much less of it than there is on Node: a
+// worker has no socket to take and no directory to read, so what remains is
+// the request lifecycle and the one decision `./node.js` makes with `stat` —
+// does a file the build already wrote answer this, or does the application.
+//
+// # Where the static half went
+//
+// To the platform. Workers static assets are uploaded beside the script and
+// served by Cloudflare's own asset server; the Worker reaches them through the
+// `ASSETS` binding declared in `wrangler.json`, which answers a `Request` with
+// a `Response` exactly as `createStaticHandler` does — and answers `404` where
+// that returns `null`, which is the only translation this module performs.
+//
+// The Worker asks *first*, and `uf build --adapter edge` writes
+// `"run_worker_first": true` so that it can. That looks like the wrong way
+// round — Cloudflare's default is to serve a matching asset without invoking
+// the script at all, which is faster and resolves a file/handler collision the
+// same way — but the default also puts the resolution order in a platform
+// setting rather than in uf, and `tests/library/deploy.test.js` cannot drive a
+// platform setting. Asking here means one order, written once, checked by the
+// test that checks `uf start`'s. See ubugeeei-prod/uf#391.
+//
+// # Who owns the request, and the one thing a worker cannot promise
+//
+// `after()` says "once the response has been sent", and there is no such line
+// in a worker: [`createWorkerFetch`] has a `Response` in hand, and the platform
+// writes its body after the handler has returned. `ctx.waitUntil` is the
+// documented way to keep the isolate alive for work that outlives the handler,
+// so that is what `settle` is handed — which means an `after()` callback on
+// this target begins when the response has been *decided* rather than when its
+// last byte is out. For a streamed document those are a document apart. It is
+// written down here, in `docs/app/reference/cli/_uf.page.mdx`, and it is the
+// one behavioural difference between this target and the other three.
+//
+// `beginRequest` is passed in rather than imported, for the reason `./node.js`
+// gives at length: the request lives in an `AsyncLocalStorage` belonging to a
+// module instance, and the instance the application reads is the one bundled
+// into the `handler.js` beside the generated `worker.js`. See
+// ubugeeei-prod/uf#389.
+
+import type { RequestLifecycle } from "./internal/context.js";
+
+export type { RequestLifecycle } from "./internal/context.js";
+
+/**
+ * The `ASSETS` binding, as much of it as this module uses.
+ *
+ * One method, declared structurally: a worker's bindings are supplied by the
+ * runtime, and naming the whole of Cloudflare's `Fetcher` here would be this
+ * package holding a copy of another project's types.
+ */
+export type AssetsBinding = {
+  readonly fetch: (request: Request) => Promise<Response>,
+  ...
+};
+
+/**
+ * The `env` a Worker's `fetch` is called with.
+ *
+ * Inexact, because a project's own bindings — a KV namespace, a secret — are
+ * in here too and are none of this module's business. `ASSETS` is optional
+ * because a Worker deployed without an assets directory has no such binding,
+ * and the honest answer for that deployment is "the application answers
+ * everything" rather than a `TypeError` on the first request.
+ */
+export type EdgeEnvironment = {
+  readonly ASSETS?: AssetsBinding,
+  ...
+};
+
+/**
+ * The `ctx` a Worker's `fetch` is called with.
+ *
+ * `waitUntil` only. `passThroughOnException` exists and is deliberately not
+ * used: it serves the origin's response when the script throws, and a Worker
+ * that *is* the origin has nothing to pass through to.
+ */
+export type ExecutionContext = {
+  readonly waitUntil: (promise: Promise<mixed>) => mixed,
+  ...
+};
+
+/** Everything the worker half needs to answer a request. */
+export type WorkerHandlerOptions = {|
+  /** The application, from the generated `handler.js`. */
+  readonly handle: (request: Request) => Promise<Response>,
+  /** That same module's `beginRequest`; see the header. */
+  readonly beginRequest: (request: Request) => RequestLifecycle,
+|};
+
+/**
+ * A built uf application as a Worker's `fetch`.
+ *
+ * Static assets first, then the application — the order `uf preview` cannot
+ * deviate from and therefore the order every other front door matches. The
+ * asset lookup is skipped for anything that is not a `GET` or a `HEAD`, which
+ * is what `createStaticHandler` does and for the same reason: a `POST` to a
+ * path that happens to have a file under it belongs to a route handler.
+ *
+ * A `404` from the assets binding means "no such asset", not "the site has no
+ * such page": `wrangler.json` sets `"not_found_handling": "none"` so that the
+ * miss falls through to here, and the 404 a visitor sees is the project's own
+ * `_uf.not-found` rendered by the application. Any other status is the asset's
+ * answer and is returned as it stands.
+ */
+export function createWorkerFetch(
+  options: WorkerHandlerOptions,
+): (request: Request, env: EdgeEnvironment, ctx?: ExecutionContext) => Promise<Response> {
+  const { handle, beginRequest } = options;
+
+  return async function fetchFromWorker(
+    request: Request,
+    env: EdgeEnvironment,
+    ctx?: ExecutionContext,
+  ): Promise<Response> {
+    const lifecycle = beginRequest(request);
+    try {
+      return await lifecycle.run(async () => {
+        const assets = env?.ASSETS;
+        const method = request.method.toUpperCase();
+        if (assets != null && (method === "GET" || method === "HEAD")) {
+          const asset = await assets.fetch(request);
+          if (asset.status !== 404) return asset;
+        }
+        return await handle(request);
+      });
+    } catch (error) {
+      // The same 500 `./node.js`'s `nodeListener` writes, and for the same
+      // reasons: the body must not carry the stack, because the body goes to
+      // whoever asked, and the console is where the operator is already
+      // looking. Without this the answer would be Cloudflare's own error page,
+      // which is a different answer from `uf start`'s for the same failure —
+      // and the whole claim of the seam is that there is one answer.
+      console.error(error);
+      return new Response("500 Internal Server Error\n", {
+        status: 500,
+        headers: { "content-type": "text/plain; charset=utf-8" },
+      });
+    } finally {
+      // Scheduled rather than awaited: awaiting it here would hold the
+      // response back until every `after()` callback had finished, which is
+      // the opposite of what `after()` is for. Where there is no `ctx` — a
+      // test, or a host that calls this directly — it is awaited, because
+      // dropping the promise would lose both the work and its rejection.
+      if (ctx != null) {
+        ctx.waitUntil(lifecycle.settle());
+      } else {
+        await lifecycle.settle();
+      }
+    }
+  };
+}

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.
  *