@rangojs/router 0.0.0-experimental.0f44aca1

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

@@ -0,0 +1,347 @@
+/**
+ * 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 { 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 { createResponseErrorPayload } from "./response-error.js";
+import {
+  createResponseWithMergedHeaders,
+  finalizeResponse,
+  isCacheableStatus,
+  buildRouteMiddlewareEntries,
+} from "./helpers.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,
+    pathname: url.pathname,
+    reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
+    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
+    header: (name: string, value: string) => reqCtx.header(name, value),
+    _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) => {
+      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,
+      });
+    };
+
+    // JSON response routes: wrap in { data } / { error } envelope
+    if (preview.responseType === "json") {
+      try {
+        const result = await (preview.handler as Function)(responseHandlerCtx);
+        if (result instanceof Response) {
+          return rewrapResponse(result);
+        }
+        return createResponseWithMergedHeaders(
+          JSON.stringify({ data: result }),
+          {
+            status: 200,
+            headers: { "content-type": "application/json;charset=utf-8" },
+          },
+        );
+      } catch (error) {
+        handlerCtx.callOnError(error, "handler", errorCtx);
+        const isDev = process.env.NODE_ENV !== "production";
+        const status = error instanceof RouterError ? error.status : 500;
+        return createResponseWithMergedHeaders(
+          JSON.stringify({
+            error: createResponseErrorPayload(error, isDev),
+          }),
+          {
+            status,
+            headers: { "content-type": "application/json;charset=utf-8" },
+          },
+        );
+      }
+    }
+
+    // Non-JSON response routes: catch errors and return plain Response
+    try {
+      const result = await (preview.handler as Function)(responseHandlerCtx);
+
+      if (result instanceof Response) {
+        return rewrapResponse(result);
+      }
+
+      // Auto-wrap based on response type tag
+      switch (preview.responseType) {
+        case "text":
+          return createResponseWithMergedHeaders(String(result), {
+            status: 200,
+            headers: { "content-type": "text/plain;charset=utf-8" },
+          });
+        case "html":
+          return createResponseWithMergedHeaders(String(result), {
+            status: 200,
+            headers: { "content-type": "text/html;charset=utf-8" },
+          });
+        case "xml":
+          return createResponseWithMergedHeaders(String(result), {
+            status: 200,
+            headers: { "content-type": "application/xml;charset=utf-8" },
+          });
+        case "md":
+          return createResponseWithMergedHeaders(String(result), {
+            status: 200,
+            headers: { "content-type": "text/markdown;charset=utf-8" },
+          });
+        default:
+          // image, stream, any -- must return Response
+          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 status = error instanceof RouterError ? error.status : 500;
+      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) {
+      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,235 @@
+/**
+ * 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 } from "./ssr-setup.js";
+import type { RscPayload } 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;
+
+  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 = {
+        metadata: {
+          pathname: url.pathname,
+          segments: match.segments,
+          matched: match.matched,
+          diff: match.diff,
+          params: match.params,
+          isPartial: false,
+          rootLayout: ctx.router.rootLayout,
+          handles: handleStore.stream(),
+          version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+          themeConfig: ctx.router.themeConfig,
+          initialTheme: reqCtx.theme,
+        },
+      };
+    } else {
+      setRequestContextParams(result.params, result.routeName);
+
+      hasInterceptSlots = !!result.slots;
+
+      payload = {
+        metadata: {
+          pathname: url.pathname,
+          segments: result.segments,
+          matched: result.matched,
+          diff: result.diff,
+          params: result.params,
+          isPartial: true,
+          slots: result.slots,
+          handles: handleStore.stream(),
+          version: ctx.version,
+        },
+      };
+    }
+  } 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 = {
+        // Initial SSR can reconstruct the tree from segments + rootLayout,
+        // so we omit root to avoid sending the same structure twice.
+
+        metadata: {
+          pathname: url.pathname,
+          segments: match.segments,
+          matched: match.matched,
+          diff: match.diff,
+          params: match.params,
+          isPartial: false,
+          rootLayout: ctx.router.rootLayout,
+          handles: handleStore.stream(),
+          version: ctx.version,
+          themeConfig: ctx.router.themeConfig,
+          initialTheme: reqCtx.theme,
+        },
+      };
+    }
+  }
+
+  // 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);
+  const rscSerializeDur = performance.now() - rscSerializeStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  appendMetric(
+    metricsStore,
+    "rsc-serialize",
+    rscSerializeStart,
+    rscSerializeDur,
+  );
+
+  // Determine if this is an RSC request or HTML request.
+  // Partial requests (_rsc_partial) are always RSC -- they come from client-side
+  // navigation or prefetch fetch(). We cannot rely on Accept alone since some
+  // browsers may send Accept: text/html for non-HTML requests.
+  const isRscRequest =
+    isPartial ||
+    (!request.headers.get("accept")?.includes("text/html") &&
+      !url.searchParams.has("__html")) ||
+    url.searchParams.has("__rsc");
+
+  if (isRscRequest) {
+    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",
+    };
+    // 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,42 @@
+/**
+ * Runtime guardrail warnings (dev-only).
+ *
+ * W3: PE action redirect / Response handling.
+ */
+
+import {
+  createResponseWithMergedHeaders,
+  carryOverRedirectHeaders,
+} from "./helpers.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;
+  const location = value.headers.get("Location");
+  if (value.status >= 300 && value.status < 400 && location) {
+    const redirect = createResponseWithMergedHeaders(null, {
+      status: value.status,
+      headers: { Location: location },
+    });
+    carryOverRedirectHeaders(value, redirect);
+    return redirect;
+  }
+  return null;
+}
+
+/**
+ * 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.`,
+  );
+}