@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

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

@@ -0,0 +1,362 @@
+/**
+ * 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 { requireRequestContext } from "../server/request-context.js";
+import { contextGet } from "../context-var.js";
+import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import { traverseBack } from "../router/pattern-matching.js";
+import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
+import { createCacheScope } from "../cache/cache-scope.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";
+
+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 = requireRequestContext();
+  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) => {
+        if (key.toLowerCase() === "set-cookie") {
+          headers.append(key, value);
+        } else {
+          headers.set(key, value);
+        }
+      });
+      return createResponseWithMergedHeaders(result.body, {
+        status: result.status,
+        headers,
+      });
+    };
+
+    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. JSON.stringify would silently emit {} for it (the
+        // forgotten-await footgun — the RSC pipeline awaits nested promises, this
+        // path does not). Throw a clear error instead of shipping empty data.
+        const body = JSON.stringify(result, (_key, value) => {
+          if (
+            value != null &&
+            typeof (value as { then?: unknown }).then === "function"
+          ) {
+            throw new RouterError(
+              "RESPONSE_NOT_SERIALIZABLE",
+              "A json() response route returned a Promise (likely a forgotten " +
+                "await). Await async values before returning so they serialize, " +
+                "instead of emitting an empty {}.",
+            );
+          }
+          return value;
+        });
+        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();
+  };
+
+  // Resolve cache config from entry tree (same pattern as match-api.ts)
+  if (preview.manifestEntry) {
+    let cacheScope: ReturnType<typeof createCacheScope> = null;
+    for (const entry of traverseBack(preview.manifestEntry)) {
+      if (entry.cache) {
+        cacheScope = createCacheScope(entry.cache, cacheScope);
+      }
+    }
+
+    if (cacheScope?.enabled) {
+      // Evaluate condition — skip 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) {
+        // Build cache key with response:{type}: prefix to avoid collision
+        // with segment keys and differentiate between response types.
+        // Include host and url.search so query-driven and multi-host
+        // responses cache separately.
+        let cacheKey = `response:${preview.responseType}:${url.host}${url.pathname}${url.search}`;
+
+        // Priority 1: Route-level key function (full override)
+        if (cacheScope.config !== false && cacheScope.config.key) {
+          try {
+            const customKey = await cacheScope.config.key(reqCtx);
+            cacheKey = `response:${customKey}`;
+          } catch {
+            // Fall back to default key on route-level key failure
+          }
+        } else if (store.keyGenerator) {
+          // Priority 2: Store-level keyGenerator (modifies default key)
+          try {
+            cacheKey = await store.keyGenerator(reqCtx, cacheKey);
+          } catch {
+            // Fall back to default key on keyGenerator failure
+          }
+        }
+
+        // Save pre-handler callbacks (registered by app-level middleware
+        // before we reach the cache block) and clear the live array.
+        // createResponseWithMergedHeaders (inside the handler) eagerly
+        // executes any callbacks present in _onResponseCallbacks, so
+        // handler-registered callbacks are baked into the handler's
+        // response and the cached artifact. Pre-handler callbacks are
+        // NOT in the live array during execution, so they are applied
+        // once per serve on every path (hit + miss) below.
+        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;
+        };
+
+        try {
+          const cached = await store.getResponse(cacheKey);
+
+          if (cached && isCacheableStatus(cached.response.status)) {
+            if (!cached.shouldRevalidate) {
+              // Fresh hit
+              return applyPreHandlerCallbacks(cached.response);
+            }
+
+            // Stale hit (SWR) - return cached, revalidate in background
+            reqCtx.waitUntil(async () => {
+              try {
+                // finalizeResponse drains any onResponse callbacks registered
+                // during middleware execution (e.g. middleware short-circuit)
+                // that createResponseWithMergedHeaders didn't reach.
+                const fresh = finalizeResponse(await executeHandler());
+                if (isCacheableStatus(fresh.status)) {
+                  await store.putResponse!(
+                    cacheKey,
+                    fresh.clone(),
+                    cacheScope!.ttl,
+                    cacheScope!.swr,
+                  );
+                }
+              } catch (error) {
+                console.error(`[ResponseCache] Revalidation failed:`, error);
+              }
+            });
+
+            return applyPreHandlerCallbacks(cached.response);
+          }
+        } catch (error) {
+          console.error(`[ResponseCache] Cache lookup failed:`, error);
+        }
+
+        // Cache miss - execute handler and cache the result.
+        // createResponseWithMergedHeaders inside the handler drains callbacks
+        // registered during handler execution. finalizeResponse catches any
+        // remaining callbacks (e.g. from middleware short-circuit where the
+        // handler never ran) so the cached artifact includes all transforms.
+        const response = finalizeResponse(await executeHandler());
+
+        if (isCacheableStatus(response.status)) {
+          reqCtx.waitUntil(async () => {
+            try {
+              await store.putResponse!(
+                cacheKey,
+                response.clone(),
+                cacheScope!.ttl,
+                cacheScope!.swr,
+              );
+            } catch (error) {
+              console.error(`[ResponseCache] Cache write failed:`, error);
+            }
+          });
+        }
+
+        return applyPreHandlerCallbacks(response);
+      }
+    }
+  }
+
+  return executeHandler().then(finalizeResponse);
+}

package/src/rsc/rsc-rendering.ts

@@ -0,0 +1,240 @@
+/**
+ * RSC Rendering Handler (Navigation)
+ *
+ * Handles RSC rendering for both partial (client-side navigation) and full
+ * (initial page load) requests. Includes prerender collection for build-time
+ * static generation.
+ */
+
+import {
+  requireRequestContext,
+  setRequestContextParams,
+  getLocationState,
+} from "../server/request-context.js";
+import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import { appendMetric } from "../router/metrics.js";
+import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
+import type { RscPayload } from "./types.js";
+import type { MatchResult } from "../types.js";
+import {
+  createResponseWithMergedHeaders,
+  createSimpleRedirectResponse,
+} from "./helpers.js";
+import type { HandlerContext } from "./handler-context.js";
+
+export async function handleRscRendering<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  isPartial: boolean,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  nonce: string | undefined,
+): Promise<Response> {
+  const reqCtx = requireRequestContext();
+
+  let payload: RscPayload;
+  let hasInterceptSlots = false;
+
+  // Shared by the partial-fallback and full-render paths. The partial-success
+  // payload below is intentionally different (omits rootLayout/theme, adds slots).
+  const buildFullPayload = (m: MatchResult): RscPayload => ({
+    metadata: {
+      pathname: url.pathname,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
+      segments: m.segments,
+      matched: m.matched,
+      diff: m.diff,
+      resolvedIds: m.resolvedIds,
+      params: m.params,
+      isPartial: false,
+      rootLayout: ctx.router.rootLayout,
+      handles: handleStore.stream(),
+      version: ctx.version,
+      prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+      themeConfig: ctx.router.themeConfig,
+      initialTheme: reqCtx.theme,
+    },
+  });
+
+  if (isPartial) {
+    // Partial render (navigation)
+    const result = await ctx.router.matchPartial(request, { env });
+
+    if (!result) {
+      // Fall back to full render
+      const match = await ctx.router.match(request, { env });
+      setRequestContextParams(match.params, match.routeName);
+
+      if (match.redirect) {
+        // Partial request: use X-RSC-Redirect header so the client can
+        // perform SPA navigation. A raw 308 would be auto-followed by
+        // fetch, hitting the target without _rsc_partial.
+        return createSimpleRedirectResponse(match.redirect);
+      }
+
+      payload = buildFullPayload(match);
+    } else {
+      setRequestContextParams(result.params, result.routeName);
+
+      hasInterceptSlots = !!result.slots;
+
+      payload = {
+        metadata: {
+          pathname: url.pathname,
+          // routerId is serialized on every payload (including within-session
+          // ones) so the frontend can read the current app/router identity. It
+          // always equals the current app's id: a cross-app navigation is
+          // intercepted server-side (X-RSC-Reload) and never delivers a
+          // different-router payload to the client.
+          routerId: ctx.router.id,
+          segments: result.segments,
+          matched: result.matched,
+          diff: result.diff,
+          resolvedIds: result.resolvedIds,
+          params: result.params,
+          isPartial: true,
+          slots: result.slots,
+          handles: handleStore.stream(),
+          version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+        },
+      };
+    }
+  } else {
+    // Full render (initial page load)
+    const match = await ctx.router.match(request, { env });
+    setRequestContextParams(match.params, match.routeName);
+
+    if (match.redirect) {
+      return createResponseWithMergedHeaders(null, {
+        status: 308,
+        headers: { Location: match.redirect },
+      });
+    }
+
+    // Caching is now handled in router.match() via cache provider in request context
+    // match.segments already contains cached or fresh segments as appropriate
+
+    if (url.searchParams.has("__prerender_collect")) {
+      // Build-time prerender collection: serialize segments and handle data
+      // to JSON for storage as build artifacts. At runtime the worker
+      // deserializes these and feeds them through the normal segment pipeline.
+      const nonLoaderSegments = match.segments.filter(
+        (s) => s.type !== "loader",
+      );
+      handleStore.seal();
+      await handleStore.settled;
+      const { serializeSegments } = await import("../cache/segment-codec.js");
+      const serializedSegments = await serializeSegments(nonLoaderSegments);
+      const handles: Record<string, Record<string, unknown[]>> = {};
+      for (const seg of nonLoaderSegments) {
+        const segHandles = handleStore.getDataForSegment(seg.id);
+        if (Object.keys(segHandles).length > 0) {
+          handles[seg.id] = segHandles;
+        }
+      }
+      return new Response(
+        JSON.stringify({
+          segments: serializedSegments,
+          handles,
+          routeName: match.routeName,
+          params: match.params,
+        }),
+        { headers: { "Content-Type": "application/json" } },
+      );
+    } else {
+      payload = buildFullPayload(match);
+    }
+  }
+
+  // For partial requests, include any server-set location state in the payload.
+  // SSR (full page) requests ignore location state since there's no history.state
+  // to write to on a fresh page load.
+  if (isPartial && payload.metadata) {
+    const locationState = getLocationState();
+    if (locationState) {
+      payload.metadata.locationState =
+        resolveLocationStateEntries(locationState);
+    }
+  }
+
+  const metricsStore = reqCtx._metricsStore;
+  const renderStart = performance.now();
+
+  // Serialize to RSC stream
+  const rscSerializeStart = performance.now();
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
+  const rscSerializeDur = performance.now() - rscSerializeStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  appendMetric(
+    metricsStore,
+    "rsc-serialize",
+    rscSerializeStart,
+    rscSerializeDur,
+  );
+
+  if (isRscRequest(request, url, isPartial)) {
+    const renderDur = performance.now() - renderStart;
+    appendMetric(metricsStore, "render:total", renderStart, renderDur);
+    const rscHeaders: Record<string, string> = {
+      "content-type": "text/x-component;charset=utf-8",
+      vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
+      // Router identity, so the client can verify pre-decode (before importing
+      // chunks) that this content payload belongs to its app and refuse a
+      // foreign one (cache/proxy/bug). Control-only reload/redirect responses
+      // are deliberately NOT stamped. See browser/response-adapter.ts.
+      "X-RSC-Router-Id": ctx.router.id,
+    };
+    // Tell the client's prefetch cache to scope this response to its source
+    // URL (instead of the default source-agnostic wildcard). Intercept
+    // responses depend on the source page matching an intercept rule, so
+    // they must not be reused for navigations from other sources.
+    if (hasInterceptSlots) {
+      rscHeaders["x-rsc-prefetch-scope"] = "source";
+    }
+    // Enable browser HTTP caching for prefetch responses only.
+    // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
+    // non-intercept context (intercept responses depend on source page),
+    // and a configured cache-control value (false disables caching).
+    const isPrefetch = request.headers.has("X-Rango-Prefetch");
+    if (isPrefetch && isPartial && !hasInterceptSlots) {
+      const cc = ctx.router.prefetchCacheControl;
+      if (cc) {
+        rscHeaders["cache-control"] = cc;
+      }
+    }
+    return createResponseWithMergedHeaders(rscStream, {
+      headers: rscHeaders,
+    });
+  }
+
+  // Delegate to SSR for HTML response (reuse early setup if available)
+  const [ssrModule, streamMode] = await getSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    metricsStore,
+  );
+
+  const ssrRenderStart = performance.now();
+  const htmlStream = await ssrModule.renderHTML(rscStream, {
+    nonce,
+    streamMode,
+  });
+  const ssrRenderDur = performance.now() - ssrRenderStart;
+  appendMetric(metricsStore, "ssr-render-html", ssrRenderStart, ssrRenderDur);
+
+  const renderDur = performance.now() - renderStart;
+  appendMetric(metricsStore, "render:total", renderStart, renderDur);
+
+  return createResponseWithMergedHeaders(htmlStream, {
+    headers: { "content-type": "text/html;charset=utf-8" },
+  });
+}

package/src/rsc/runtime-warnings.ts

@@ -0,0 +1,41 @@
+/**
+ * Runtime guardrail warnings (dev-only).
+ *
+ * W3: PE action redirect / Response handling.
+ */
+
+import {
+  createResponseWithMergedHeaders,
+  carryOverRedirectHeaders,
+} from "./helpers.js";
+import { isRedirectResponse } from "../response-utils.js";
+
+// W3 -----------------------------------------------------------------------
+
+/**
+ * Extract a redirect Response from a thrown or returned value.
+ * Returns a redirect Response to send to the client, or null if the value
+ * is not a redirect Response.
+ */
+export function extractRedirectResponse(value: unknown): Response | null {
+  if (!(value instanceof Response)) return null;
+  if (!isRedirectResponse(value)) return null;
+  const location = value.headers.get("Location")!;
+  const redirect = createResponseWithMergedHeaders(null, {
+    status: value.status,
+    headers: { Location: location },
+  });
+  carryOverRedirectHeaders(value, redirect);
+  return redirect;
+}
+
+/**
+ * Warn when a non-redirect Response is returned from an action during PE.
+ */
+export function warnNonRedirectPeResponse(): void {
+  console.warn(
+    `[rango] Server action returned a non-redirect Response during ` +
+      `progressive enhancement (no-JS) request. The Response will be ` +
+      `ignored — the page will re-render at the current URL instead.`,
+  );
+}