@uniflowed/server 0.0.0-alpha.10

package/internal/context.js

@@ -0,0 +1,285 @@
+// @flow
+//
+// Internal to `@uniflowed/server`: the request a server function is inside.
+//
+// `headers()` and `cookies()` take no arguments, which is the whole point —
+// a component nested six levels down should not have to be handed a request
+// that every layer between it and the server has to thread through. That
+// convenience needs somewhere to keep the request, and "somewhere" has exactly
+// one safe answer on a server: storage scoped to the asynchronous call tree of
+// the request being handled.
+//
+// A module-level variable would be wrong in a way that only shows up under
+// load. `renderToString` is synchronous, so a variable set around it reads
+// correctly — right up until a route awaits something, another request arrives
+// while it is suspended, and the second request's headers are what the first
+// one sees. `AsyncLocalStorage` is the primitive that does not have that bug,
+// and Node, Deno and Bun all provide it under the `node:` specifier.
+//
+// This module is server-only by construction: nothing in `@uniflowed/server`
+// is reachable from a client component, and `uf:rsc` classifies it that way.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { CacheOptions } from "./cache-store.js";
+
+/** A read-only view of one request's headers. */
+export type HeaderStore = {
+  readonly get: (name: string) => string | null,
+  readonly has: (name: string) => boolean,
+};
+
+/** A read-only view of one request's cookies. */
+export type CookieStore = {
+  readonly get: (name: string) => string | null,
+  readonly has: (name: string) => boolean,
+};
+
+/** Whether this request is rendering draft content, and how to change that. */
+export type DraftMode = {
+  readonly isEnabled: boolean,
+  readonly enable: () => void,
+  readonly disable: () => void,
+};
+
+/**
+ * Everything a server function may ask about the request it is inside.
+ *
+ * Deliberately not the `Request` itself. A server function that could reach the
+ * whole request could read the body, which is already being consumed by the
+ * thing that called it, and could hold it past the response.
+ */
+export type RequestContext = {
+  readonly headers: HeaderStore,
+  readonly cookies: CookieStore,
+  draft: boolean,
+  /** Work deferred until the response has been sent. */
+  readonly deferred: Array<() => mixed | Promise<mixed>>,
+  /**
+   * How many times this request has read state that varies per request.
+   *
+   * A counter rather than a flag, and the difference is what makes a route
+   * cache possible at all. A middleware that reads a cookie to decide whether
+   * to let the request through has not made the *page* vary — it either
+   * answered or it did not — so a flag set by that read would refuse to cache
+   * every page in every application that has an auth guard. A counter can be
+   * read before the render and again after the last byte, and what moved in
+   * between is exactly what the document depended on.
+   *
+   * Incremented by `../index.js`'s three bindings and by nothing else.
+   * `after()` reads the context too and does not touch this: registering
+   * deferred work says nothing about what the response contains.
+   */
+  requestStateReads: number,
+  /**
+   * The cache the host installed for this request, or `null`.
+   *
+   * On the context rather than in a module-level variable, which is the same
+   * decision `storage` above is and rests on the same fact: two requests are
+   * answered at once, and anything a server function reaches for by name has
+   * to be scoped to the request or it is scoped to whichever request set it
+   * last. It also means `revalidateTag()` in a server action reaches the store
+   * that answered the request the action is part of, rather than a copy some
+   * other module instance is holding — the hazard ubugeeei-prod/uf#389 is
+   * about, pointed at a cache.
+   */
+  cache: CacheOptions | null,
+};
+
+/**
+ * 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();
+
+/**
+ * The context of the request being handled, or `null` outside one.
+ *
+ * `null` rather than throwing, so each caller can say what *it* needed the
+ * request for — "cookies() was called outside a request" is a better error than
+ * one generic message from here.
+ */
+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.
+ *
+ * Everything `body` awaits sees the same context, and nothing outside it does.
+ */
+export function runWithContext<T>(context: RequestContext, body: () => T): T {
+  return storage.run(context, body);
+}
+
+/**
+ * Build a context from a `Request`.
+ *
+ * The header and cookie views are built once and read many times: a render
+ * 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;
+  let cookies: { [string]: string } | null = null;
+  const parsed = () => (cookies ??= parseCookies(headers.get("cookie")));
+
+  return {
+    headers: {
+      get: (name) => headers.get(name),
+      has: (name) => headers.has(name),
+    },
+    cookies: {
+      get: (name) => (Object.hasOwn(parsed(), name) ? parsed()[name] : null),
+      has: (name) => Object.hasOwn(parsed(), name),
+    },
+    draft: false,
+    deferred: [],
+    requestStateReads: 0,
+    cache: null,
+  };
+}
+
+/**
+ * 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.
+ *
+ * `Object.create(null)` rather than `{}`: a cookie called `__proto__` is a
+ * thing an attacker can set, and on an ordinary object it would not be a key
+ * at all — it would be the prototype.
+ *
+ * A duplicated name keeps the first value, which is what every server-side
+ * cookie parser does and what browsers send for a name set at two paths.
+ */
+export function parseCookies(header: string | null): { [string]: string } {
+  const out: { [string]: string } = Object.create(null);
+  if (header == null || header === "") {
+    return out;
+  }
+
+  for (const pair of header.split(";")) {
+    const at = pair.indexOf("=");
+    if (at < 0) {
+      continue;
+    }
+    const name = pair.slice(0, at).trim();
+    if (name === "" || Object.hasOwn(out, name)) {
+      continue;
+    }
+    out[name] = decodeValue(pair.slice(at + 1).trim());
+  }
+  return out;
+}
+
+/**
+ * Decode one cookie value, leaving it alone if it is not valid encoding.
+ *
+ * `decodeURIComponent` throws on a stray `%`, and a malformed cookie is not a
+ * reason to fail a request — the value is simply not what the sender meant.
+ */
+function decodeValue(value: string): string {
+  const unquoted =
+    value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+  try {
+    return decodeURIComponent(unquoted);
+  } catch {
+    return unquoted;
+  }
+}
+
+/**
+ * Run everything `after()` deferred, in the order it was registered.
+ *
+ * A failure is reported and does not stop the rest: deferred work is by
+ * definition not what the response depended on, and one broken analytics call
+ * should not take the others with it.
+ */
+export async function drainDeferred(context: RequestContext): Promise<void> {
+  const pending = context.deferred.splice(0, context.deferred.length);
+  for (const task of pending) {
+    try {
+      await task();
+    } catch (error) {
+      reportDeferredFailure(error);
+    }
+  }
+}
+
+/**
+ * Report a deferred task that threw.
+ *
+ * Isolated so a host can be given somewhere to put this; today it is the
+ * console, which is where an unhandled rejection would have gone anyway.
+ */
+function reportDeferredFailure(error: mixed): void {
+  // eslint-disable-next-line no-console
+  console.error("uf: a task registered with after() failed", error);
+}

package/lambda.js

@@ -0,0 +1,266 @@
+// @flow
+//
+// `@uniflowed/server/lambda`: the AWS Lambda half of serving a build.
+//
+// A serverless target has no server. What it has is one function per
+// invocation, whose signature belongs to the platform rather than to the Web —
+// so this module is a translation, and the thing being translated is the same
+// [`./fetch.js`] handler `uf start` and every other front door answer through.
+//
+// # One event shape, named
+//
+// **Payload format version 2.0**, which is what a Lambda Function URL always
+// sends and what an API Gateway *HTTP* API sends by default. It is not what an
+// API Gateway *REST* API sends (that is format 1.0, with `httpMethod`,
+// `path` and `multiValueHeaders`), and it is not an ALB target-group event.
+// Supporting all three by sniffing the event would be three untested code
+// paths where the platform's own documentation says which one you get; this
+// one is named in `docs/app/reference/cli/_uf.page.mdx`, and an event that is
+// not it is refused by [`toRequest`] with a message saying so rather than
+// answered from fields that happen to be undefined.
+//
+// # Buffered, and why that is a limitation rather than a choice
+//
+// `createFetchHandler` answers a document as a stream, so a `<Suspense>`
+// fallback reaches the browser while the page behind it is still resolving.
+// A Lambda response in this format is a JSON value, so the whole body is read
+// before the invocation returns and none of that streaming survives. Response
+// streaming exists — `awslambda.streamifyResponse`, on a Function URL whose
+// invoke mode is `RESPONSE_STREAM` — and this module does not implement it:
+// the wrapper is a global the managed runtime injects, so nothing outside a
+// real invocation can drive it, and an untested streaming path is worse than a
+// buffered one that says it is buffered. The 6 MB response payload limit is
+// the platform's and applies to what this returns.
+//
+// # The static half is here rather than on a CDN, unless you put one there
+//
+// `staticDir` is served through `./node.js`'s `createStaticHandler`, from the
+// deployment package itself, so the function answers a prerendered document
+// and a hashed asset without any other infrastructure existing. That is the
+// shape that works the moment it is uploaded; it is not the shape anybody
+// should keep. Every byte of `static/` is then billed as invocation time and
+// counted against the package limit, and a CloudFront distribution or an S3
+// origin in front of the function is what the platform expects. Leaving
+// `staticDir` out is how you say you have one — the application half then
+// answers alone, exactly as it does on a worker.
+
+import { Buffer } from "node:buffer";
+
+import { createStaticHandler } from "./node.js";
+
+import type { RequestLifecycle } from "./internal/context.js";
+
+export type { RequestLifecycle } from "./internal/context.js";
+
+/**
+ * An HTTP API payload format 2.0 event, as much of it as this module reads.
+ *
+ * Inexact and almost entirely optional, because it arrives from the platform
+ * rather than from a caller: the fields uf needs are checked in [`toRequest`],
+ * where a missing one can be reported as the wrong event shape.
+ */
+export type LambdaHttpEvent = {
+  readonly version?: string,
+  readonly rawPath?: string,
+  readonly rawQueryString?: string,
+  readonly cookies?: $ReadOnlyArray<string>,
+  readonly headers?: { readonly [string]: string | void },
+  readonly body?: string,
+  readonly isBase64Encoded?: boolean,
+  readonly requestContext?: {
+    readonly domainName?: string,
+    readonly http?: {
+      readonly method?: string,
+      readonly path?: string,
+      ...
+    },
+    ...
+  },
+  ...
+};
+
+/** What Lambda expects back for payload format 2.0. */
+export type LambdaHttpResult = {|
+  readonly statusCode: number,
+  readonly headers: { [string]: string },
+  readonly cookies: $ReadOnlyArray<string>,
+  readonly body: string,
+  readonly isBase64Encoded: boolean,
+|};
+
+/** Everything the serverless half needs to answer an invocation. */
+export type LambdaHandlerOptions = {|
+  /** The application, from the generated `handler.js`. */
+  readonly handle: (request: Request) => Promise<Response>,
+  /** That same module's `beginRequest`; see [`./node.js`]'s header for why. */
+  readonly beginRequest: (request: Request) => RequestLifecycle,
+  /**
+   * The directory holding the build's own files, if the package carries them.
+   *
+   * Omitted where a CDN answers for them; see the header.
+   */
+  readonly staticDir?: string,
+|};
+
+/**
+ * The `getSetCookie` half of `Headers`.
+ *
+ * Declared rather than called straight off the value because iterating
+ * `Headers` joins repeated fields with a comma, and `Set-Cookie` is the one
+ * field where that is a corruption rather than a spelling: two cookies become
+ * one header nothing can parse back apart. `getSetCookie` is the standard
+ * answer and every runtime that can run this has it — but a runtime that does
+ * not would throw here rather than at the point the cookies were set, so the
+ * absence is checked.
+ */
+type SetCookieReader = {
+  readonly getSetCookie?: () => $ReadOnlyArray<string>,
+  ...
+};
+
+/**
+ * Media types whose bodies are text, and therefore not base64.
+ *
+ * The same shape of decision `./node.js` makes with `CONTENT_TYPES`, and the
+ * same default: what is not known to be text is returned base64-encoded, which
+ * is lossless for every byte sequence. Getting it the other way round would
+ * corrupt an image silently.
+ */
+const TEXT_TYPES: $ReadOnlyArray<string> = Object.freeze([
+  "application/javascript",
+  "application/json",
+  "application/manifest+json",
+  "application/xml",
+  "image/svg+xml",
+]);
+
+/** Whether a response with this `content-type` can be returned as a string. */
+function isText(contentType: string | null): boolean {
+  if (contentType == null) return false;
+  const media = contentType.split(";")[0].trim().toLowerCase();
+  if (media.startsWith("text/")) return true;
+  if (media.endsWith("+json") || media.endsWith("+xml")) return true;
+  return TEXT_TYPES.includes(media);
+}
+
+/**
+ * The event as a `Request`.
+ *
+ * The URL is rebuilt rather than taken from a field, because no field holds
+ * one: the path is `rawPath`, the query is `rawQueryString`, and the authority
+ * is the `host` header the client sent — falling back to the API's own domain,
+ * which is what a health check with no `Host` arrives with. `https`, always:
+ * both a Function URL and an HTTP API terminate TLS, and there is no spelling
+ * of either that a browser reaches over `http`.
+ *
+ * Cookies come from `event.cookies` and not from a header, because that is
+ * where format 2.0 puts them — an application reading `cookies()` would
+ * otherwise see none of them, which is the kind of difference between a
+ * deployment and `uf start` this whole seam exists to prevent.
+ */
+export function toRequest(event: LambdaHttpEvent): Request {
+  const method = event.requestContext?.http?.method;
+  const rawPath = event.rawPath;
+  if (typeof method !== "string" || typeof rawPath !== "string") {
+    throw new Error(
+      "uf: this handler reads AWS Lambda payload format 2.0 — a Lambda Function URL, " +
+        "or an API Gateway HTTP API — and the event it was given has no " +
+        "`requestContext.http.method` and `rawPath`. An API Gateway REST API sends " +
+        "format 1.0 and an ALB sends its own shape; neither is supported.",
+    );
+  }
+
+  const headers = new Headers();
+  const source = event.headers ?? {};
+  for (const name of Object.keys(source)) {
+    const value = source[name];
+    if (typeof value === "string") headers.set(name, value);
+  }
+  const cookies = event.cookies ?? [];
+  if (cookies.length > 0) headers.set("cookie", cookies.join("; "));
+
+  const authority =
+    headers.get("host") ?? event.requestContext?.domainName ?? "lambda.amazonaws.com";
+  const query = event.rawQueryString ?? "";
+  const url = new URL(`https://${authority}${rawPath}${query === "" ? "" : `?${query}`}`);
+
+  const init: { [string]: mixed } = { method: method.toUpperCase(), headers };
+  // `Request` refuses a body on a `GET` or a `HEAD`, and API Gateway is under
+  // no obligation not to send one: a client can, and the invocation would then
+  // fail with a `TypeError` from the constructor rather than answer.
+  if (typeof event.body === "string" && !["GET", "HEAD"].includes(method.toUpperCase())) {
+    init.body =
+      event.isBase64Encoded === true ? Buffer.from(event.body, "base64") : Buffer.from(event.body);
+  }
+  return new Request(url, init);
+}
+
+/** A `Response` as the JSON value Lambda returns to the client. */
+export async function toResult(response: Response): Promise<LambdaHttpResult> {
+  const headers: { [string]: string } = {};
+  for (const [name, value] of response.headers) {
+    // Skipped here and carried in `cookies` below: see [`SetCookieReader`].
+    if (name.toLowerCase() === "set-cookie") continue;
+    headers[name] = value;
+  }
+  const reader: SetCookieReader = response.headers;
+  const cookies = typeof reader.getSetCookie === "function" ? [...reader.getSetCookie()] : [];
+
+  const body = Buffer.from(await response.arrayBuffer());
+  const text = isText(response.headers.get("content-type"));
+  return {
+    statusCode: response.status,
+    headers,
+    cookies,
+    body: text ? body.toString("utf8") : body.toString("base64"),
+    isBase64Encoded: !text,
+  };
+}
+
+/**
+ * A built uf application as a Lambda handler.
+ *
+ * Static files first, then the application — the order `uf preview` cannot
+ * deviate from and therefore the order every other front door matches. The
+ * request is begun here and settled once the body has been read into the
+ * result, which on this target is genuinely "the response has been produced":
+ * an invocation that returned before its `after()` callbacks ran would have
+ * them killed with the sandbox, so `settle` is awaited rather than deferred.
+ */
+export function createLambdaHandler(
+  options: LambdaHandlerOptions,
+): (event: LambdaHttpEvent) => Promise<LambdaHttpResult> {
+  const { handle, beginRequest, staticDir } = options;
+  const serveStatic = staticDir == null ? null : createStaticHandler({ root: staticDir });
+
+  return async function lambdaHandler(event: LambdaHttpEvent): Promise<LambdaHttpResult> {
+    const request = toRequest(event);
+    const lifecycle = beginRequest(request);
+    try {
+      return await lifecycle.run(async () => {
+        const asset = serveStatic == null ? null : await serveStatic(request);
+        return await toResult(asset ?? (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, and the console — which on
+      // Lambda is CloudWatch — is where the operator is already looking. A
+      // rejected invocation would be a 502 from API Gateway instead, which is
+      // a different answer from `uf start`'s for the same failure.
+      //
+      // `toRequest` above is deliberately outside this: an event in the wrong
+      // format is a misconfigured function rather than a failed request, and
+      // answering it 500 forever would hide that.
+      console.error(error);
+      return {
+        statusCode: 500,
+        headers: { "content-type": "text/plain; charset=utf-8" },
+        cookies: [],
+        body: "500 Internal Server Error\n",
+        isBase64Encoded: false,
+      };
+    } finally {
+      await lifecycle.settle();
+    }
+  };
+}