@uniflowed/server 0.0.0-alpha.2

package/host.js

@@ -0,0 +1,23 @@
+// @flow
+//
+// `@uniflowed/server/host`: how a host establishes a request.
+//
+// The other half of this package. `@uniflowed/server` is what an application
+// calls *inside* a request; this is what a renderer, a route dispatcher or a
+// server-action bridge calls to say that a request has begun and, later, that
+// the response has gone.
+//
+// Two subpaths rather than one module, because they have opposite audiences and
+// opposite rules. Everything in the root is safe to call from a component and
+// meaningless outside a request; everything here is meaningless *inside* one
+// and must be called exactly once around it. Mixing them would put
+// `runWithContext` in the same import a page reaches for, which is an invitation
+// to nest one request inside another.
+//
+// It is a subpath rather than `internal/` because a sibling package cannot
+// reach another's internals: `@uniflowed/router` is where a request begins, and
+// it is a different npm package.
+
+export type { CookieStore, DraftMode, HeaderStore, RequestContext } from "./internal/context.js";
+
+export { contextFor, drainDeferred, parseCookies, runWithContext } from "./internal/context.js";

package/index.js

@@ -0,0 +1,101 @@
+// @flow
+//
+// `@uniflowed/server`: what a server function may ask about its request.
+//
+// Every binding here takes no arguments and answers about the request being
+// handled, which is only possible because the renderer establishes a context
+// around each one ([`./internal/context.js`]). Outside a request they throw,
+// and each says what it was that had nowhere to look — a component that calls
+// `cookies()` during a static prerender has made a mistake worth naming, not a
+// mistake worth returning `null` for.
+//
+// This module is server-only. Nothing in it is reachable from a client
+// component, `uf:rsc` classifies it that way, and importing it from one is the
+// error that classification exists to produce.
+
+import type { CookieStore, DraftMode, HeaderStore } from "./internal/context.js";
+import { currentContext } from "./internal/context.js";
+
+export type { CookieStore, DraftMode, HeaderStore } from "./internal/context.js";
+
+/**
+ * Raised when a server function is called with no request to answer about.
+ *
+ * Names the binding, because "no request context" on its own leaves a reader
+ * hunting for which of the six things they called was the one out of place.
+ */
+export class OutsideRequestError extends Error {
+  /** The binding that was called, e.g. `cookies`. */
+  binding: string;
+
+  constructor(binding: string) {
+    super(
+      `@uniflowed/server: ${binding}() was called outside a request. ` +
+        "It answers about the request being handled, and there is not one here — " +
+        "a static prerender, a module's top level, or a client component.",
+    );
+    this.name = "OutsideRequestError";
+    this.binding = binding;
+  }
+}
+
+/** The current request's context, or a named failure. */
+function require$Context(binding: string) {
+  const context = currentContext();
+  if (context == null) {
+    throw new OutsideRequestError(binding);
+  }
+  return context;
+}
+
+/**
+ * The request's headers, read-only.
+ *
+ * Read-only because a response header set from inside a render has no defined
+ * moment to take effect: the headers may already be on the wire by the time a
+ * component deep in the tree renders.
+ */
+export function headers(): HeaderStore {
+  return require$Context("headers").headers;
+}
+
+/**
+ * The request's cookies, read-only.
+ *
+ * Setting a cookie belongs to a route handler or a server action, which run
+ * before a response exists and can say so in it.
+ */
+export function cookies(): CookieStore {
+  return require$Context("cookies").cookies;
+}
+
+/**
+ * Whether this request is rendering draft content.
+ *
+ * The flag lives on the request rather than in a module, so two requests being
+ * handled at once cannot see each other's answer.
+ */
+export function draftMode(): DraftMode {
+  const context = require$Context("draftMode");
+  return {
+    isEnabled: context.draft,
+    enable: () => {
+      context.draft = true;
+    },
+    disable: () => {
+      context.draft = false;
+    },
+  };
+}
+
+/**
+ * Run `callback` once the response has been sent.
+ *
+ * For the work a request causes but a response does not wait on: recording a
+ * view, flushing a metric, warming a cache. Registered work runs in the order
+ * it was registered, and one task failing does not stop the others — deferred
+ * work is by definition not what the response depended on.
+ */
+export function after(callback: () => mixed | Promise<mixed>): void {
+  require$Context("after").deferred.push(callback);
+}

package/internal/context.js

@@ -0,0 +1,179 @@
+// @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";
+
+/** 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>>,
+};
+
+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;
+}
+
+/**
+ * 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.
+ */
+export function contextFor(request: Request): RequestContext {
+  const headers = request.headers;
+  const cookies = parseCookies(headers.get("cookie"));
+
+  return {
+    headers: {
+      get: (name) => headers.get(name),
+      has: (name) => headers.has(name),
+    },
+    cookies: {
+      get: (name) => (Object.hasOwn(cookies, name) ? cookies[name] : null),
+      has: (name) => Object.hasOwn(cookies, name),
+    },
+    draft: false,
+    deferred: [],
+  };
+}
+
+/**
+ * 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/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@uniflowed/server",
+  "version": "0.0.0-alpha.2",
+  "description": "Request-scoped server functions for the Unified Toolchain for Flow (React).",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/server"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./host": "./host.js"
+  },
+  "files": [
+    "index.js",
+    "host.js",
+    "internal/*.js"
+  ]
+}