@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/router/handler-context.ts

@@ -8,10 +8,26 @@ import type { HandlerContext, InternalHandlerContext } from "../types";
 import { _getRequestContext } from "../server/request-context.js";
 import { getSearchSchema, isRouteRootScoped } from "../route-map-builder.js";
 import { parseSearchParams, serializeSearchParams } from "../search-params.js";
-import { contextGet, contextSet } from "../context-var.js";
+import {
+  contextGet,
+  contextSet,
+  isNonCacheable,
+  type ContextSetOptions,
+} from "../context-var.js";
+import {
+  assertCachedHeaderWriteAllowed,
+  isInsideCacheScope,
+} from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
+import { substitutePatternParams } from "./substitute-pattern-params.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
+
+// Mutating Headers methods guarded so they throw inside "use cache" / cache()
+// scope. Module-level constant (read-only, .has() lookups) so it is allocated
+// once at module load instead of per createHandlerContext (per-request) call.
+const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
 
 /**
  * Strip internal _rsc* query params from a URL.
@@ -80,7 +96,7 @@ function resolveRouteName(
     // Resolution order: explicit param > scope registry > heuristic.
     const isRootScoped =
       rootScoped ??
-      isRouteRootScoped(currentRoutePrefix) ??
+      isRouteRootScoped(currentRoutePrefix, _getRequestContext()?._routerId) ??
       !currentRoutePrefix.includes(".");
     if (isRootScoped) {
       if (routeMap[lookupName] !== undefined) {
@@ -108,9 +124,9 @@ function createPrerenderPassthroughFn(
     }
     if (!isPassthroughRoute) {
       throw new Error(
-        "ctx.passthrough() is only available on routes declared with " +
-          "{ passthrough: true }. Remove the passthrough() call or add " +
-          "{ passthrough: true } to the Prerender options.",
+        "ctx.passthrough() is only available on routes wrapped with " +
+          "Passthrough(). Remove the passthrough() call or wrap the " +
+          "Prerender definition with Passthrough(prerenderDef, liveHandler).",
       );
     }
     return PRERENDER_PASSTHROUGH;
@@ -152,26 +168,14 @@ export function createReverseFunction(
       );
     }
 
-    let result = pattern;
-
     // Merge current request params as defaults, explicit params override
     const effectiveParams = currentParams
       ? { ...currentParams, ...hrefParams }
       : hrefParams;
 
-    // Substitute params (strip constraint and optional syntax: :param(a|b)? -> value)
-    if (effectiveParams) {
-      result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\??/g,
-        (_, key) => {
-          const value = effectiveParams[key];
-          if (value === undefined) {
-            throw new Error(`Missing param "${key}" for route "${name}"`);
-          }
-          return encodeURIComponent(value);
-        },
-      );
-    }
+    let result = effectiveParams
+      ? substitutePatternParams(pattern, effectiveParams, name)
+      : pattern;
 
     // Append search params as query string
     if (search) {
@@ -201,10 +205,12 @@ export function createHandlerContext<TEnv>(
   // Get variables from request context - this is the unified context
   // shared between middleware and route handlers
   const requestContext = _getRequestContext();
-  const variables: any = requestContext?.var ?? {};
+  const variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
-  const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
+  const searchSchema = routeName
+    ? getSearchSchema(routeName, requestContext?._routerId)
+    : undefined;
   const resolvedSearchParams = searchSchema
     ? parseSearchParams(searchParams, searchSchema)
     : searchParams;
@@ -213,10 +219,12 @@ export function createHandlerContext<TEnv>(
   const stubResponse =
     requestContext?.res ?? new Response(null, { status: 200 });
 
-  // Guard mutating Headers methods so they throw inside "use cache" functions.
+  // Guard mutating Headers methods so they throw inside "use cache" scope or
+  // cached header-write territory (cache() boundary / ppr route render —
+  // assertCachedHeaderWriteAllowed, the unified #713 guard).
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
-  const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
+  // MUTATING_HEADERS_METHODS is hoisted to module scope (constant, read-only).
   let ctx: InternalHandlerContext<any, TEnv>;
   const guardedHeaders = new Proxy(stubResponse.headers, {
     get(target, prop, receiver) {
@@ -225,6 +233,7 @@ export function createHandlerContext<TEnv>(
         if (MUTATING_HEADERS_METHODS.has(prop as string)) {
           return (...args: any[]) => {
             assertNotInsideCacheExec(ctx, "headers");
+            assertCachedHeaderWriteAllowed("ctx.headers", prop);
             return value.apply(target, args);
           };
         }
@@ -236,22 +245,40 @@ export function createHandlerContext<TEnv>(
 
   ctx = {
     params,
-    build: false,
+    build: requestContext?.build ?? false,
+    dynamic(): void {
+      requestContext?.dynamic();
+    },
+    dev: false,
     request,
     searchParams,
     search: searchSchema ? resolvedSearchParams : {},
     pathname,
     url,
-    originalUrl: new URL(request.url),
+    originalUrl: requestContext?.originalUrl ?? new URL(request.url),
     env: bindings,
-    var: variables,
-    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as HandlerContext<
-      any,
-      TEnv
-    >["get"],
-    set: ((keyOrVar: any, value: any) => {
+    waitUntil: requestContext
+      ? requestContext.waitUntil.bind(requestContext)
+      : fireAndForgetWaitUntil,
+    executionContext: requestContext?.executionContext,
+    _variables: variables,
+    get: ((keyOrVar: any) => {
+      // Read-time guard: non-cacheable var inside cache() → throw.
+      // Works for both ContextVar tokens and string keys.
+      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
+        throw new Error(
+          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+            `The variable was created with { cache: false } or set with { cache: false }, ` +
+            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+        );
+      }
+      return contextGet(variables, keyOrVar);
+    }) as HandlerContext<any, TEnv>["get"],
+    set: ((keyOrVar: any, value: any, options?: ContextSetOptions) => {
       assertNotInsideCacheExec(ctx, "set");
-      contextSet(variables, keyOrVar, value);
+      // Write is dumb: store value + non-cacheable metadata.
+      // Enforcement happens at read time via ctx.get().
+      contextSet(variables, keyOrVar, value, options);
     }) as HandlerContext<any, TEnv>["set"],
     res: stubResponse, // Stub response for setting headers
     headers: guardedHeaders, // Guarded shorthand for res.headers
@@ -281,7 +308,9 @@ export function createHandlerContext<TEnv>(
       routeMap,
       routeName,
       params,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, requestContext?._routerId)
+        : undefined,
     ),
     passthrough: createPrerenderPassthroughFn(false, isPassthroughRoute),
     _responseType: responseType,
@@ -297,7 +326,7 @@ export function createHandlerContext<TEnv>(
  *
  * Returns an InternalHandlerContext where params, pathname, url, searchParams,
  * search, reverse, and use(handle) work. Request-time properties
- * (request, env, headers, cookies, var, get, set, res) throw with a clear error.
+ * (request, env, headers, cookies, get, set, res) throw with a clear error.
  */
 export function createPrerenderContext<TEnv>(
   params: Record<string, string>,
@@ -306,6 +335,8 @@ export function createPrerenderContext<TEnv>(
   routeName?: string,
   buildVars?: Record<string, any>,
   isPassthroughRoute?: boolean,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const syntheticUrl = new URL(`http://prerender${pathname}`);
   const variables = buildVars ?? {};
@@ -320,6 +351,10 @@ export function createPrerenderContext<TEnv>(
   return {
     params,
     build: true,
+    // Inert here: prerender/static contexts have no live PPR-shell decision to
+    // gate. dynamic() only reaches the shell axis on a live request or capture.
+    dynamic: () => {},
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -329,11 +364,19 @@ export function createPrerenderContext<TEnv>(
     url: syntheticUrl,
     originalUrl: syntheticUrl,
     get env(): TEnv {
-      return throwUnavailable("env");
-    },
-    get var(): any {
-      return throwUnavailable("var");
+      if (buildEnv !== undefined) return buildEnv;
+      throw new Error(
+        "ctx.env is not available during pre-rendering. " +
+          "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      );
     },
+    // Build-time prerender has no live request. waitUntil is a true no-op
+    // (running fn() here would fire side effects during build, which is
+    // incorrect — these are meant to outlive the live response).
+    // executionContext is absent for the same reason.
+    waitUntil: () => {},
+    executionContext: undefined,
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);
@@ -360,7 +403,9 @@ export function createPrerenderContext<TEnv>(
       routeMap,
       routeName,
       params,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, _getRequestContext()?._routerId)
+        : undefined,
     ),
     passthrough: createPrerenderPassthroughFn(
       true,
@@ -379,6 +424,8 @@ export function createPrerenderContext<TEnv>(
 export function createStaticContext<TEnv>(
   routeMap: Record<string, string>,
   routeName?: string,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const variables: Record<string, any> = {};
 
@@ -394,6 +441,10 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("params");
     },
     build: true,
+    // Inert here: prerender/static contexts have no live PPR-shell decision to
+    // gate. dynamic() only reaches the shell axis on a live request or capture.
+    dynamic: () => {},
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -413,11 +464,18 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("originalUrl");
     },
     get env(): TEnv {
-      return throwUnavailable("env");
-    },
-    get var(): any {
-      return throwUnavailable("var");
+      if (buildEnv !== undefined) return buildEnv;
+      throw new Error(
+        "ctx.env is not available in Static() handlers. " +
+          "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      );
     },
+    // Static() handlers have no live request. waitUntil is a true no-op
+    // (running fn() here would fire side effects during build, which is
+    // incorrect). executionContext is absent for the same reason.
+    waitUntil: () => {},
+    executionContext: undefined,
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);
@@ -444,7 +502,9 @@ export function createStaticContext<TEnv>(
       routeMap,
       routeName,
       undefined,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, _getRequestContext()?._routerId)
+        : undefined,
     ),
     _routeName: routeName,
   } as InternalHandlerContext<any, TEnv>;