@rangojs/router 0.18.0 → 0.19.1

package/src/server/cookie-store.ts

@@ -8,14 +8,20 @@
  */
 
 import type { CookieOptions } from "../router/middleware-types.js";
-import { getRequestContext, _getRequestContext } from "./request-context.js";
+import type { Theme } from "../theme/types.js";
 import {
-  isInsideCacheScope,
-  assertNotInsideShellCapture,
-  tripShellCaptureGuard,
+  getRequestContext,
+  _getRequestContext,
+  type RequestContext,
+} from "./request-context.js";
+import {
+  guardIdentityRead,
   recordLoaderIdentityRead,
+  refuseInCacheScope,
+  requestReadCaptureFix,
+  type IdentityReadWording,
 } from "./context.js";
-import { isInsideCacheExecScope } from "../cache/cache-exec-scope.js";
+import { requestHeaders, shadowRequestHeaders } from "./request-headers.js";
 
 /**
  * A single cookie entry returned by get() and getAll().
@@ -66,8 +72,7 @@ export interface CookieStore {
  */
 export function cookies(): CookieStore {
   const ctx = getRequestContext();
-  assertNotInsideCacheContext("cookies");
-  assertNotInsideShellCapture(ctx, "cookies");
+  guardIdentityRead(ctx, "cookies()", COOKIES_READ);
   return createCookieStore(ctx);
 }
 
@@ -91,66 +96,98 @@ export interface ReadonlyHeaders {
 type HeadersIterator<T> = IterableIterator<T>;
 
 /**
- * Throw if called inside a cache boundary — either a "use cache" function
- * (`isInsideCacheExecScope()` — the AsyncLocalStorage scope the cache runtime
- * enters around the cached body) or a `cache()` DSL boundary
- * (`isInsideCacheScope()` — the render-store flag set while resolving a
- * `type: "cache"` route entry).
- *
- * Reading request-scoped data (cookies, headers) inside a cached scope
- * produces per-request values that are NOT reflected in the cache key, so
- * they would be frozen into the shared cache entry and served to the wrong
- * users. This is the same hazard for both scopes: a `cache()` boundary caches
- * everything except loaders (it is the document-level "PPR shell"), so a read
- * here is baked into the shell exactly like a `"use cache"` return value is
- * baked into its cache entry.
- *
- * Both checks are scoped so loaders stay exempt — loaders are the dynamic
- * "holes" of a cached document and always run fresh. `isInsideCacheScope()`
- * returns false inside loaders by construction; `isInsideCacheExecScope()`
- * follows the cached body's own async chain, so a loader running in PARALLEL
- * with a slow "use cache" fetch on the same request reads cookies() freely.
- * (Scar: the previous INSIDE_CACHE_EXEC stamp on the shared RequestContext
- * made exactly that parallel read throw for the cached fetch's whole
- * execution window — see cache-exec-scope.ts.)
- *
- * The loader cache() identity reads (#972) are recorded by the read methods
- * instead (createCookieStore, the headers() view), so a write alone is not one.
+ * The cache-scope wording of cookies(), headers() and the response
+ * directives. Request-scoped data read in a cached scope is not reflected in
+ * its key, so it would be frozen into the shared entry and served to the
+ * wrong users; a "use cache" scope follows the cached body's own async chain
+ * (cache-exec-scope.ts), so a loader running in PARALLEL with a slow cached
+ * fetch on the same request reads cookies() freely. (Scar: an
+ * INSIDE_CACHE_EXEC stamp on the shared RequestContext made that parallel
+ * read throw for the fetch's whole execution window.)
  */
-function assertNotInsideCacheContext(fnName: string): void {
-  const scope = refusingCacheScope();
-  if (scope === "use cache") {
-    throw new Error(
-      `${fnName}() cannot be called inside a "use cache" function. ` +
-        `Request-scoped data (cookies, headers) varies per request but is not ` +
-        `reflected in the cache key, so cached results would be served to the ` +
-        `wrong users. Extract the value before the cached function and pass it ` +
-        `as an argument:\n\n` +
-        `  const locale = cookies().get("locale")?.value ?? "en";\n` +
-        `  const data = await getCachedData(locale); // locale is now in the cache key`,
-    );
-  }
-  if (scope === "cache()") {
-    throw new Error(
-      `${fnName}() cannot be called inside a cache() boundary. ` +
-        `A cache() scope caches everything except loaders, so request-scoped ` +
-        `data (cookies, headers) read here would be frozen into the shared ` +
-        `cached shell and served to other users. Read it inside a loader ` +
-        `instead — loaders always run fresh on every request, even on a cache hit:\n\n` +
-        `  loader("user", () => getUser(cookies().get("session")?.value));`,
-    );
-  }
+const REQUEST_READ_CACHE_FIX: Pick<
+  IdentityReadWording["fix"],
+  "useCache" | "cacheScope"
+> = {
+  useCache:
+    "Request-scoped data (cookies, headers) varies per request but is not " +
+    "reflected in the cache key, so cached results would be served to the " +
+    "wrong users. Extract the value before the cached function and pass it " +
+    "as an argument:\n\n" +
+    '  const locale = cookies().get("locale")?.value ?? "en";\n' +
+    "  const data = await getCachedData(locale); // locale is now in the cache key",
+  cacheScope:
+    "A cache() scope caches everything except loaders, so request-scoped " +
+    "data (cookies, headers) read here would be frozen into the shared " +
+    "cached shell and served to other users. Read it inside a loader " +
+    "instead — loaders always run fresh on every request, even on a cache hit:\n\n" +
+    '  loader("user", () => getUser(cookies().get("session")?.value));',
+};
+
+/**
+ * cookies() and headers() record the read on the returned view's read
+ * methods (createCookieStore, the headers() proxy), so a write alone is not
+ * one (#972).
+ */
+function requestReadWording(what: string): IdentityReadWording {
+  return {
+    verb: "called",
+    fix: { ...REQUEST_READ_CACHE_FIX, ...requestReadCaptureFix(what) },
+    record: false,
+  };
+}
+
+const COOKIES_READ: IdentityReadWording = requestReadWording("cookies");
+const HEADERS_READ: IdentityReadWording = requestReadWording("headers");
+
+/**
+ * The raw reads (#976): `ctx.request.headers` and `getRequestContext()
+ * .cookie()` / `.cookies()`. Same wording as cookies()/headers(), but each
+ * returns the data itself, so the read is recorded at the access.
+ */
+const REQUEST_HEADERS_READ: IdentityReadWording = {
+  verb: "read",
+  fix: HEADERS_READ.fix,
+};
+const RAW_COOKIES_READ: IdentityReadWording = {
+  verb: "called",
+  fix: COOKIES_READ.fix,
+};
+
+/**
+ * Run the identity guard for a raw cookie read on `ctx`
+ * (request-context.ts `cookie()` / `cookies()`). Before #976 they were plain
+ * reads of the Cookie header that no shared scope refused. The guard reads
+ * the ambient context, as cookies() does, and falls back to `ctx`.
+ */
+export function guardRawCookieRead(
+  ctx: RequestContext<any>,
+  surface: "getRequestContext().cookie()" | "getRequestContext().cookies()",
+): void {
+  guardIdentityRead(_getRequestContext() ?? ctx, surface, RAW_COOKIES_READ);
+}
+
+function guardRequestHeadersRead(): void {
+  guardIdentityRead(
+    _getRequestContext(),
+    "ctx.request.headers",
+    REQUEST_HEADERS_READ,
+  );
 }
 
 /**
- * The cache scope that refuses a request-scoped read here, or undefined. One
- * owner of the predicates and their order (assertNotInsideCacheContext above),
- * so cookies()/headers() and the theme reads refuse in the same places.
+ * Guard `request.headers` like headers() (#976): the request every ctx
+ * exposes (request context, handler, middleware and loader `ctx.request`)
+ * gets an own getter that runs guardIdentityRead against the ambient request
+ * context, so a read inside a ppr capture, a cache() boundary, a "use cache"
+ * body or an unkeyed loader cache() fill refuses as cookies() does. A Request
+ * argument keys a "use cache" entry by its URL only (cache-runtime.ts), so a
+ * header read there baked the first caller's value into the shared entry.
+ * The router's own reads go through requestHeaders() (request-headers.ts).
+ * Idempotent; returns `request`.
  */
-function refusingCacheScope(): "use cache" | "cache()" | undefined {
-  if (isInsideCacheExecScope()) return "use cache";
-  if (isInsideCacheScope()) return "cache()";
-  return undefined;
+export function guardRequestHeaders(request: Request): Request {
+  return shadowRequestHeaders(request, guardRequestHeadersRead);
 }
 
 /** The fix for a theme read that a cache() boundary or a ppr capture refuses. */
@@ -160,57 +197,49 @@ const THEME_READ_FIX =
   "The <html> theme class needs neither: the theme script sets it before paint. " +
   "See the /theme skill (node_modules/@rangojs/router/skills/theme/SKILL.md).";
 
-/** The public reads of the visitor's theme cookie that assertThemeReadAllowed guards. */
+/**
+ * The theme is the visitor's theme cookie, so a read of it is an identity
+ * read like cookies() (guardIdentityRead). Before #971 each read was a plain
+ * cookie read, so a ppr shell, a cache() entry or a "use cache" entry stored
+ * the first visitor's theme and served it to every later visitor.
+ */
+const THEME_READ: IdentityReadWording = {
+  verb: "read",
+  fix: {
+    useCache:
+      "The theme comes from the visitor's cookie and is not in the cache " +
+      "key, so the first caller's theme would be served to later callers. " +
+      "Read it before the cached function and pass it in as an argument.",
+    cacheScope:
+      "The theme comes from the visitor's cookie, so the first visitor's " +
+      "theme would be stored in the shared entry and served to everyone. " +
+      THEME_READ_FIX,
+    capture:
+      "The captured shell is served to every visitor of this URL, so the " +
+      `capturing visitor's theme would reach everyone. ${THEME_READ_FIX}`,
+    warning: THEME_READ_FIX,
+  },
+};
+
+/** The public reads of the visitor's theme cookie that readGuardedTheme guards. */
 export type ThemeReadSurface = "ctx.theme" | "getRequestContext().theme";
 
 /**
- * Guard for a read of the visitor's theme: the handler and middleware
- * `ctx.theme` (handler-context.ts, middleware.ts) and `getRequestContext().theme`
- * (request-context.ts). The theme is the visitor's theme cookie, so it is an
- * identity read like cookies(): it refuses in the same scopes, in the same
- * order (refusingCacheScope, then tripShellCaptureGuard in context.ts), with
- * the same exemption (a loader body under cache(); at capture there is none).
- * Before #971 each read was a plain cookie read, so a ppr shell, a cache()
- * entry or a "use cache" entry stored the first visitor's theme and served it
- * to every later visitor.
- *
- * A read the guards allow is recorded on the current loader execution, as a
- * cookies() read method records it (#972, recordLoaderIdentityRead).
- *
- * `ctx` is the request context at read time, as cookies() reads it. The
- * router's own payload read (payloadInitialTheme, rsc/full-payload.ts) goes
- * through the unguarded `_readTheme()`.
+ * `ctx`'s theme through guardIdentityRead: the one body of every public theme
+ * read (the handler and middleware `ctx.theme`, handler-context.ts and
+ * middleware.ts, and `getRequestContext().theme`, request-context.ts). The
+ * guard reads the ambient context, as cookies() does, and falls back to
+ * `ctx`; the value is `ctx`'s unguarded `_readTheme()`, which the router's
+ * own payload read (payloadInitialTheme, rsc/full-payload.ts) calls directly.
+ * Undefined without a theme config.
  */
-export function assertThemeReadAllowed(
-  ctx: unknown,
+export function readGuardedTheme(
+  ctx: RequestContext<any> | undefined,
   surface: ThemeReadSurface,
-): void {
-  const scope = refusingCacheScope();
-  if (scope === "use cache") {
-    throw new Error(
-      `${surface} cannot be read inside a "use cache" function. The theme ` +
-        `comes from the visitor's cookie and is not in the cache key, so the ` +
-        `first caller's theme would be served to later callers. Read it ` +
-        `before the cached function and pass it in as an argument.`,
-    );
-  }
-  if (scope === "cache()") {
-    throw new Error(
-      `${surface} cannot be read inside a cache() boundary. The theme comes ` +
-        `from the visitor's cookie, so the first visitor's theme would be ` +
-        `stored in the shared entry and served to everyone. ${THEME_READ_FIX}`,
-    );
-  }
-  if (tripShellCaptureGuard(ctx, surface, THEME_READ_FIX)) {
-    throw new Error(
-      `${surface} cannot be read while capturing a shared shell (ppr shell ` +
-        `capture). The captured shell is served to every visitor of this URL, ` +
-        `so the capturing visitor's theme would reach everyone. ${THEME_READ_FIX}`,
-    );
-  }
-  // An identity read like a cookies() read method: a loader cache() fill with
-  // no key() refuses an execution that made one (#972).
-  recordLoaderIdentityRead(surface, "read");
+): Theme | undefined {
+  if (!ctx?._themeConfig) return undefined;
+  guardIdentityRead(_getRequestContext() ?? ctx, surface, THEME_READ);
+  return ctx._readTheme();
 }
 
 const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
@@ -244,9 +273,8 @@ const HEADERS_READ_PROPS = new Set<string | symbol>([
  */
 export function headers(): ReadonlyHeaders {
   const ctx = getRequestContext();
-  assertNotInsideCacheContext("headers");
-  assertNotInsideShellCapture(ctx, "headers");
-  return new Proxy(ctx.request.headers, {
+  guardIdentityRead(ctx, "headers()", HEADERS_READ);
+  return new Proxy(requestHeaders(ctx.request), {
     get(target, prop, receiver) {
       if (HEADERS_READ_PROPS.has(prop)) recordLoaderIdentityRead("headers()");
       if (typeof prop === "string" && HEADERS_MUTATION_METHODS.has(prop)) {
@@ -285,7 +313,7 @@ export function invalidateClientCache(): void {
     }
     return;
   }
-  assertNotInsideCacheContext("invalidateClientCache");
+  refuseInCacheScope("invalidateClientCache()", COOKIES_READ);
   ctx._rotateStateCookie();
 }
 
@@ -310,33 +338,31 @@ export function keepClientCache(): void {
     }
     return;
   }
-  assertNotInsideCacheContext("keepClientCache");
+  refuseInCacheScope("keepClientCache()", COOKIES_READ);
   ctx._setKeepCacheDirective();
 }
 
 /**
- * Create a CookieStore backed by a RequestContext.
- * @internal Shared between cookies() shorthand and context methods.
+ * Create a CookieStore backed by a RequestContext. Reads go through the
+ * context's unguarded `_readCookie()` / `_readCookies()`: cookies() ran the
+ * guard at its call and records on each read method here.
  */
-function createCookieStore(ctx: {
-  cookie(name: string): string | undefined;
-  cookies(): Record<string, string>;
-  setCookie(name: string, value: string, options?: CookieOptions): void;
-  deleteCookie(
-    name: string,
-    options?: Pick<CookieOptions, "domain" | "path">,
-  ): void;
-}): CookieStore {
+function createCookieStore(
+  ctx: Pick<
+    RequestContext<any>,
+    "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie"
+  >,
+): CookieStore {
   return {
     get(name: string): Cookie | undefined {
       recordLoaderIdentityRead("cookies()");
-      const value = ctx.cookie(name);
+      const value = ctx._readCookie(name);
       return value !== undefined ? { name, value } : undefined;
     },
 
     getAll(name?: string): Cookie[] {
       recordLoaderIdentityRead("cookies()");
-      const all = ctx.cookies();
+      const all = ctx._readCookies();
       if (name !== undefined) {
         const value = all[name];
         return value !== undefined ? [{ name, value }] : [];
@@ -346,7 +372,7 @@ function createCookieStore(ctx: {
 
     has(name: string): boolean {
       recordLoaderIdentityRead("cookies()");
-      return ctx.cookie(name) !== undefined;
+      return ctx._readCookie(name) !== undefined;
     },
 
     set(name: string, value: string, options?: CookieOptions): void {