@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/src/server/request-context.ts

@@ -50,6 +50,7 @@ import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
 import type { TransitionWhenFn } from "../types/segments.js";
 import type { ResolvedTracing } from "../router/tracing.js";
+import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import {
   THEME_COOKIE,
   isValidTheme,
@@ -57,7 +58,11 @@ import {
 } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
-import { isInsideCacheScope } from "./context.js";
+import {
+  assertCachedHeaderWriteAllowed,
+  clearPprHeaderScope,
+  isInsideCacheScope,
+} from "./context.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -71,6 +76,18 @@ import { parseSearchParams } from "../search-params.js";
 import { invariant } from "../errors.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
+export interface RenderForegroundCursor {
+  mode: RenderMode;
+  phase: RenderPhase;
+  state: "paused" | "running";
+  completed: number;
+  total: number;
+  pipelineStartedAt: number;
+  phaseStartedAt?: number;
+  routeKey?: string;
+  actionId?: string;
+}
+
 /**
  * Unified request context available via getRequestContext()
  *
@@ -105,6 +122,27 @@ export interface RequestContext<
   /** @internal Stub response for collecting headers/cookies. Use ctx.headers or ctx.header() instead. */
   readonly res: Response;
 
+  /**
+   * True for build-time render/capture requests. Live requests use false.
+   * Build-time shell capture sets this while replaying middleware so apps can
+   * skip side-effectful runtime work.
+   */
+  readonly build: boolean;
+
+  /**
+   * Opt this request out of PPR shell serving/capture.
+   * Runtime middleware can call this before the PPR commit point; handlers can
+   * call it on a MISS to prevent the follow-up capture.
+   *
+   * Scope: the PPR SHELL axis only. It does NOT disable prerender B-segment
+   * (Prerender/Static) serving, and it is inert in the prerender-collect /
+   * static-render contexts (no live shell decision to influence there).
+   */
+  dynamic(): void;
+
+  /** @internal Request-local PPR opt-out marker set by ctx.dynamic(). */
+  _dynamic?: boolean;
+
   /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
   cookie(name: string): string | undefined;
   /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
@@ -203,12 +241,77 @@ export interface RequestContext<
   /**
    * @internal Loader-family snapshot seed for a shell HIT's tail render:
    * segment-key -> the capture's elided container (already Flight-deserialized
-   * by serveShellHit). resolveLoaderData overlays it onto the fresh run's
-   * container (recorded paths pinned, hole-marker paths keep the fresh nested
-   * promises) so the payload's baked bytes match the frozen prelude. Own
-   * property of the HIT tail's derived context only.
+   * by serveShellHit) plus its capture-computed hole bit. resolveLoaderData
+   * overlays it onto the fresh run's container (recorded paths pinned,
+   * hole-marker paths keep the fresh nested promises) so the payload's baked
+   * bytes match the frozen prelude; a hole-free entry resolves pin-first
+   * without gating on the fresh run. Own property of the HIT tail's derived
+   * context only.
+   */
+  _shellLoaderSeed?: Map<
+    string,
+    import("../cache/shell-snapshot.js").ShellLoaderSeedEntry
+  >;
+
+  /**
+   * @internal Shell fast-path marker: makes the NEXT full match treat the whole
+   * matched route as an implicit doc-level cache() boundary (see
+   * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
+   * (a) the capture's derived context — with a record-only store so the
+   * capture's cacheRoute write lands in the snapshot, never the real store —
+   * and (b) a HIT tail's seeded context when the entry is eligible
+   * (!handlerLiveHoles), where the SeededShellStore serves the recorded doc
+   * entry and the match skips handler execution entirely. Routes with their
+   * own cache() config (including cache(false)) are never overridden: the
+   * marker only applies when the route tree derived NO cache scope.
+   */
+  _shellImplicitCache?: {
+    ttl?: number;
+    swr?: number;
+    store?: SegmentCacheStore;
+  };
+
+  /**
+   * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
+   * render emit stored segment fragments VERBATIM into the payload
+   * (segment-codec fragmentSegments) instead of deserialize -> re-serialize
+   * per request; the payload consumers (SSR resume + browser hydration)
+   * expand them (segment-fragments.ts, issue #700). Own property of
+   * serveShellHit's derived tail context ONLY — it must never be visible to a
+   * capture render: the capture SSR-prerenders the payload AND serializes
+   * segments into records (cacheRoute), and an envelope reaching
+   * serializeSegments would store a double-encoded fragment.
+   */
+  _shellFragmentPayload?: boolean;
+
+  /**
+   * @internal Handler-layer liveness observed DURING a shell capture, from
+   * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
+   * when a push made OUTSIDE a DSL loader scope carries a nested thenable
+   * (masked to a never-filling hole); (b) still-pending top-level handler
+   * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
+   * executing during the capture (loader-resolution.ts — its consumption-lane
+   * value would freeze on a handler-free HIT). captureAndStoreShell folds it
+   * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
+   * property of the capture's derived context only.
+   */
+  _shellCaptureHandleLiveness?: {
+    holes: boolean;
+    pendingPushes: number;
+    handlerInvokedLoader: boolean;
+  };
+
+  /**
+   * @internal Handle values pushed from a DSL loader scope DURING a shell
+   * capture (identity set; populated by the capture push wrapper in
+   * shell-capture.ts). cacheRoute threads it into captureHandles so those
+   * values stay out of cache-write handle records — loaders re-run fresh on
+   * every HIT, so replaying their captured (masked) values would duplicate
+   * the fresh push and stall the Flight handle encode. Own property of the
+   * capture's derived context only; render-time handle consumers are
+   * unaffected (the exclusion applies only at the captureHandles call site).
    */
-  _shellLoaderSeed?: Map<string, unknown>;
+  _shellCaptureLoaderHandleValues?: WeakSet<object>;
 
   /**
    * @internal Set (to the offending fn name) by the cookies()/headers()
@@ -478,6 +581,16 @@ export interface RequestContext<
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
 
+  /**
+   * @internal Foreground response-construction cursor. It reports only the
+   * generator driver's current Flight/HTML/response operation; concurrent
+   * loaders and post-commit stream work have separate lifetimes.
+   */
+  _renderForeground?: RenderForegroundCursor;
+
+  /** @internal Keep the render cursor active for timeout support. */
+  _renderDiagnosticsEnabled?: boolean;
+
   /**
    * @internal True request entry timestamp (performance.now() at handler entry).
    * Set once at request-context creation (rsc/handler.ts) so a metrics store
@@ -528,6 +641,7 @@ export type PublicRequestContext<
   | "_transitionWhen"
   | "_cacheStore"
   | "_shellCaptureRun"
+  | "_shellFragmentPayload"
   | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
@@ -556,6 +670,8 @@ export type PublicRequestContext<
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_renderForeground"
+  | "_renderDiagnosticsEnabled"
   | "_handlerStart"
   | "_basename"
   | "_setStatus"
@@ -564,6 +680,7 @@ export type PublicRequestContext<
   | "_variables"
   | "_classifiedRoute"
   | "_cacheSignal"
+  | "_dynamic"
   | "res"
 >;
 
@@ -711,6 +828,8 @@ export interface CreateRequestContextOptions<TEnv> {
   >;
   /** Optional Cloudflare execution context for waitUntil support */
   executionContext?: ExecutionContext;
+  /** Build-time render/capture request marker. Defaults to false. */
+  build?: boolean;
   /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
   themeConfig?: ResolvedThemeConfig | null;
   /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
@@ -740,6 +859,7 @@ export function createRequestContext<TEnv>(
     explicitTaggedStores,
     cacheProfiles,
     executionContext,
+    build = false,
     themeConfig,
     stateCookieName,
     version: stateVersion,
@@ -756,6 +876,50 @@ export function createRequestContext<TEnv>(
       })
     : new Response(null, { status: 200 });
 
+  // The #713 choke point: `rawStubHeaders` is the stub's REAL Headers; the
+  // proxy below is the only view reachable from consumer code, and its
+  // mutating methods consult the cached-scope guard first. shadowStubHeaders
+  // shadows `headers` on the stub Response INSTANCE (a real Response, not a
+  // facade — safe to hand to the platform), so every surface that ends in a
+  // stub-header mutation — ctx.header/setCookie/deleteCookie, ctx.setTheme,
+  // the handler ctx.headers proxy, and raw `ctx.res.headers.set(...)` — is
+  // guarded at the mutation itself, not per enumerated wrapper. Guard-exempt
+  // internal writers (_rotateStateCookie, _setKeepCacheDirective — serve
+  // machinery, documented callable from loaders/during capture) write to
+  // rawStubHeaders directly. The serve/commit path's stub reads and its
+  // Set-Cookie drain (rsc/helpers.ts) run outside any latched funnel scope,
+  // where assertCachedHeaderWriteAllowed is a no-op.
+  let rawStubHeaders = stubResponse.headers;
+  const guardedStubHeaders: Headers = new Proxy(new Headers(), {
+    get(_target, prop) {
+      const raw = rawStubHeaders;
+      const value = Reflect.get(raw, prop) as unknown;
+      if (typeof value !== "function") return value;
+      if (prop === "set" || prop === "append" || prop === "delete") {
+        return (...args: unknown[]) => {
+          assertCachedHeaderWriteAllowed("response headers", prop);
+          return (value as (...a: unknown[]) => unknown).apply(raw, args);
+        };
+      }
+      return (value as (...a: unknown[]) => unknown).bind(raw);
+    },
+  });
+  const shadowStubHeaders = (res: Response): void => {
+    Object.defineProperty(res, "headers", {
+      value: guardedStubHeaders,
+      enumerable: true,
+      configurable: true,
+    });
+  };
+  shadowStubHeaders(stubResponse);
+  // Rebuild the stub with a new status, re-shadowing the fresh instance
+  // (the Response constructor copies rawStubHeaders into new raw Headers).
+  const replaceStubStatus = (status: number): void => {
+    stubResponse = new Response(null, { status, headers: rawStubHeaders });
+    rawStubHeaders = stubResponse.headers;
+    shadowStubHeaders(stubResponse);
+  };
+
   const handleStore = createHandleStore();
   const loaderPromises = new Map<string, Promise<any>>();
 
@@ -777,14 +941,12 @@ export function createRequestContext<TEnv>(
     responseCookieCache = null;
   };
 
-  function assertNotInsideCacheScopeALS(methodName: string): void {
-    if (isInsideCacheScope()) {
-      throw new Error(
-        `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
-          `On cache hit the handler is skipped, so this side effect would be lost. ` +
-          `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
-      );
-    }
+  // Guard for the two response-write surfaces that are NOT Headers mutations
+  // (setStatus rebuilds the stub Response, onResponse registers a callback) —
+  // these can't ride the guarded-headers choke point above, so they stay
+  // enumerated. Same unified #713 guard, same message family.
+  function assertResponseWriteAllowed(methodName: string): void {
+    assertCachedHeaderWriteAllowed("ctx", methodName);
   }
 
   // Response stub Set-Cookie wins, then original header (source of truth for mutations).
@@ -845,6 +1007,16 @@ export function createRequestContext<TEnv>(
     pathname: url.pathname,
     searchParams: cleanUrl.searchParams,
     _variables: variables,
+    build,
+    dynamic(): void {
+      ctx._dynamic = true;
+      // A dynamic() render is always live (never a shell HIT), so its handler
+      // header writes are deterministic — clear the ppr latch to re-permit them
+      // (#735). No-op from middleware (outside the funnel scope) or on non-ppr
+      // routes; cache() latches are left alone.
+      clearPprHeaderScope();
+    },
+    _dynamic: false,
     get: ((keyOrVar: any) => {
       if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
         throw new Error(
@@ -895,7 +1067,6 @@ export function createRequestContext<TEnv>(
 
     setCookie(name: string, value: string, options?: CookieOptions): void {
       assertNotInsideCacheExec(ctx, "setCookie");
-      assertNotInsideCacheScopeALS("setCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, value, options),
@@ -908,7 +1079,6 @@ export function createRequestContext<TEnv>(
       options?: Pick<CookieOptions, "domain" | "path">,
     ): void {
       assertNotInsideCacheExec(ctx, "deleteCookie");
-      assertNotInsideCacheScopeALS("deleteCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, "", { ...options, maxAge: 0 }),
@@ -918,7 +1088,6 @@ export function createRequestContext<TEnv>(
 
     header(name: string, value: string): void {
       assertNotInsideCacheExec(ctx, "header");
-      assertNotInsideCacheScopeALS("header");
       stubResponse.headers.set(name, value);
     },
 
@@ -947,7 +1116,9 @@ export function createRequestContext<TEnv>(
         (request.headers.get("x-rango-state") || null) ??
         getRawCookieValue(cookieHeader, stateCookieName);
       const value = mintStateValue(stateVersion ?? "0", prevRaw);
-      stubResponse.headers.append(
+      // rawStubHeaders: guard-exempt internal writer — invalidateClientCache()
+      // is documented callable from loaders and during shell capture.
+      rawStubHeaders.append(
         "Set-Cookie",
         serializeStateCookie(stateCookieName, value, url.protocol === "https:"),
       );
@@ -956,25 +1127,20 @@ export function createRequestContext<TEnv>(
 
     // Set the keepClientCache() directive header. The action bridge reads it on
     // the response and suppresses its automatic invalidation. `.set` makes this
-    // idempotent (one header regardless of call count).
+    // idempotent (one header regardless of call count). rawStubHeaders:
+    // guard-exempt internal writer.
     _setKeepCacheDirective(): void {
-      stubResponse.headers.set(KEEP_CACHE_HEADER, "1");
+      rawStubHeaders.set(KEEP_CACHE_HEADER, "1");
     },
 
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
-      assertNotInsideCacheScopeALS("setStatus");
-      stubResponse = new Response(null, {
-        status,
-        headers: stubResponse.headers,
-      });
+      assertResponseWriteAllowed("setStatus");
+      replaceStubStatus(status);
     },
 
     _setStatus(status: number): void {
-      stubResponse = new Response(null, {
-        status,
-        headers: stubResponse.headers,
-      });
+      replaceStubStatus(status);
     },
 
     use: null as any,
@@ -989,6 +1155,7 @@ export function createRequestContext<TEnv>(
     _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {
+      if (ctx.build) return;
       // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
       // non-async callback becomes a rejected promise handed to the host's
       // waitUntil (logged as a background failure), instead of escaping into
@@ -1023,7 +1190,7 @@ export function createRequestContext<TEnv>(
 
     onResponse(callback: (response: Response) => Response): void {
       assertNotInsideCacheExec(ctx, "onResponse");
-      assertNotInsideCacheScopeALS("onResponse");
+      assertResponseWriteAllowed("onResponse");
       this._onResponseCallbacks.push(callback);
     },
 
@@ -1049,6 +1216,8 @@ export function createRequestContext<TEnv>(
 
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
+    _renderForeground: undefined,
+    _renderDiagnosticsEnabled: undefined,
     _handlerStart: undefined,
 
     _renderBarrier: null as any,
@@ -1058,10 +1227,56 @@ export function createRequestContext<TEnv>(
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
-  // Lazy allocation: only create Promise when a loader calls rendered().
+  wireRenderBarrier(ctx, handleStore);
+
+  ctx.use = createUseFunction({
+    handleStore,
+    loaderPromises,
+    getContext: () => ctx,
+  });
+
+  (ctx as any)[NOCACHE_SYMBOL] = true;
+  return ctx;
+}
+
+/**
+ * Wire a fresh render barrier onto `ctx`, closure-bound to THIS ctx and THIS
+ * handle store. Called by createRequestContext for every fresh context, and by
+ * deriveShellCaptureContext (rsc/shell-capture.ts) for the PPR capture's
+ * derived context.
+ *
+ * The derived-context call is load-bearing (issue #684, plan 009): the capture
+ * context is `Object.create(reqCtx)`, so without its own wiring every
+ * `_renderBarrier*` read fell through the prototype to the FOREGROUND
+ * request's barrier — whose getter and resolver are closure-bound to the
+ * foreground ctx and its handle store, and whose resolver no-ops once
+ * resolved. A bake-lane loader's `await ctx.rendered()` during capture then
+ * resolved instantly against the foreground's barrier and `ctx.use(handle)`
+ * read the foreground's handle snapshot; the capture's fresh `_handleStore`
+ * was invisible, so foreground per-request handle data could bake into the
+ * shared shell.
+ */
+export function wireRenderBarrier(
+  ctx: RequestContext<any, any>,
+  handleStore: HandleStore,
+): void {
+  // Reset the whole barrier family as OWN properties. No-op for a fresh
+  // context; for the derived capture context this shadows the foreground's
+  // resolved state so the capture runs its own barrier lifecycle. In
+  // particular _treeHasStreaming must be recomputed for the CAPTURE's tree
+  // (cache-lookup/segment-resolution only set it when undefined): an
+  // inherited `true` made a capture-lane rendered() seal the capture's fresh
+  // store at loader start and pair it with the foreground's segment order.
+  ctx._renderBarrierSegmentOrder = undefined;
+  ctx._renderBarrierWaiters = undefined;
+  ctx._renderBarrierHandleSnapshot = undefined;
+  ctx._renderBarrierGuardClosed = undefined;
+  ctx._handlerLoaderDeps = undefined;
+  ctx._treeHasStreaming = undefined;
+
+  // Lazy allocation: only create the Promise when a loader calls rendered().
   let barrierResolved = false;
   let resolveBarrier: (() => void) | undefined;
-  ctx._renderBarrier = null as any;
   ctx._resolveRenderBarrier = (
     segments: Array<{ type: string; id: string }>,
   ) => {
@@ -1089,6 +1304,9 @@ export function createRequestContext<TEnv>(
     }
     if (resolveBarrier) resolveBarrier();
   };
+  // defineProperty, not assignment: on a derived context the prototype's
+  // _renderBarrier may already be a non-writable data property (the getter
+  // pins it after first access), which would reject a plain assignment.
   Object.defineProperty(ctx, "_renderBarrier", {
     get() {
       const p = barrierResolved
@@ -1105,15 +1323,6 @@ export function createRequestContext<TEnv>(
     },
     configurable: true,
   });
-
-  ctx.use = createUseFunction({
-    handleStore,
-    loaderPromises,
-    getContext: () => ctx,
-  });
-
-  (ctx as any)[NOCACHE_SYMBOL] = true;
-  return ctx;
 }
 
 // Capture the Max-Age value so it can be parsed numerically. A leading zero
@@ -1159,6 +1368,21 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
 // dispatcher) can share it without pulling this module's request-context graph.
 export { parseCookiesFromHeader };
 
+/** Reject CR/LF/;/,/whitespace/control so raw attribute interpolation cannot inject. */
+function assertSafeCookieAttribute(
+  value: string,
+  label: "domain" | "path",
+): void {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f || value[i] === ";" || value[i] === ",") {
+      throw new Error(
+        label === "domain" ? "invalid cookie domain" : "invalid cookie path",
+      );
+    }
+  }
+}
+
 export function serializeCookieValue(
   name: string,
   value: string,
@@ -1166,13 +1390,41 @@ export function serializeCookieValue(
 ): string {
   let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
 
-  if (options.domain) cookie += `; Domain=${options.domain}`;
-  if (options.path) cookie += `; Path=${options.path}`;
-  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
+  if (options.domain) {
+    assertSafeCookieAttribute(options.domain, "domain");
+    cookie += `; Domain=${options.domain}`;
+  }
+  if (options.path) {
+    if (!options.path.startsWith("/")) {
+      throw new Error("invalid cookie path");
+    }
+    assertSafeCookieAttribute(options.path, "path");
+    cookie += `; Path=${options.path}`;
+  }
+  if (options.maxAge !== undefined) {
+    // Safe integer: Number.isInteger(1e21) is true but stringifies as "1e+21",
+    // which is invalid Max-Age wire syntax. Number.isSafeInteger rejects that.
+    if (
+      typeof options.maxAge !== "number" ||
+      !Number.isSafeInteger(options.maxAge)
+    ) {
+      throw new Error("invalid cookie maxAge");
+    }
+    cookie += `; Max-Age=${options.maxAge}`;
+  }
   if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
   if (options.httpOnly) cookie += "; HttpOnly";
   if (options.secure) cookie += "; Secure";
-  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
+  if (options.sameSite) {
+    if (
+      options.sameSite !== "strict" &&
+      options.sameSite !== "lax" &&
+      options.sameSite !== "none"
+    ) {
+      throw new Error("invalid cookie sameSite");
+    }
+    cookie += `; SameSite=${options.sameSite}`;
+  }
 
   return cookie;
 }