@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/router/handler-context.ts

@@ -5,60 +5,188 @@
  */
 
 import type { HandlerContext, InternalHandlerContext } from "../types";
-import type { HandleStore } from "../server/handle-store.js";
-import { getRequestContext } from "../server/request-context.js";
-import { getSearchSchema } from "../route-map-builder.js";
+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,
+  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.
+ * Returns a new URL with only user-facing params.
+ */
+export function stripInternalParams(url: URL): URL {
+  const clean = new URL(url);
+  for (const key of [...clean.searchParams.keys()]) {
+    if (key.startsWith("_rsc")) {
+      clean.searchParams.delete(key);
+    }
+  }
+  return clean;
+}
 
 /**
  * Resolve route name with namespace prefix support.
- * Supports local names, absolute names (dot notation), and path-based URLs.
+ * Supports local names (dot-prefixed) and absolute names (global lookup).
+ *
+ * @param rootScoped - Explicit override for root-scope check. When undefined,
+ *   falls back to the global scope registry, then to a heuristic.
  */
 function resolveRouteName(
   name: string,
   routeMap: Record<string, string>,
-  currentRoutePrefix?: string
+  currentRoutePrefix?: string,
+  rootScoped?: boolean,
 ): string | undefined {
-  // 1. Path-based - starts with /
-  if (name.startsWith("/")) {
-    return name;
-  }
-
-  // 2. Absolute name - already has a dot (e.g., "shop.cart")
-  if (name.includes(".")) {
-    return routeMap[name];
-  }
+  // 1. Dot-prefixed (".article", ".author.posts") — local resolution only.
+  //    Resolves within the current include() scope using the mount prefix.
+  if (name.startsWith(".")) {
+    const lookupName = name.slice(1);
+    if (!currentRoutePrefix) return undefined;
 
-  // 3. Local name - try with current prefix first, then fall back to direct lookup
-  if (currentRoutePrefix) {
-    // Extract the prefix from current route name
-    // e.g., "blog.posts.detail" → prefix is "blog.posts"
+    // Extract the include prefix from current route name
+    // e.g., "magazine.author" -> prefix is "magazine"
     const lastDot = currentRoutePrefix.lastIndexOf(".");
-    const prefix = lastDot > 0 ? currentRoutePrefix.substring(0, lastDot) : currentRoutePrefix;
+    const prefix =
+      lastDot > 0
+        ? currentRoutePrefix.substring(0, lastDot)
+        : currentRoutePrefix;
 
-    // Try prefixed name
-    const prefixedName = `${prefix}.${name}`;
+    // Try prefixed name at current level
+    const prefixedName = `${prefix}.${lookupName}`;
     if (routeMap[prefixedName] !== undefined) {
       return routeMap[prefixedName];
     }
 
-    // If current route is a nested include, try parent prefixes
-    // e.g., for "blog.posts.detail", try "blog.posts.index", then "blog.index"
+    // Walk up parent prefixes for nested includes
     let currentPrefix = prefix;
     while (currentPrefix.includes(".")) {
       const parentDot = currentPrefix.lastIndexOf(".");
       currentPrefix = currentPrefix.substring(0, parentDot);
-      const parentPrefixedName = `${currentPrefix}.${name}`;
+      const parentPrefixedName = `${currentPrefix}.${lookupName}`;
       if (routeMap[parentPrefixedName] !== undefined) {
         return routeMap[parentPrefixedName];
       }
     }
+
+    // Fallback: try bare name at root scope only.
+    // Routes inside { name: "" } mounts are at root scope — their dot-local
+    // names can fall back to bare names (e.g., "sub.detail" reaching "flatIndex").
+    // Routes inside named mounts (e.g., { name: "magazine" }) are NOT at root
+    // scope — dot-local must not leak into unrelated global names.
+    //
+    // Resolution order: explicit param > scope registry > heuristic.
+    const isRootScoped =
+      rootScoped ??
+      isRouteRootScoped(currentRoutePrefix) ??
+      !currentRoutePrefix.includes(".");
+    if (isRootScoped) {
+      if (routeMap[lookupName] !== undefined) {
+        return routeMap[lookupName];
+      }
+    }
+
+    return undefined;
   }
 
-  // Fall back to direct lookup (route without prefix)
+  // 2. Unprefixed ("magazine.index", "blog.post") — global resolution only.
+  //    Direct lookup in the full named-routes map.
   return routeMap[name];
 }
 
+function createPrerenderPassthroughFn(
+  build: boolean,
+  isPassthroughRoute: boolean,
+): () => typeof PRERENDER_PASSTHROUGH {
+  return () => {
+    if (!build) {
+      throw new Error(
+        "ctx.passthrough() can only be called during build-time prerendering.",
+      );
+    }
+    if (!isPassthroughRoute) {
+      throw new Error(
+        "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;
+  };
+}
+
+/**
+ * Create a reverse function for URL generation from route names.
+ * Used by both HandlerContext and MiddlewareContext.
+ *
+ * When currentParams is provided, those params are used as defaults for URL
+ * generation. This enables auto-filling mount params from include() prefixes:
+ * inner handlers can call ctx.reverse(".sibling") without explicitly passing
+ * params that are already known from the current URL match.
+ * Explicitly passed hrefParams take priority over currentParams.
+ */
+export function createReverseFunction(
+  routeMap: Record<string, string>,
+  currentRoutePrefix?: string,
+  currentParams?: Record<string, string>,
+  rootScoped?: boolean,
+): (
+  name: string,
+  hrefParams?: Record<string, string>,
+  search?: Record<string, unknown>,
+) => string {
+  return (name, hrefParams, search) => {
+    // Resolve route name with namespace support
+    const pattern = resolveRouteName(
+      name,
+      routeMap,
+      currentRoutePrefix,
+      rootScoped,
+    );
+
+    if (pattern === undefined) {
+      throw new Error(
+        `Unknown route: "${name}"${currentRoutePrefix ? ` (current route: ${currentRoutePrefix})` : ""}`,
+      );
+    }
+
+    // Merge current request params as defaults, explicit params override
+    const effectiveParams = currentParams
+      ? { ...currentParams, ...hrefParams }
+      : hrefParams;
+
+    let result = effectiveParams
+      ? substitutePatternParams(pattern, effectiveParams, name)
+      : pattern;
+
+    // Append search params as query string
+    if (search) {
+      const qs = serializeSearchParams(search);
+      if (qs) result += `?${qs}`;
+    }
+
+    return result;
+  };
+}
+
 /**
  * Create HandlerContext with typed env/var/get/set
  */
@@ -68,55 +196,90 @@ export function createHandlerContext<TEnv>(
   searchParams: URLSearchParams,
   pathname: string,
   url: URL,
-  bindings: any = {},
+  bindings: TEnv = {} as TEnv,
   routeMap: Record<string, string> = {},
-  routeName?: string
+  routeName?: string,
+  responseType?: string,
+  isPassthroughRoute: boolean = false,
 ): InternalHandlerContext<any, 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 ?? {};
-
-  // Filter system parameters (starting with _rsc) from searchParams
-  // This ensures handlers only see user-facing query params
-  const cleanSearchParams = new URLSearchParams();
-  searchParams.forEach((value, key) => {
-    if (!key.startsWith("_rsc")) {
-      cleanSearchParams.set(key, value);
-    }
-  });
-
-  // Create clean URL without system params
-  const cleanUrl = new URL(url);
-  cleanUrl.search = cleanSearchParams.toString();
+  const requestContext = _getRequestContext();
+  const variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
   const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
   const resolvedSearchParams = searchSchema
-    ? parseSearchParams(cleanSearchParams, searchSchema)
-    : cleanSearchParams;
+    ? parseSearchParams(searchParams, searchSchema)
+    : searchParams;
 
   // Get stub response from request context for setting headers
-  const stubResponse = requestContext?.res ?? new Response(null, { status: 200 });
+  const stubResponse =
+    requestContext?.res ?? new Response(null, { status: 200 });
 
-  return {
+  // 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.
+  // 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) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        if (MUTATING_HEADERS_METHODS.has(prop as string)) {
+          return (...args: any[]) => {
+            assertNotInsideCacheExec(ctx, "headers");
+            assertCachedHeaderWriteAllowed("ctx.headers", prop);
+            return value.apply(target, args);
+          };
+        }
+        return value.bind(target);
+      }
+      return value;
+    },
+  });
+
+  ctx = {
     params,
+    build: requestContext?.build ?? false,
+    dynamic(): void {
+      requestContext?.dynamic();
+    },
+    dev: false,
     request,
-    searchParams: resolvedSearchParams as any, // Filtered params (typed object or URLSearchParams)
+    searchParams,
+    search: searchSchema ? resolvedSearchParams : {},
     pathname,
-    url: cleanUrl, // Clean URL
+    url,
+    originalUrl: requestContext?.originalUrl ?? new URL(request.url),
     env: bindings,
-    var: variables,
-    get: ((key: string) => variables[key]) as HandlerContext<
-      any,
-      TEnv
-    >["get"],
-    set: ((key: string, value: any) => {
-      variables[key] = value;
+    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");
+      // 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"],
-    _originalRequest: request, // Raw request for advanced use
     res: stubResponse, // Stub response for setting headers
-    headers: stubResponse.headers, // Shorthand for res.headers
+    headers: guardedHeaders, // Guarded shorthand for res.headers
     // Placeholder use() - will be replaced with actual implementation during request
     use: () => {
       throw new Error("ctx.use() called before loaders were initialized");
@@ -124,73 +287,55 @@ export function createHandlerContext<TEnv>(
     // Theme support (when enabled via router config)
     theme: requestContext?.theme,
     setTheme: requestContext?.setTheme,
-    // Scoped reverse for URL generation
-    reverse: (name: string, hrefParams?: Record<string, string>, search?: Record<string, unknown>) => {
-      // Path-based - return directly (optionally with param substitution)
-      if (name.startsWith("/")) {
-        let result = name;
-        if (hrefParams) {
-          result = result.replace(/:([^/]+)/g, (_, key) => {
-            const value = hrefParams[key];
-            if (value === undefined) {
-              throw new Error(`Missing param "${key}" for path "${name}"`);
-            }
-            return encodeURIComponent(value);
-          });
-        }
-        if (search) {
-          const qs = serializeSearchParams(search);
-          if (qs) result += `?${qs}`;
-        }
-        return result;
-      }
-
-      // Resolve route name with namespace support
-      const pattern = resolveRouteName(name, routeMap, routeName);
-
-      if (pattern === undefined) {
+    // Location state support (delegates to request context)
+    setLocationState(entries) {
+      if (!requestContext) {
         throw new Error(
-          `Unknown route: "${name}"${routeName ? ` (current route: ${routeName})` : ""}`
+          "setLocationState() is not available outside a request context",
         );
       }
-
-      let result = pattern;
-
-      // Substitute params
-      if (hrefParams) {
-        result = result.replace(/:([^/]+)/g, (_, key) => {
-          const value = hrefParams[key];
-          if (value === undefined) {
-            throw new Error(`Missing param "${key}" for route "${name}"`);
-          }
-          return encodeURIComponent(value);
-        });
-      }
-
-      // Append search params as query string
-      if (search) {
-        const qs = serializeSearchParams(search);
-        if (qs) result += `?${qs}`;
-      }
-
-      return result;
+      requestContext.setLocationState(entries);
     },
+    routeName: (routeName && !isAutoGeneratedRouteName(routeName)
+      ? routeName
+      : undefined) as HandlerContext["routeName"],
+    // Scoped reverse for URL generation (auto-fills current request params).
+    // Resolve rootScoped eagerly so the reverse function is self-contained
+    // and does not depend on the global rootScopeRoutes registry at call time.
+    reverse: createReverseFunction(
+      routeMap,
+      routeName,
+      params,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    ),
+    passthrough: createPrerenderPassthroughFn(false, isPassthroughRoute),
+    _responseType: responseType,
+    _routeName: routeName,
   };
+  // Brand with taint symbol so "use cache" excludes ctx from cache keys
+  (ctx as any)[NOCACHE_SYMBOL] = true;
+  return ctx;
 }
 
 /**
- * Create a BuildContext for pre-rendering.
+ * Create a PrerenderContext for Prerender() handlers at build time.
  *
- * Returns a HandlerContext-compatible object where params, pathname, url,
- * and use(handle) work, but request/env/headers/cookies/var/searchParams
- * throw with a clear error. Loaders are not available during pre-rendering.
+ * Returns an InternalHandlerContext where params, pathname, url, searchParams,
+ * search, reverse, and use(handle) work. Request-time properties
+ * (request, env, headers, cookies, get, set, res) throw with a clear error.
  */
-export function createBuildContext<TEnv>(
+export function createPrerenderContext<TEnv>(
   params: Record<string, string>,
   pathname: string,
-  handleStore: HandleStore,
+  routeMap: Record<string, string>,
+  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 ?? {};
 
   function throwUnavailable(prop: string): never {
     throw new Error(
@@ -201,29 +346,134 @@ export function createBuildContext<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");
     },
-    get searchParams(): URLSearchParams {
-      return throwUnavailable("searchParams");
-    },
+    searchParams: syntheticUrl.searchParams,
+    search: {},
     pathname,
     url: syntheticUrl,
+    originalUrl: syntheticUrl,
     get env(): TEnv {
-      return throwUnavailable("env");
+      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.",
+      );
     },
-    get var(): any {
-      return throwUnavailable("var");
-    },
-    get: (() => {
-      throwUnavailable("get");
-    }) as any,
-    set: (() => {
-      throwUnavailable("set");
+    // 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);
     }) as any,
-    get _originalRequest(): Request {
+    get res(): Response {
+      return throwUnavailable("res");
+    },
+    get headers(): Headers {
+      return throwUnavailable("headers");
+    },
+    // Placeholder use() - replaced by setupBuildUse
+    use: () => {
+      throw new Error("ctx.use() called before build context was initialized");
+    },
+    theme: undefined,
+    setTheme: undefined,
+    routeName: (routeName && !isAutoGeneratedRouteName(routeName)
+      ? routeName
+      : undefined) as HandlerContext["routeName"],
+    setLocationState: () => {
+      throwUnavailable("setLocationState");
+    },
+    reverse: createReverseFunction(
+      routeMap,
+      routeName,
+      params,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    ),
+    passthrough: createPrerenderPassthroughFn(
+      true,
+      isPassthroughRoute === true,
+    ),
+    _routeName: routeName,
+  } as InternalHandlerContext<any, TEnv>;
+}
+
+/**
+ * Create a StaticContext for Static() handlers at build time.
+ *
+ * Returns an InternalHandlerContext where only reverse and use(handle) work.
+ * Static handlers have no URL, no params, no pathname — everything else throws.
+ */
+export function createStaticContext<TEnv>(
+  routeMap: Record<string, string>,
+  routeName?: string,
+  buildEnv?: TEnv,
+  devMode?: boolean,
+): InternalHandlerContext<any, TEnv> {
+  const variables: Record<string, any> = {};
+
+  function throwUnavailable(prop: string): never {
+    throw new Error(
+      `Property "${prop}" is not available in Static() handlers. ` +
+        `Static handlers render content without request context.`,
+    );
+  }
+
+  return {
+    get params(): any {
+      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");
     },
+    get searchParams(): URLSearchParams {
+      return throwUnavailable("searchParams");
+    },
+    get search(): any {
+      return throwUnavailable("search");
+    },
+    get pathname(): string {
+      return throwUnavailable("pathname");
+    },
+    get url(): URL {
+      return throwUnavailable("url");
+    },
+    get originalUrl(): URL {
+      return throwUnavailable("originalUrl");
+    },
+    get env(): TEnv {
+      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);
+    }) as any,
     get res(): Response {
       return throwUnavailable("res");
     },
@@ -236,8 +486,18 @@ export function createBuildContext<TEnv>(
     },
     theme: undefined,
     setTheme: undefined,
-    reverse: () => {
-      throwUnavailable("reverse");
+    routeName: (routeName && !isAutoGeneratedRouteName(routeName)
+      ? routeName
+      : undefined) as HandlerContext["routeName"],
+    setLocationState: () => {
+      throwUnavailable("setLocationState");
     },
+    reverse: createReverseFunction(
+      routeMap,
+      routeName,
+      undefined,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    ),
+    _routeName: routeName,
   } as InternalHandlerContext<any, TEnv>;
 }