@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/src/server/context.ts

@@ -27,6 +27,7 @@ export interface PerformanceMetric {
   duration: number; // milliseconds
   startTime: number; // relative to request start
   depth?: number; // nesting level for hierarchical display (0 = top-level)
+  desc?: string; // free-form outcome detail, emitted as Server-Timing desc="..."
 }
 
 /**
@@ -276,6 +277,17 @@ export interface TrackedInclude {
   lazy: boolean;
 }
 
+/**
+ * Cached response-header write scope (issue #713). `kind` selects the error
+ * wording; `routeKey` names the route in the error.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type CachedHeaderScope = {
+  kind: "cache" | "ppr";
+  routeKey?: string;
+};
+
 /**
  * Context stored in AsyncLocalStorage
  */
@@ -316,6 +328,13 @@ interface HelperContext {
   /** True when resolving handlers inside a cache() DSL boundary.
    *  Read by ctx.get() to guard non-cacheable variable reads. */
   insideCacheScope?: boolean;
+  /**
+   * RULE (issue #713): in any cached scenario ONLY MIDDLEWARE writes response
+   * headers. Latched by the segment funnels, consulted by
+   * assertCachedHeaderWriteAllowed(); full doctrine in
+   * docs/design/ppr-shell-resume.md "The header doctrine".
+   */
+  cachedHeaderScope?: CachedHeaderScope;
   /**
    * Include scope string applied to direct-descendant shortCodes.
    *
@@ -483,6 +502,9 @@ export const getContext = (): {
           trackedIncludes: store.trackedIncludes,
           cacheProfiles: store.cacheProfiles,
           includeScope: store.includeScope,
+          // cachedHeaderScope (and insideCacheScope) deliberately NOT copied —
+          // the header guard's middleware exemption depends on the latch dying
+          // with the funnel scope (see assertCachedHeaderWriteAllowed).
         },
         callback,
       );
@@ -795,14 +817,15 @@ const loaderBodyScopeALS: AsyncLocalStorage<{
  */
 export function isInsideCacheScope(): boolean {
   if (RangoContext.getStore()?.insideCacheScope !== true) return false;
-  // Loaders are always fresh — even inside a cache() boundary, the loader
-  // function re-executes on every request. Skip the guard when running
-  // inside a loader.
-  if (loaderScopeALS.getStore()?.active) return false;
-  // Also exempt handler-invoked loaders: their bodies run in a loader-body
-  // scope (not the DSL loader scope above), so request-scoped reads inside any
-  // loader — however invoked — are safe (loaders always re-run fresh).
-  if (loaderBodyScopeALS.getStore()?.active) return false;
+  // Request-scoped READS are exempt in any loader body — DSL loaders re-run on
+  // every request (including cache() HITs via resolveLoadersOnly), and a
+  // handler-invoked loader body, though skipped with its handler on a HIT,
+  // yields a BAKED shared copy in the cached artifact — an accepted
+  // consumption-lane tradeoff (#672/#674). This is deliberately BROADER than
+  // the WRITE guard (assertCachedHeaderWriteAllowed narrows the cache()
+  // exemption to DSL scope, #725): a read bakes-and-accepts, a Set-Cookie/header
+  // write drops-and-throws because it has no baked-copy semantics on a HIT.
+  if (isInsideAnyLoaderScope()) return false;
   return true;
 }
 
@@ -815,6 +838,159 @@ export function isInsideLoaderScope(): boolean {
   return loaderScopeALS.getStore()?.active === true;
 }
 
+/**
+ * Latch the cached header-write scope for the current request. First latch
+ * wins: a ppr route latched at the funnel top is not downgraded by a nested
+ * cache() entry (the document-scoped wording is the more useful one).
+ * Takes scalars so the already-latched path allocates nothing.
+ */
+export function latchCachedHeaderScope(
+  kind: CachedHeaderScope["kind"],
+  routeKey?: string,
+): void {
+  const store = RangoContext.getStore();
+  if (store && !store.cachedHeaderScope) {
+    store.cachedHeaderScope = { kind, routeKey };
+  }
+}
+
+/** True inside ANY loader execution — DSL loader scope or a loader body
+ *  (however invoked). The "loaders always re-run fresh" exemptions key off
+ *  this. */
+function isInsideAnyLoaderScope(): boolean {
+  return (
+    loaderScopeALS.getStore()?.active === true ||
+    loaderBodyScopeALS.getStore()?.active === true
+  );
+}
+
+/**
+ * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
+ * (`false` and undefined mean plain axis 1). Shared by the serve path
+ * (rsc/shell-serve.ts resolvePprConfig) and the header-write latch below so
+ * the two layers can never drift on what counts as a ppr route.
+ */
+export function isPprEntry(entry: EntryData): entry is EntryData & {
+  type: "route";
+  ppr: true | import("../urls/pattern-types.js").PartialPrerenderProps;
+} {
+  return (
+    entry.type === "route" && entry.ppr !== undefined && entry.ppr !== false
+  );
+}
+
+/**
+ * Latch the ppr header-write scope when the entry chain about to resolve is a
+ * `ppr` page route's. Called at the TOP of every segment funnel — unlike
+ * cache() (positional: ancestors before the boundary stay writable), ppr is
+ * document-scoped: the root layout down to the page bakes into the shared
+ * shell, so the whole funnel is cached territory.
+ *
+ * Checks the LEAF entry only: `entries` is the traverseBack chain
+ * [root, ..., manifestEntry], and the serve path reads `ppr` off the same
+ * leaf (rsc-rendering.ts: resolvePprConfig(manifestEntry)) — guard and serve
+ * share the predicate (isPprEntry) AND the input, so they cannot drift.
+ */
+export function latchPprHeaderScopeForEntries(
+  entries: EntryData[],
+  routeKey?: string,
+): void {
+  const store = RangoContext.getStore();
+  if (!store || store.cachedHeaderScope) return;
+  const leaf = entries[entries.length - 1];
+  if (leaf !== undefined && isPprEntry(leaf)) {
+    store.cachedHeaderScope = { kind: "ppr", routeKey };
+  }
+}
+
+/**
+ * Clear the ppr header-write latch for the remainder of this render (issue
+ * #735). Called by ctx.dynamic(): a dynamic() render opts off the SHELL axis
+ * (rsc-rendering.ts skips both the HIT commit and the MISS capture on
+ * `_dynamic`), so it is ALWAYS live — every request re-runs the handler and its
+ * header write lands identically each time. The guard's reason to forbid it
+ * (MISS/HIT divergence) evaporates, so the write is re-permitted.
+ *
+ * ONLY the ppr (shell) axis is dropped — dynamic() does NOT opt off the CACHE
+ * axis. Two cases:
+ * - Pure ppr funnel (no cache() boundary): clear the latch → writes re-permit.
+ * - ppr route nested under a cache() boundary: fresh.ts latches "ppr" at the
+ *   funnel top (first-wins), which MASKS the positional cache() latch, but the
+ *   handler still runs inside the cache scope (`insideCacheScope`). A cache()
+ *   HIT skips that handler, so the write is still non-deterministic — UNMASK to
+ *   "cache" instead of clearing, so the guard keeps throwing (accurate cache()
+ *   wording). This is why the check keys off `insideCacheScope`, not just kind.
+ *
+ * A subsequent cache() entered AFTER dynamic() on a pure-ppr funnel re-latches
+ * "cache" via latchCachedHeaderScope's `!store.cachedHeaderScope` guard (the
+ * field is undefined again once cleared). No-op when there is no funnel store or
+ * no ppr latch (dynamic() from middleware runs outside the funnel Store.run
+ * scope, so nothing is latched — the middleware exemption is unchanged).
+ */
+export function clearPprHeaderScope(): void {
+  const store = RangoContext.getStore();
+  if (store?.cachedHeaderScope?.kind !== "ppr") return;
+  store.cachedHeaderScope = store.insideCacheScope
+    ? { kind: "cache", routeKey: store.cachedHeaderScope.routeKey }
+    : undefined;
+}
+
+/**
+ * RULE (issue #713): in any cached scenario ONLY MIDDLEWARE writes response
+ * headers — handler and loader writes throw while a scope is latched; the one
+ * exemption is DSL (registered) loaders under plain cache(). A handler-invoked
+ * loader body (ctx.use from a handler, never registered with loader()) is
+ * skipped with its handler on a HIT and throws like a handler write (#725).
+ * A ctx.dynamic() render clears the ppr latch (clearPprHeaderScope, #735) so
+ * its always-live handler header writes are re-permitted. Full layer rules and
+ * rationale: docs/design/ppr-shell-resume.md "The header doctrine".
+ */
+export function assertCachedHeaderWriteAllowed(
+  surface: string,
+  surfaceProp?: string | symbol,
+): void {
+  const scope = RangoContext.getStore()?.cachedHeaderScope;
+  if (!scope) return;
+  // Exempt DSL loaders (loaderScopeALS) ONLY. A registered loader re-runs on
+  // every cache HIT (fresh.ts runInsideLoaderScope -> cache-lookup.ts
+  // resolveLoadersOnly), so its header/cookie writes merge into every response
+  // with no MISS/HIT divergence. A handler-invoked loader body has
+  // loaderBodyScopeALS active but loaderScopeALS unset (loader-resolution.ts
+  // derives isDslLoader from isInsideLoaderScope()); on a HIT the handler is
+  // skipped so that loader never re-runs and its write would land only on the
+  // MISS — throw it. isInsideLoaderScope() (not isInsideAnyLoaderScope) is the
+  // discriminator; the DSL scope ALS survives nested ctx.use bodies, so a
+  // handler-invoked loader nested under a DSL loader stays exempt (its DSL
+  // parent re-invokes it on every HIT). This is the exempt fast path, so the
+  // broad predicate for the error label is deferred to the throw path below.
+  if (scope.kind === "cache" && isInsideLoaderScope()) return;
+  // Everything below runs only on the throw path — `surfaceProp` exists so
+  // callers pass constants and the success path allocates nothing (the full
+  // surface, e.g. "ctx.headers.set()", is assembled here). isInsideAnyLoaderScope
+  // (broad) labels a now-throwing handler-invoked loader body "loader".
+  const fullSurface =
+    surfaceProp === undefined ? surface : `${surface}.${String(surfaceProp)}()`;
+  const layer = isInsideAnyLoaderScope() ? "loader" : "handler";
+  const route = scope.routeKey ? ` (route "${scope.routeKey}")` : "";
+  const where =
+    scope.kind === "ppr"
+      ? `on a ppr route${route} — the document shell is cached and replayed`
+      : `inside a cache() boundary${route}`;
+  // ppr loader writes fail by physics (headers flush before loaders settle);
+  // every other throw — a handler, or a handler-invoked loader under cache() —
+  // fails because the handler is skipped on a HIT, so key the reason on the
+  // scope kind, not the layer.
+  const why =
+    scope.kind === "ppr" && layer === "loader"
+      ? "The response headers flush with the shell before loaders settle, so this write is dropped on cache hits."
+      : "On a cache hit the handler is skipped, so this write would silently vanish.";
+  throw new Error(
+    `${fullSurface} cannot be called from a ${layer} ${where}. ${why} ` +
+      "Set response headers in route middleware instead — middleware runs " +
+      "on every request, including cache hits.",
+  );
+}
+
 /**
  * Run `fn` inside a loader scope. While active, cache-scope guards
  * are bypassed because loaders are always fresh (never cached) and