@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.130

package/src/rsc/helpers.ts

@@ -4,7 +4,90 @@
  * Utility functions for RSC request handling.
  */
 
-import { getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  getLocationState,
+} from "../server/request-context.js";
+import type { RequestContext } from "../server/request-context.js";
+import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import { isRedirectResponse } from "../response-utils.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
+import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+import { formatCacheSignalHeader } from "../router/telemetry.js";
+import type { RscPayload } from "./types.js";
+
+/**
+ * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
+ * match/matchPartial populate ctx._cacheSignal. Emit it as the X-Rango-Cache
+ * header. When the gate is off, ctx._cacheSignal is undefined and NOTHING is
+ * attached — output is byte-identical to the default. Header mutation failures
+ * are swallowed so immutable Response headers (e.g. protocol-switch) are safe.
+ */
+function applyCacheSignalHeader(target: Headers, ctx: RequestContext): void {
+  const signal = ctx._cacheSignal;
+  if (!signal || signal.length === 0) return;
+  try {
+    target.set("X-Rango-Cache", formatCacheSignalHeader(signal));
+  } catch {
+    // Headers immutable — skip.
+  }
+}
+
+/**
+ * Copy stub headers from the request context onto a target Headers instance:
+ * append Set-Cookie entries, set everything else only if absent. Header
+ * mutation failures are swallowed so the same logic works against Response
+ * headers that may be immutable (e.g. Cloudflare protocol-switch responses).
+ */
+function applyStubHeaders(target: Headers, stub: Headers): void {
+  stub.forEach((value, name) => {
+    try {
+      // The reserved external-redirect marker is internal and never a trust
+      // signal; never copy a stub value (e.g. a stray ctx.header() call) onto a
+      // browser-facing response. The opt-in is the out-of-band brand.
+      if (name.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
+      if (name.toLowerCase() === "set-cookie") {
+        target.append(name, value);
+      } else if (!target.has(name)) {
+        target.set(name, value);
+      }
+    } catch {
+      // Headers immutable — skip.
+    }
+  });
+}
+
+/**
+ * Drain ctx._onResponseCallbacks onto a response. Swapping the array before
+ * iteration prevents re-entrant registrations from double-firing and matches
+ * the contract that each callback runs at most once per request.
+ */
+function drainOnResponseCallbacks(
+  ctx: RequestContext,
+  response: Response,
+): Response {
+  const callbacks = ctx._onResponseCallbacks;
+  if (callbacks.length === 0) return response;
+  ctx._onResponseCallbacks = [];
+  // An onResponse callback may return a NEW Response (e.g. to add a header),
+  // which drops the out-of-band external-redirect brand (brand is keyed on
+  // Response object identity). Preserve a redirect(url, { external: true })
+  // opt-in across that rebuild so a callback can't silently neutralize the
+  // off-host redirect at the guard chokepoint.
+  const wasExternal = isExternalRedirect(response);
+  let result = response;
+  for (const callback of callbacks) {
+    result = callback(result) ?? result;
+  }
+  if (wasExternal && !isExternalRedirect(result)) {
+    markExternalRedirect(result);
+  }
+  return result;
+}
 
 /**
  * Check if a request body has content to decode
@@ -27,38 +110,205 @@ export function hasBodyContent(body: FormData | string): boolean {
  */
 export function createResponseWithMergedHeaders(
   body: BodyInit | null,
-  init: ResponseInit
+  init: ResponseInit,
 ): Response {
-  const ctx = getRequestContext();
+  const ctx = _getRequestContext();
   if (!ctx) {
     return new Response(body, init);
   }
 
-  // Merge headers from stub response into the new response
+  // Delete Set-Cookie from the stub after consuming so downstream merge
+  // points (e.g. executeMiddleware) don't duplicate them.
   const mergedHeaders = new Headers(init.headers);
-  ctx.res.headers.forEach((value, name) => {
-    if (name.toLowerCase() === "set-cookie") {
-      mergedHeaders.append(name, value);
-    } else if (!mergedHeaders.has(name)) {
-      // Only set if not already present in init.headers
-      mergedHeaders.set(name, value);
-    }
-  });
+  applyStubHeaders(mergedHeaders, ctx.res.headers);
+  ctx.res.headers.delete("set-cookie");
+  applyCacheSignalHeader(mergedHeaders, ctx);
 
-  // Use ctx.res.status if it was set (e.g., 404 for notFound, 500 for error)
-  // Otherwise use the status from init
+  // ctx.res.status overrides init.status when explicitly set (e.g. 404 for
+  // notFound, 500 for error). Default ctx.res.status is 200.
   const status = ctx.res.status !== 200 ? ctx.res.status : init.status;
 
-  let response = new Response(body, {
+  const response = new Response(body, {
     ...init,
     status,
     headers: mergedHeaders,
   });
 
-  // Run onResponse callbacks - each can inspect/modify the response
-  for (const callback of ctx._onResponseCallbacks) {
-    response = callback(response) ?? response;
+  return drainOnResponseCallbacks(ctx, response);
+}
+
+/**
+ * Create a 204 response with X-RSC-Redirect header for stateless redirects.
+ * Used during partial/action requests where fetch would auto-follow a raw
+ * 3xx to a URL that renders full HTML instead of Flight data. The 204 status
+ * prevents auto-follow; the client reads the header and re-navigates via
+ * the router.
+ */
+export function createSimpleRedirectResponse(redirectUrl: string): Response {
+  return createResponseWithMergedHeaders(null, {
+    status: 204,
+    headers: { "X-RSC-Redirect": redirectUrl },
+  });
+}
+
+/**
+ * Carry over headers from a source redirect Response to a wrapper Response.
+ * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper) and
+ * appends Set-Cookie to avoid clobbering multiple cookie headers.
+ *
+ * This is a GENERIC copier used by every redirect-rebuild path (PE
+ * extractRedirectResponse, the SPA intercept below, the guard's neutralize
+ * rebuild), so it has two redirect-specific jobs:
+ *
+ * 1. NEVER copy the reserved external-redirect header: it is no longer a trust
+ *    signal (the opt-in is the out-of-band brand), and a forged value from a
+ *    proxied upstream must not ride a rebuilt response to the browser.
+ * 2. Transfer the out-of-band external brand: a rebuilt document-native redirect
+ *    has to carry the opt-in to the guard chokepoint, which reads and clears it.
+ *    Without this transfer, redirect(url, { external: true }) would be silently
+ *    neutralized on any rebuild path (fail-closed, but a feature regression).
+ */
+export function carryOverRedirectHeaders(
+  source: Response,
+  target: Response,
+): void {
+  source.headers.forEach((value, name) => {
+    const lower = name.toLowerCase();
+    if (lower === "location" || lower === "x-rsc-redirect") return;
+    if (lower === EXTERNAL_REDIRECT_MARKER) return;
+    if (lower === "set-cookie") {
+      target.headers.append(name, value);
+    } else if (!target.headers.has(name)) {
+      target.headers.set(name, value);
+    }
+  });
+  if (isExternalRedirect(source)) {
+    markExternalRedirect(target);
+  }
+}
+
+/**
+ * If a response is a 3xx redirect during a partial (client-side) request,
+ * intercept it and return a Flight-compatible redirect instead.
+ * fetch() auto-follows 3xx which would hit a URL that renders full HTML
+ * the client can't parse. Returns null if the response is not a redirect.
+ */
+export function interceptRedirectForPartial(
+  response: Response,
+  createRedirectFlightResponse: (
+    redirectUrl: string,
+    locationState?: Record<string, unknown>,
+    external?: boolean,
+  ) => Response,
+): Response | null {
+  if (!isRedirectResponse(response)) {
+    return null;
+  }
+  const redirectUrl = response.headers.get("Location")!;
+  // redirect(url, { external: true }) marks an explicit off-host redirect via
+  // the out-of-band brand (not a wire header). On the SPA/action channel the
+  // intent must travel as a Flight payload (metadata.redirect.external) so the
+  // client does a scheme-validated hard navigation (location.assign) rather than
+  // a partial fetch. The client re-validates the scheme; see partial-update.ts.
+  const external = isExternalRedirect(response);
+  const locationState = getLocationState();
+  let intercepted: Response;
+  if (locationState) {
+    intercepted = createRedirectFlightResponse(
+      redirectUrl,
+      resolveLocationStateEntries(locationState),
+      external,
+    );
+  } else if (external) {
+    intercepted = createRedirectFlightResponse(redirectUrl, undefined, true);
+  } else {
+    intercepted = createSimpleRedirectResponse(redirectUrl);
+  }
+
+  carryOverRedirectHeaders(response, intercepted);
+  // Defense-in-depth at the SPA browser-facing exit: carryOverRedirectHeaders
+  // already refuses to copy the reserved marker, but strip any value that might
+  // exist on `intercepted` so a forged header can never ride the 200/204 to the
+  // browser. The external intent travels in metadata.redirect.external (Flight),
+  // where the client re-validates the scheme.
+  try {
+    intercepted.headers.delete(EXTERNAL_REDIRECT_MARKER);
+  } catch {
+    // Immutable headers: the marker was never copied here, so this is inert.
+  }
+
+  return intercepted;
+}
+
+/**
+ * Attach location state set during a request to a payload's metadata.
+ * No-op if no location state was set. Callers must ensure payload.metadata
+ * is populated (the non-null assertion holds for the partial/action payloads
+ * that reach this helper).
+ */
+export function attachLocationStateIfPresent(payload: RscPayload): void {
+  const locationState = getLocationState();
+  if (locationState) {
+    payload.metadata!.locationState =
+      resolveLocationStateEntries(locationState);
   }
+}
 
-  return response;
+/**
+ * Only cache successful responses. Non-200 statuses (errors, redirects) are
+ * not cached -- notFound() produces 500 in response routes, and explicit
+ * non-200 Responses are rare enough that caching them would be surprising.
+ */
+export function isCacheableStatus(status: number): boolean {
+  return status === 200;
+}
+
+/**
+ * Convert route-level middleware entries to the format expected by
+ * executeMiddleware. Route middleware from previewMatch carries just
+ * { handler, params }; this wraps them in the full MiddlewareEntry shape.
+ */
+export function buildRouteMiddlewareEntries<TEnv>(
+  routeMiddleware: Array<{
+    handler: MiddlewareFn;
+    params: Record<string, string>;
+  }>,
+): Array<{ entry: MiddlewareEntry<TEnv>; params: Record<string, string> }> {
+  return routeMiddleware.map((mw) => ({
+    entry: {
+      pattern: null,
+      regex: null,
+      paramNames: [],
+      handler: mw.handler,
+    } as MiddlewareEntry<TEnv>,
+    params: mw.params,
+  }));
+}
+
+/**
+ * Merge stub headers from the request context onto an existing Response in
+ * place, then drain onResponse callbacks. Used when a Response cannot flow
+ * through `new Response()` — status 101 is outside the constructor's
+ * 200-599 range, and the Cloudflare-specific `webSocket` property would be
+ * lost on reconstruction.
+ */
+export function mergeStubHeadersAndFinalize(response: Response): Response {
+  const ctx = _getRequestContext();
+  if (!ctx) return response;
+
+  applyStubHeaders(response.headers, ctx.res.headers);
+  ctx.res.headers.delete("set-cookie");
+
+  return drainOnResponseCallbacks(ctx, response);
+}
+
+/**
+ * Run onResponse callbacks on an existing Response. Used by code paths that
+ * bypass createResponseWithMergedHeaders (e.g. middleware short-circuits)
+ * but still need ctx.onResponse() callbacks to fire.
+ */
+export function finalizeResponse(response: Response): Response {
+  const ctx = _getRequestContext();
+  if (!ctx) return response;
+  return drainOnResponseCallbacks(ctx, response);
 }

package/src/rsc/index.ts

@@ -1,5 +1,5 @@
 /**
- * RSC Router - RSC Entry Point
+ * Rango - RSC Entry Point
  *
  * This module provides RSC utilities for server-side rendering,
  * server actions, loader fetching, and progressive enhancement.
@@ -29,28 +29,8 @@ export type {
   NonceProvider,
 } from "./types.js";
 
-// Re-export HandleStore types for consumers who need custom handling
-export {
-  createHandleStore,
-  type HandleStore,
-  type HandleData,
-} from "../server/handle-store.js";
-
 // Re-export request context utilities for server-side access to env/request/params
 export {
   getRequestContext,
   requireRequestContext,
-  setRequestContextParams,
 } from "../server/request-context.js";
-
-// Re-export cache store types and implementations
-export type {
-  SegmentCacheStore,
-  CachedEntryData,
-  CachedEntryResult,
-  SegmentCacheProvider,
-  SegmentHandleData,
-} from "../cache/types.js";
-
-export { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
-export { CFCacheStore, type CFCacheStoreOptions } from "../cache/cf/index.js";

package/src/rsc/json-route-result.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared serialization for `json()` response-route results.
+ *
+ * Kept in its own lightweight module (depends only on `errors.js`) so the
+ * `dispatch()` testing primitive can import it WITHOUT dragging in
+ * `response-route-handler.ts`'s heavy runtime graph, which transitively reaches
+ * a Vite virtual module and breaks a plain (non-Vite) vitest import.
+ */
+
+import { RouterError } from "../errors.js";
+
+/**
+ * Serialize a `json()` response-route result, rejecting a nested unresolved
+ * Promise (the forgotten-await footgun: `() => ({ data: fetchSomething() })`).
+ * `JSON.stringify` would silently emit `{}` for a Promise, shipping empty data;
+ * the RSC pipeline awaits nested promises but this path does not. Throwing
+ * `RESPONSE_NOT_SERIALIZABLE` makes the failure loud.
+ *
+ * Shared by the production response-route handler and the `dispatch()` testing
+ * primitive so a `dispatch` json test of a forgotten await fails exactly where
+ * production 500s, instead of going green.
+ */
+export function stringifyJsonRouteResult(result: unknown): string {
+  return 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;
+  });
+}

package/src/rsc/loader-fetch.ts

@@ -0,0 +1,235 @@
+/**
+ * Loader Fetch Handler
+ *
+ * Handles load() requests (GET, POST, PUT, PATCH, DELETE) from the client.
+ * All loader data fetching and mutations go through this endpoint.
+ *
+ * Route params (e.g. slug from /blog/:slug) come from previewMatch() in the
+ * outer coreRequestHandler, threaded through coreRequestHandlerInner as
+ * routeParams. This is necessary because handleLoaderFetch doesn't do its
+ * own route matching -- the URL is the page's pathname, and previewMatch
+ * has already extracted params from it.
+ */
+
+import { getLoaderLazy } from "../server/loader-registry.js";
+import { executeLoaderMiddleware } from "../router/middleware.js";
+import { requireRequestContext } from "../server/request-context.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import {
+  getGlobalRouteMap,
+  getSearchSchema,
+  isRouteRootScoped,
+} from "../route-map-builder.js";
+import { parseSearchParams } from "../search-params.js";
+import {
+  createResponseWithMergedHeaders,
+  finalizeResponse,
+} from "./helpers.js";
+import type { HandlerContext } from "./handler-context.js";
+
+export async function handleLoaderFetch<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  variables: Record<string, any>,
+  routeParams?: Record<string, string>,
+): Promise<Response> {
+  const loaderId = url.searchParams.get("_rsc_loader");
+
+  if (!loaderId) {
+    return createResponseWithMergedHeaders("Missing _rsc_loader parameter", {
+      status: 400,
+    });
+  }
+
+  // Look up loader lazily
+  const registeredLoader = await getLoaderLazy(loaderId);
+  if (!registeredLoader) {
+    return createResponseWithMergedHeaders(
+      `Loader "${loaderId}" not found in registry`,
+      { status: 404 },
+    );
+  }
+
+  // Non-fetchable loaders are registered for SSR ctx.use() only.
+  // They must not be callable through the standalone _rsc_loader endpoint.
+  if (!registeredLoader.fetchable) {
+    return createResponseWithMergedHeaders(
+      `Loader "${loaderId}" is not fetchable`,
+      { status: 403 },
+    );
+  }
+
+  // Parse params, body, and formData based on request method and content type
+  let loaderParams: Record<string, string> = {};
+  let loaderBody: unknown = undefined;
+  let loaderFormData: FormData | undefined;
+  const isBodyMethod = request.method !== "GET" && request.method !== "HEAD";
+
+  if (isBodyMethod) {
+    try {
+      const contentType = request.headers.get("content-type") || "";
+      if (contentType.includes("multipart/form-data")) {
+        // FormData body — sent by load() when body is a FormData instance.
+        // Preserves File objects and binary data.
+        loaderFormData = await request.formData();
+        // Extract params if provided via the special field
+        const paramsField = loaderFormData.get("_rsc_loader_params");
+        if (typeof paramsField === "string") {
+          loaderParams = JSON.parse(paramsField);
+          loaderFormData.delete("_rsc_loader_params");
+        }
+      } else if (contentType.includes("application/json")) {
+        const jsonBody = (await request.json()) as {
+          params?: Record<string, string>;
+          body?: unknown;
+        };
+        loaderParams = jsonBody.params ?? {};
+        loaderBody = jsonBody.body;
+      }
+    } catch {
+      return createResponseWithMergedHeaders("Invalid request body", {
+        status: 400,
+      });
+    }
+  } else {
+    const loaderParamsJson = url.searchParams.get("_rsc_loader_params");
+    if (loaderParamsJson) {
+      try {
+        loaderParams = JSON.parse(loaderParamsJson);
+      } catch {
+        return createResponseWithMergedHeaders(
+          "Invalid _rsc_loader_params JSON",
+          { status: 400 },
+        );
+      }
+    }
+  }
+
+  // Execute the loader with middleware.
+  // finalizeResponse drains onResponse callbacks that middleware short-circuits
+  // may leave behind (executeLoaderMiddleware does not finalize them itself).
+  try {
+    const { fn, middleware } = registeredLoader;
+
+    return finalizeResponse(
+      await executeLoaderMiddleware(
+        middleware,
+        request,
+        env,
+        loaderParams,
+        variables,
+        async () => {
+          const reqCtx = requireRequestContext();
+          // Merge route params (from previewMatch) with explicit loader params.
+          // Explicit params take precedence over route-matched params.
+          const resolvedRouteParams = routeParams ?? {};
+          const mergedParams = {
+            ...resolvedRouteParams,
+            ...loaderParams,
+          };
+          // Strip _rsc_* transport params so loaders see the same
+          // url/searchParams as during SSR/navigation.
+          const cleanUrl = stripInternalParams(url);
+          const cleanSearchParams = cleanUrl.searchParams;
+          const searchSchema = reqCtx._routeName
+            ? getSearchSchema(reqCtx._routeName)
+            : undefined;
+          const loaderCtx: any = {
+            ...reqCtx,
+            url: cleanUrl,
+            pathname: cleanUrl.pathname,
+            searchParams: cleanSearchParams,
+            search: searchSchema
+              ? parseSearchParams(cleanSearchParams, searchSchema)
+              : {},
+            params: mergedParams,
+            routeParams: resolvedRouteParams,
+            body: loaderBody,
+            method: request.method,
+            reverse: createReverseFunction(
+              getGlobalRouteMap(),
+              reqCtx._routeName,
+              mergedParams,
+              reqCtx._routeName
+                ? isRouteRootScoped(reqCtx._routeName)
+                : undefined,
+            ),
+            ...(loaderFormData ? { formData: loaderFormData } : {}),
+          };
+
+          // Meter the fetchable-loader execution via observePhase, the sole
+          // funnel for this path (fn is called directly, not via ctx.use).
+          // depth:1 — a fetchable request has no render-phase parent.
+          const result = await observePhase(PHASES.loader(loaderId, 1), () =>
+            fn(loaderCtx),
+          );
+
+          interface LoaderPayload {
+            loaderResult: unknown;
+          }
+          const loaderPayload: LoaderPayload = { loaderResult: result };
+          const rscStream = ctx.renderToReadableStream<LoaderPayload>(
+            loaderPayload,
+            {
+              onError: (error: unknown) => {
+                ctx.callOnError(error, "rendering", {
+                  request,
+                  url,
+                  env,
+                  loaderName: loaderId,
+                });
+              },
+            },
+          );
+
+          return createResponseWithMergedHeaders(rscStream, {
+            headers: { "content-type": "text/x-component;charset=utf-8" },
+          });
+        },
+        createReverseFunction(ctx.getRequiredRouteMap()),
+      ),
+    );
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const isDev = process.env.NODE_ENV !== "production";
+
+    console.error("[RSC] Loader error:", error);
+
+    ctx.callOnError(error, "loader", {
+      request,
+      url,
+      env,
+      loaderName: loaderId,
+      handledByBoundary: false,
+    });
+
+    const errorPayload = {
+      loaderResult: null,
+      loaderError: {
+        message: isDev ? err.message : "An error occurred",
+        name: err.name,
+      },
+    };
+    const rscStream = ctx.renderToReadableStream(errorPayload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", {
+          request,
+          url,
+          env,
+          loaderName: loaderId,
+        });
+      },
+    });
+
+    return createResponseWithMergedHeaders(rscStream, {
+      status: 500,
+      headers: { "content-type": "text/x-component;charset=utf-8" },
+    });
+  }
+}