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

package/src/rsc/response-cache-serve.ts

@@ -0,0 +1,238 @@
+/**
+ * Shared response-route cache serve.
+ *
+ * Owns the single response-cache contract — cache-scope resolution from the
+ * matched entry tree, condition eval, key resolution (route key() > store
+ * keyGenerator > default), tag resolution, pre-handler-callback timing, and the
+ * fresh-hit / SWR-revalidate / miss-write branches — for BOTH the production
+ * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
+ * primitive (testing/dispatch.ts), so the two can never drift.
+ *
+ * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
+ * which the non-Vite unit-test runner cannot resolve, and this module is on the
+ * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` and
+ * `resolveCacheTags` are NOT imported here at runtime — they are INJECTED by the
+ * caller (production imports them statically; dispatch lazy-imports them only once
+ * a response route matches). The only runtime imports here are plugin-rsc-free
+ * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
+ * type-only import (erased at build).
+ */
+
+import type { CacheScope } from "../cache/cache-scope.js";
+import type { PartialCacheOptions } from "../types.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { EntryCacheConfig, EntryData } from "../server/context.js";
+import { traverseBack } from "../router/pattern-matching.js";
+import { isCacheableStatus, finalizeResponse } from "./helpers.js";
+import { reportCacheError } from "../cache/cache-error.js";
+
+/** Injected cache-scope builders (kept off this module's runtime import graph). */
+export interface CacheScopeDeps {
+  createCacheScope: (
+    config: EntryCacheConfig | undefined,
+    parent?: CacheScope | null,
+  ) => CacheScope | null;
+  resolveCacheTags: (
+    config: PartialCacheOptions | false,
+    ctx: RequestContext | undefined,
+  ) => string[] | undefined;
+}
+
+export interface ServeResponseRouteWithCacheArgs {
+  reqCtx: RequestContext;
+  manifestEntry: EntryData;
+  responseType: string;
+  url: URL;
+  /** callHandler wrapped by route-level middleware — the unit the cache wraps. */
+  executeHandler: () => Promise<Response>;
+  deps: CacheScopeDeps;
+}
+
+/**
+ * Serve a response route through its cache, or return `undefined` when no cache
+ * applies (no scope, disabled, condition false, or store lacks get/putResponse)
+ * so the caller falls through to a plain `executeHandler()` run.
+ *
+ * Must run inside runWithRequestContext (reads the ambient request context via
+ * the helpers and reqCtx.waitUntil for background writes).
+ */
+export async function serveResponseRouteWithCache(
+  args: ServeResponseRouteWithCacheArgs,
+): Promise<Response | undefined> {
+  const { reqCtx, manifestEntry, responseType, url, executeHandler, deps } =
+    args;
+
+  let cacheScope: CacheScope | null = null;
+  for (const entry of traverseBack(manifestEntry)) {
+    if (entry.cache) {
+      cacheScope = deps.createCacheScope(entry.cache, cacheScope);
+    }
+  }
+
+  if (!cacheScope?.enabled) return undefined;
+
+  // Evaluate condition — skip the response cache when condition returns false.
+  let conditionPassed = true;
+  if (cacheScope.config !== false && cacheScope.config.condition) {
+    try {
+      conditionPassed = !!cacheScope.config.condition(reqCtx);
+    } catch {
+      conditionPassed = false;
+    }
+  }
+
+  const store = cacheScope.getStore() ?? reqCtx._cacheStore;
+  if (!conditionPassed || !store?.getResponse || !store?.putResponse) {
+    return undefined;
+  }
+
+  // Build cache key with the response:{type}: prefix (avoids collision with
+  // segment keys); include host + url.search so query-driven and multi-host
+  // responses cache separately.
+  let cacheKey = `response:${responseType}:${url.host}${url.pathname}${url.search}`;
+
+  // Priority 1: route-level key() (full override). Priority 2: store-level
+  // keyGenerator (modifies the default key).
+  //
+  // A CONFIGURED key()/keyGenerator that THROWS must DEGRADE TO A MISS, not fall
+  // back to the broad default key. The default key
+  // `response:${type}:${host}${path}${search}` is intentionally broad; if the
+  // configured key encodes tenant/user/auth state, falling back to the broad key
+  // would cache PERSONALIZED output under it and serve it cross-user (cache
+  // poisoning). Mirrors the segment-cache behavior (cache-scope.ts lookupRoute):
+  // a throwing key degrades to a cache miss, never a collision onto the default
+  // slot. The no-key default path is left untouched (the broad key is correct
+  // when no key is configured).
+  let keyResolutionFailed = false;
+  if (cacheScope.config !== false && cacheScope.config.key) {
+    try {
+      const customKey = await cacheScope.config.key(reqCtx);
+      cacheKey = `response:${customKey}`;
+    } catch (error) {
+      keyResolutionFailed = true;
+      reportCacheError(
+        error,
+        "cache-read",
+        "[ResponseCache] Key resolution failed",
+        reqCtx,
+      );
+    }
+  } else if (store.keyGenerator) {
+    try {
+      cacheKey = await store.keyGenerator(reqCtx, cacheKey);
+    } catch (error) {
+      keyResolutionFailed = true;
+      reportCacheError(
+        error,
+        "cache-read",
+        "[ResponseCache] keyGenerator failed",
+        reqCtx,
+      );
+    }
+  }
+
+  // Degrade to a MISS: return undefined so the caller runs the route UNCACHED.
+  // This early-returns BEFORE _onResponseCallbacks is saved/cleared below, so the
+  // pre-handler onResponse callbacks are still intact for the uncached run.
+  if (keyResolutionFailed) {
+    return undefined;
+  }
+
+  // Resolve cache tags for this document entry (static or dynamic) while the
+  // request context is available, so the stored entry is tag-invalidatable.
+  const responseTags = deps.resolveCacheTags(cacheScope.config, reqCtx);
+
+  // Pre-handler callbacks (registered by app-level middleware before the cache
+  // block) are saved and the live array is cleared:
+  // createResponseWithMergedHeaders inside the handler eagerly drains whatever is
+  // in _onResponseCallbacks, so handler-registered callbacks bake into the cached
+  // artifact, while these pre-handler callbacks are applied once per serve on
+  // every path (hit + miss).
+  const savedCallbacks = reqCtx._onResponseCallbacks;
+  reqCtx._onResponseCallbacks = [];
+  const applyPreHandlerCallbacks = (response: Response): Response => {
+    let result = response;
+    for (const callback of savedCallbacks) {
+      result = callback(result) ?? result;
+    }
+    return result;
+  };
+
+  const putFresh = (
+    store2: SegmentCacheStore,
+    fresh: Response,
+  ): Promise<void> =>
+    store2.putResponse!(
+      cacheKey,
+      fresh.clone(),
+      cacheScope!.ttl,
+      cacheScope!.swr,
+      responseTags,
+    );
+
+  try {
+    const cached = await store.getResponse(cacheKey);
+    if (cached && isCacheableStatus(cached.response.status)) {
+      if (!cached.shouldRevalidate) {
+        return applyPreHandlerCallbacks(cached.response);
+      }
+      // Stale hit (SWR): return cached, revalidate in background.
+      reqCtx.waitUntil(async () => {
+        try {
+          const fresh = finalizeResponse(await executeHandler());
+          if (isCacheableStatus(fresh.status)) await putFresh(store, fresh);
+        } catch (error) {
+          reportCacheError(
+            error,
+            "stale-revalidation",
+            "[ResponseCache] background revalidation",
+            reqCtx,
+          );
+        }
+      });
+      return applyPreHandlerCallbacks(cached.response);
+    }
+  } catch (error) {
+    reportCacheError(
+      error,
+      "cache-read",
+      "[ResponseCache] Cache lookup failed",
+      reqCtx,
+    );
+  }
+
+  // Cache miss: execute the handler and cache the result.
+  const response = finalizeResponse(await executeHandler());
+  if (isCacheableStatus(response.status)) {
+    // Clone SYNCHRONOUSLY here, before returning. The original `response` is
+    // handed back to the middleware chain, where mergeResponse rebuilds it as
+    // `new Response(response.body, ...)`. Deferring the clone into the waitUntil
+    // callback (putFresh(response), which clones inside the async body) raced
+    // that rebuild: the background clone() and the foreground body read could
+    // interleave and throw "Response body object should not be disturbed or
+    // locked" (a flaky 500). Teeing now keeps the returned body independent of
+    // the cache write. The SWR path above is unaffected (its `fresh` is created
+    // inside the background callback and never returned to the caller).
+    const toCache = response.clone();
+    reqCtx.waitUntil(async () => {
+      try {
+        await store.putResponse!(
+          cacheKey,
+          toCache,
+          cacheScope!.ttl,
+          cacheScope!.swr,
+          responseTags,
+        );
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-write",
+          "[ResponseCache] Cache write failed",
+          reqCtx,
+        );
+      }
+    });
+  }
+  return applyPreHandlerCallbacks(response);
+}

package/src/rsc/response-error.ts

@@ -0,0 +1,104 @@
+/**
+ * Problem Details (RFC 9457) Builder
+ *
+ * Builds a problem+json error body from a caught error, controlling what
+ * information is exposed based on error type and environment.
+ */
+
+import { RouterError } from "../errors.js";
+import type { ProblemDetails } from "../urls.js";
+
+/**
+ * HTTP reason phrases for the problem `title` member. Inlined because the
+ * router targets edge/worker runtimes without node's `http.STATUS_CODES`;
+ * covers the full standard 4xx/5xx range, with a generic fallback for any
+ * non-standard status a handler might set.
+ */
+const STATUS_PHRASES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Payload Too Large",
+  414: "URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a Teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
+  429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required",
+};
+
+function statusPhrase(status: number): string {
+  return STATUS_PHRASES[status] ?? "Error";
+}
+
+/**
+ * Build an RFC 9457 problem+json body from a caught error.
+ * RouterError messages/codes are always exposed (developer-crafted).
+ * Standard Error messages are hidden in production.
+ *
+ * The `type` member is omitted in this phase: per RFC 9457 an absent `type` is
+ * treated as `"about:blank"` (no semantics beyond the HTTP status), so emitting
+ * it adds nothing. Per-route problem-type URIs arrive with the declared-errors
+ * map later. `code` is always present so consumers can branch on it
+ * (`"INTERNAL"` for non-RouterError failures).
+ */
+export function createProblemDetails(
+  error: unknown,
+  status: number,
+  isDev: boolean,
+): ProblemDetails {
+  if (error instanceof RouterError) {
+    return {
+      title: statusPhrase(status),
+      status,
+      detail: error.message,
+      code: error.code,
+      ...(isDev && error.stack ? { stack: error.stack } : {}),
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      title: statusPhrase(status),
+      status,
+      detail: isDev ? error.message : "Internal Server Error",
+      code: "INTERNAL",
+      ...(isDev && error.stack ? { stack: error.stack } : {}),
+    };
+  }
+  return {
+    title: statusPhrase(status),
+    status,
+    detail: isDev ? String(error) : "Internal Server Error",
+    code: "INTERNAL",
+  };
+}

package/src/rsc/response-route-handler.ts

@@ -0,0 +1,257 @@
+/**
+ * Response Route Handler
+ *
+ * Handles response routes (JSON, text, HTML, XML, markdown, image, stream)
+ * that bypass the RSC rendering pipeline entirely. Includes content-type
+ * dispatch, route middleware execution, and response caching with SWR.
+ */
+
+import { RouterError } from "../errors.js";
+import { getRequestContext } from "../server/request-context.js";
+import { contextGet } from "../context-var.js";
+import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
+import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
+import { serveResponseRouteWithCache } from "./response-cache-serve.js";
+import { executeMiddleware } from "../router/middleware.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+import type { EntryData } from "../server/context.js";
+import type { HandlerContext } from "./handler-context.js";
+import { createProblemDetails } from "./response-error.js";
+import {
+  createResponseWithMergedHeaders,
+  finalizeResponse,
+  isCacheableStatus,
+  buildRouteMiddlewareEntries,
+  mergeStubHeadersAndFinalize,
+} from "./helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import { stringifyJsonRouteResult } from "./json-route-result.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
+
+export interface ResponseRouteMatch {
+  responseType: string;
+  handler: Function;
+  params?: Record<string, string>;
+  negotiated?: boolean;
+  manifestEntry?: EntryData;
+  routeMiddleware?: Array<{
+    handler: MiddlewareFn;
+    params: Record<string, string>;
+  }>;
+}
+
+/**
+ * Handle a response route (non-RSC). Dispatches by content type, wraps
+ * with route middleware and response caching when configured.
+ *
+ * For partial (client-side navigation) requests, returns X-RSC-Reload
+ * so the browser triggers a hard navigation to the response route URL.
+ */
+export async function handleResponseRoute<TEnv>(
+  handlerCtx: HandlerContext<TEnv>,
+  preview: ResponseRouteMatch,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  variables: Record<string, any>,
+): Promise<Response> {
+  const isPartial = url.searchParams.has("_rsc_partial");
+
+  // Partial requests (client-side navigation) to response routes
+  // get X-RSC-Reload to trigger hard navigation in the browser
+  if (isPartial) {
+    return createResponseWithMergedHeaders(null, {
+      status: 200,
+      headers: {
+        "X-RSC-Reload": stripInternalParams(url).toString(),
+        "content-type": "text/x-component;charset=utf-8",
+      },
+    });
+  }
+
+  // Build lightweight context for response handler
+  const reqCtx = getRequestContext();
+  const cleanUrl = stripInternalParams(url);
+  const responseHandlerCtx = {
+    request,
+    params: preview.params || {},
+    env,
+    searchParams: cleanUrl.searchParams,
+    url: cleanUrl,
+    originalUrl: reqCtx.originalUrl,
+    pathname: url.pathname,
+    reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
+    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
+    header: (name: string, value: string) => reqCtx.header(name, value),
+    waitUntil: reqCtx.waitUntil.bind(reqCtx),
+    executionContext: reqCtx.executionContext,
+    _responseType: preview.responseType,
+  };
+  // Brand with taint symbol so "use cache" detects it as request-scoped
+  // and extracts route-identifying properties (params, pathname, _responseType)
+  (responseHandlerCtx as any)[NOCACHE_SYMBOL] = true;
+
+  // Call handler directly, wrapped by route middleware if present
+  const callHandler = async () => {
+    const errorCtx = { request, url, env };
+
+    // Re-wrap a handler-returned Response through createResponseWithMergedHeaders
+    // so that stub headers (cookies, custom headers set via ctx.header()) are included.
+    // Use Headers (not Record<string, string>) to preserve duplicate entries like Set-Cookie.
+    const rewrapResponse = (result: Response) => {
+      // 204/205/304 are NOT short-circuited — they're valid for the Response
+      // constructor and must honor ctx.setStatus() overrides. Only upgrade
+      // responses (status 101 / `webSocket` property) bypass reconstruction.
+      if (isWebSocketUpgradeResponse(result)) {
+        return mergeStubHeadersAndFinalize(result);
+      }
+      const headers = new Headers();
+      result.headers.forEach((value, key) => {
+        // Never copy the reserved external-redirect marker off a handler result.
+        // It is not a trust signal -- the opt-in is the out-of-band brand below
+        // -- and a proxy-style route returning an attacker-controlled upstream
+        // response must not let a forged value ride through to the browser.
+        if (key.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
+        if (key.toLowerCase() === "set-cookie") {
+          headers.append(key, value);
+        } else {
+          headers.set(key, value);
+        }
+      });
+      const rewrapped = createResponseWithMergedHeaders(result.body, {
+        status: result.status,
+        headers,
+      });
+      // Transfer the out-of-band external brand only when the handler result is
+      // genuinely branded (a real redirect(url, { external: true })). A proxied
+      // upstream Response is never branded, so an attacker cannot opt a response
+      // route's redirect out of the same-origin guard by injecting the header.
+      if (isExternalRedirect(result)) {
+        markExternalRedirect(rewrapped);
+      }
+      return rewrapped;
+    };
+
+    try {
+      const result = await (preview.handler as Function)(responseHandlerCtx);
+
+      if (result instanceof Response) {
+        return rewrapResponse(result);
+      }
+
+      // Handled before the MIME lookup (json is also a RESPONSE_TYPE_MIME key).
+      if (preview.responseType === "json") {
+        // Runtime guard: the json() return type rejects nested Promises at
+        // compile time, but an `as`-cast or untyped (JS) handler can still slip
+        // one through. stringifyJsonRouteResult throws a clear error instead of
+        // shipping empty data (shared with dispatch() so the two cannot drift).
+        const body = stringifyJsonRouteResult(result);
+        return createResponseWithMergedHeaders(body, {
+          status: 200,
+          headers: { "content-type": "application/json;charset=utf-8" },
+        });
+      }
+
+      // Object.hasOwn (not truthiness) so prototype names like "toString" are not
+      // matched; image/stream/any are absent and fall through to the throw.
+      if (Object.hasOwn(RESPONSE_TYPE_MIME, preview.responseType)) {
+        return createResponseWithMergedHeaders(String(result), {
+          status: 200,
+          headers: {
+            "content-type": `${RESPONSE_TYPE_MIME[preview.responseType]};charset=utf-8`,
+          },
+        });
+      }
+
+      throw new Error(
+        `Response route handler for "${preview.responseType}" must return a Response object, got ${typeof result}`,
+      );
+    } catch (error) {
+      handlerCtx.callOnError(error, "handler", errorCtx);
+      const isDev = process.env.NODE_ENV !== "production";
+      const derivedStatus = error instanceof RouterError ? error.status : 500;
+      // Resolve the effective status the same way createResponseWithMergedHeaders
+      // will (ctx.res.status override) so the problem body's status/title match
+      // the actual HTTP status — e.g. when a handler called ctx.setStatus()
+      // before throwing.
+      const status =
+        reqCtx.res.status !== 200 ? reqCtx.res.status : derivedStatus;
+
+      if (preview.responseType === "json") {
+        return createResponseWithMergedHeaders(
+          JSON.stringify(createProblemDetails(error, status, isDev)),
+          {
+            status,
+            headers: {
+              "content-type": "application/problem+json;charset=utf-8",
+            },
+          },
+        );
+      }
+
+      const message =
+        error instanceof RouterError
+          ? error.message
+          : isDev && error instanceof Error
+            ? error.message
+            : "Internal Server Error";
+      return createResponseWithMergedHeaders(message, {
+        status,
+        headers: { "content-type": "text/plain;charset=utf-8" },
+      });
+    }
+  };
+
+  // Wrap callHandler to append Vary: Accept on content-negotiated responses
+  const callHandlerWithVary = async () => {
+    const response = await callHandler();
+    if (preview.negotiated && !isWebSocketUpgradeResponse(response)) {
+      // Skip Vary on upgrade responses: headers are semantically immutable
+      // on some runtimes, and Vary is meaningless for a 101 response.
+      response.headers.append("Vary", "Accept");
+    }
+    return response;
+  };
+
+  // Wrap with route middleware if present
+  const executeHandler = async () => {
+    if (preview.routeMiddleware && preview.routeMiddleware.length > 0) {
+      return executeMiddleware(
+        buildRouteMiddlewareEntries<TEnv>(preview.routeMiddleware),
+        request,
+        env,
+        variables,
+        callHandlerWithVary,
+        createReverseFunction(handlerCtx.getRequiredRouteMap()),
+      );
+    }
+    return callHandlerWithVary();
+  };
+
+  // Response-route cache: resolved through the shared serve leaf
+  // (rsc/response-cache-serve.ts) so production and the dispatch testing
+  // primitive share ONE owner of the cache contract. Returns undefined when no
+  // cache applies, so we fall through to a plain handler run.
+  if (preview.manifestEntry) {
+    const cached = await serveResponseRouteWithCache({
+      reqCtx,
+      manifestEntry: preview.manifestEntry,
+      responseType: preview.responseType,
+      url,
+      executeHandler,
+      deps: { createCacheScope, resolveCacheTags },
+    });
+    if (cached !== undefined) return cached;
+  }
+
+  return executeHandler().then(finalizeResponse);
+}