@rangojs/router 0.0.0-experimental.tapabs2 → 0.1.0

package/src/rsc/handler.ts

@@ -30,7 +30,13 @@ import {
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import { renderRscFlightStage, renderRscResponse } from "./render-pipeline.js";
 import { guardOutgoingRedirect } from "./redirect-guard.js";
+import {
+  resolveSoftRedirectUrl,
+  resolveExternalRedirect,
+  safeSameOriginLanding,
+} from "../redirect-origin.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import {
   isWebSocketUpgradeResponse,
@@ -52,8 +58,6 @@ import {
 import { contextSet } from "../context-var.js";
 import {
   hasCachedManifest,
-  getRouteTrie,
-  getPrecomputedEntries,
   waitForManifestReady,
   getRouterManifest,
   getRouterTrie,
@@ -76,9 +80,11 @@ import {
 import { handleRscRendering } from "./rsc-rendering.js";
 import {
   withTimeout,
+  isTimeoutEnabled,
   RouterTimeoutError,
   createDefaultTimeoutResponse,
   type TimeoutPhase,
+  type RenderTimeoutContext,
 } from "../router/timeout.js";
 import {
   createMetricsStore,
@@ -89,7 +95,7 @@ import { observePhase, PHASES } from "../router/instrument.js";
 import { safeEmit, resolveSink, getRequestId } from "../router/telemetry.js";
 import {
   startSSRSetup,
-  getSSRSetup,
+  createSsrHtmlStage,
   mayNeedSSR,
   isRscRequest,
   SSR_SETUP_VAR,
@@ -236,7 +242,25 @@ export function createRSCHandler<
     actionId?: string,
   ): Promise<Response> {
     const timeoutError = new RouterTimeoutError(phase, durationMs);
+    const cursor = _getRequestContext<TEnv>()?._renderForeground;
+    const render: RenderTimeoutContext | undefined =
+      phase === "render-start" && cursor
+        ? {
+            mode: cursor.mode,
+            phase: cursor.phase,
+            state: cursor.state,
+            completed: cursor.completed,
+            total: cursor.total,
+            ...(cursor.phaseStartedAt !== undefined && {
+              phaseDurationMs: performance.now() - cursor.phaseStartedAt,
+            }),
+          }
+        : undefined;
 
+    // Each surface gets its OWN shallow copy of the snapshot. onError, telemetry,
+    // and onTimeout are independent consumers; a consumer that mutates its
+    // `render` (e.g. an onError redacting metadata) must not corrupt what the
+    // other two observe.
     callOnError(timeoutError, phase === "action" ? "action" : "handler", {
       request,
       url,
@@ -244,7 +268,12 @@ export function createRSCHandler<
       routeKey,
       actionId,
       handledByBoundary: false,
-      metadata: { timeout: true, phase, durationMs },
+      metadata: {
+        timeout: true,
+        phase,
+        durationMs,
+        ...(render && { render: { ...render } }),
+      },
     });
 
     if (router.telemetry) {
@@ -258,6 +287,7 @@ export function createRSCHandler<
         actionId,
         durationMs,
         customHandler: !!router.onTimeout,
+        ...(render && { render: { ...render } }),
       });
     }
 
@@ -271,6 +301,7 @@ export function createRSCHandler<
           routeKey,
           actionId,
           durationMs,
+          ...(render && { render: { ...render } }),
         });
       } catch (e) {
         if (process.env.NODE_ENV !== "production") {
@@ -287,31 +318,66 @@ export function createRSCHandler<
    * Build a 200 Flight response that carries a redirect URL and optional state.
    * Used when a partial/action request results in a redirect -- fetch
    * auto-follows 3xx so we send the redirect as payload metadata instead.
+   *
+   * The redirect URL is resolved with {@link resolveSoftRedirectUrl} against
+   * the current request origin so an unsafe target never leaves as Flight
+   * metadata (client validators remain defense-in-depth).
    */
   function createRedirectFlightResponse(
     redirectUrl: string,
     locationState?: Record<string, unknown>,
     external?: boolean,
   ): Response {
+    const reqCtx = _getRequestContext<TEnv>();
+    const requestOrigin =
+      reqCtx?.url.origin ?? new URL("http://localhost").origin;
+    // Resolve with the same policy as 3xx guardOutgoingRedirect. Keep
+    // external:true only when the external scheme check passed; a neutralized
+    // landing (javascript:/blocked) must not advertise external.
+    let resolvedUrl: string;
+    let resolvedExternal = false;
+    if (external) {
+      const ext = resolveExternalRedirect(redirectUrl, requestOrigin);
+      if (ext !== null) {
+        resolvedUrl = ext;
+        resolvedExternal = true;
+      } else {
+        resolvedUrl = safeSameOriginLanding(router.basename);
+      }
+    } else {
+      resolvedUrl = resolveSoftRedirectUrl(
+        redirectUrl,
+        requestOrigin,
+        router.basename,
+        false,
+      );
+    }
     const redirectPayload: RscPayload = {
       metadata: {
-        pathname: redirectUrl,
+        pathname: resolvedUrl,
         segments: [],
-        redirect: { url: redirectUrl, ...(external && { external: true }) },
+        redirect: {
+          url: resolvedUrl,
+          ...(resolvedExternal && { external: true }),
+        },
         ...(locationState && { locationState }),
       },
     };
-    const rscStream = renderToReadableStream<RscPayload>(redirectPayload, {
-      onError: (error: unknown) => {
-        const reqCtx = _getRequestContext<TEnv>();
-        if (!reqCtx) return;
-        callOnError(error, "rendering", {
+    const rscStream = reqCtx
+      ? renderRscFlightStage({
+          ctx: { renderToReadableStream, callOnError },
           request: reqCtx.request,
           url: reqCtx.url,
           env: reqCtx.env,
-        });
-      },
-    });
+          payload: redirectPayload,
+          tracking: {
+            mode: reqCtx.url.searchParams.has("_rsc_action")
+              ? "action-revalidation"
+              : "partial",
+            routeKey: reqCtx._routeName,
+          },
+        }).stream
+      : renderToReadableStream<RscPayload>(redirectPayload);
     return createResponseWithMergedHeaders(rscStream, {
       status: 200,
       headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -466,6 +532,12 @@ export function createRSCHandler<
       stateCookieName: router.resolvedStateCookieName,
       version,
     });
+    // Gate on the SAME enabled-semantics withTimeout uses (isTimeoutEnabled):
+    // a `renderStartMs: 0` / negative opt-out disables the timeout, so the
+    // driver's cursor bookkeeping (which only the timeout reads) must be off too.
+    requestContext._renderDiagnosticsEnabled = isTimeoutEnabled(
+      router.timeouts.renderStartMs,
+    );
     // Thread the true request entry timestamp onto the context so a metrics
     // store created MID-request (ctx.debugPerformance() / getMetricsStore) anchors
     // to the real start, not the opt-in moment — phases that began earlier then
@@ -554,6 +626,7 @@ export function createRSCHandler<
             const intercepted = interceptRedirectForPartial(
               mwResponse,
               createRedirectFlightResponse,
+              { requestOrigin: url.origin, basename: router.basename },
             );
             response = intercepted ?? finalizeResponse(mwResponse);
           } else {
@@ -632,35 +705,6 @@ export function createRSCHandler<
   ): Promise<Response> {
     const handlerTiming: string[] = variables.__handlerTiming || [];
 
-    // Debug manifest endpoint: handled before classification since it
-    // doesn't need a route match and needs trie access from the closure.
-    const isDev = process.env.NODE_ENV !== "production";
-    if (
-      url.searchParams.has("__debug_manifest") &&
-      (isDev || router.allowDebugManifest)
-    ) {
-      const trie = getRouterTrie(router.id) ?? getRouteTrie();
-      const routeManifest = getRequiredRouteMap();
-      const { extractAncestryFromTrie } =
-        await import("../build/route-trie.js");
-      return new Response(
-        JSON.stringify(
-          {
-            routerId: router.id,
-            routeManifest,
-            routeAncestry: trie ? extractAncestryFromTrie(trie) : {},
-            routeTrie: trie,
-            precomputedEntries: getPrecomputedEntries(),
-          },
-          null,
-          2,
-        ),
-        {
-          headers: { "Content-Type": "application/json" },
-        },
-      );
-    }
-
     // ---- 1. Classify ----
     // classifyRequest may throw RouteNotFoundError for unknown routes.
     // In that case, fall through to a full-render plan so the pipeline
@@ -885,14 +929,16 @@ export function createRSCHandler<
     // submissions always render HTML (handleProgressiveEnhancement renders via
     // getSSRSetup regardless of Accept). For full/partial-render and action,
     // the render-time HTML decision is exactly !isRscRequest — mayNeedSSR is
-    // the coarse transport pre-filter, isRscRequest is the precise Accept call
-    // (it, unlike mayNeedSSR, treats a MISSING Accept as RSC). Both must pass.
+    // the coarse transport pre-filter, isRscRequest adds the partial/__rsc
+    // flags; both share the same Accept rule (acceptsFlightExplicitly in
+    // ssr-setup.ts), so the Accept call cannot drift between them. Both must
+    // pass.
     const willRenderHtml =
       plan.mode === "pe-render" ||
       (mayNeedSSR(request, url) &&
         !isRscRequest(request, url, plan.mode === "partial-render"));
     if (plan.mode !== "loader" && willRenderHtml) {
-      variables[SSR_SETUP_VAR] = startSSRSetup(
+      const ssrSetup = startSSRSetup(
         handlerCtx,
         request,
         env,
@@ -901,6 +947,15 @@ export function createRSCHandler<
           ? () => getRequestContext()._metricsStore
           : undefined,
       );
+      variables[SSR_SETUP_VAR] = ssrSetup;
+
+      // A handler can short-circuit before HTML rendering consumes this promise
+      // (for example, by returning a redirect). Workerd cancels untracked dynamic
+      // imports at the request boundary; retaining that cancelled promise in the
+      // production SSR module memo makes every later document request hang.
+      // Extending the request lifetime lets the shared setup settle without
+      // delaying the short-circuit response.
+      getRequestContext().executionContext?.waitUntil(ssrSetup);
     }
 
     // ---- Loader fetch ----
@@ -1107,6 +1162,7 @@ export function createRSCHandler<
             const intercepted = interceptRedirectForPartial(
               error,
               createRedirectFlightResponse,
+              { requestOrigin: url.origin, basename: router.basename },
             );
             if (intercepted) return intercepted;
           }
@@ -1169,40 +1225,57 @@ export function createRSCHandler<
             },
           };
 
-          const rscStream = renderToReadableStream(payload, {
-            onError: (error: unknown) => {
-              callOnError(error, "rendering", { request, url, env });
-            },
-          });
-
-          if (isRscRequest(request, url, isPartial)) {
-            return createResponseWithMergedHeaders(rscStream, {
-              status: 404,
-              headers: {
-                "content-type": "text/x-component;charset=utf-8",
-                // Router identity for the client's pre-decode integrity check; a
-                // same-app 404 matches and applies in place. See response-adapter.
-                "X-RSC-Router-Id": router.id,
-              },
-            });
-          }
-
-          const [ssrModule, streamMode] = await getSSRSetup(
-            handlerCtx,
+          const isNotFoundFlightResponse = isRscRequest(
             request,
-            env,
             url,
-            getRequestContext()._metricsStore,
+            isPartial,
+          );
+          const notFoundStageTracking = {
+            mode: isPartial ? ("partial" as const) : ("full" as const),
+            routeKey,
+          };
+          return renderRscResponse(
+            {
+              ctx: { renderToReadableStream, callOnError },
+              request,
+              url,
+              env,
+              payload,
+              // The 404 path historically records no rsc-serialize metric (it
+              // used the standalone Flight constructor, whose gate was opt-in);
+              // opt out explicitly since renderRscResponse defaults the gate on.
+              recordSerializeMetric: false,
+              init: isNotFoundFlightResponse
+                ? {
+                    status: 404,
+                    headers: {
+                      "content-type": "text/x-component;charset=utf-8",
+                      // Router identity for the client's pre-decode integrity
+                      // check; a same-app 404 applies in place.
+                      "X-RSC-Router-Id": router.id,
+                    },
+                  }
+                : {
+                    status: 404,
+                    headers: {
+                      "content-type": "text/html;charset=utf-8",
+                    },
+                  },
+              tracking: notFoundStageTracking,
+            },
+            isNotFoundFlightResponse
+              ? undefined
+              : {
+                  html: createSsrHtmlStage({
+                    ctx: handlerCtx,
+                    request,
+                    env,
+                    url,
+                    metricsStore: getRequestContext()._metricsStore,
+                    render: { nonce },
+                  }),
+                },
           );
-          const htmlStream = await ssrModule.renderHTML(rscStream, {
-            nonce,
-            streamMode,
-          });
-
-          return createResponseWithMergedHeaders(htmlStream, {
-            status: 404,
-            headers: { "content-type": "text/html;charset=utf-8" },
-          });
         }
 
         // Report unhandled errors
@@ -1233,6 +1306,7 @@ export function createRSCHandler<
           const intercepted = interceptRedirectForPartial(
             mwResponse,
             createRedirectFlightResponse,
+            { requestOrigin: url.origin, basename: router.basename },
           );
           if (intercepted) return intercepted;
         }

package/src/rsc/helpers.ts

@@ -10,11 +10,15 @@ import {
 } 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 {
+  isRedirectResponse,
+  isWebSocketUpgradeResponse,
+} from "../response-utils.js";
 import {
   EXTERNAL_REDIRECT_MARKER,
   isExternalRedirect,
   markExternalRedirect,
+  resolveSoftRedirectUrl,
 } from "../redirect-origin.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import { formatCacheSignalHeader } from "../router/telemetry.js";
@@ -84,6 +88,14 @@ export function drainOnResponseCallbacks(
   // 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.
+  return applyOnResponseCallbacks(callbacks, response);
+}
+
+/** Apply a saved callback batch while preserving an external-redirect brand. */
+export function applyOnResponseCallbacks(
+  callbacks: Array<(response: Response) => Response>,
+  response: Response,
+): Response {
   const wasExternal = isExternalRedirect(response);
   let result = response;
   for (const callback of callbacks) {
@@ -143,17 +155,63 @@ export function createResponseWithMergedHeaders(
   return drainOnResponseCallbacks(ctx, response);
 }
 
+/**
+ * Rebuild a Response returned or thrown by a response-route handler so request
+ * effects merge consistently in production and the public dispatch primitive.
+ */
+export function rewrapResponseRouteResponse(result: Response): Response {
+  if (isWebSocketUpgradeResponse(result)) {
+    return mergeStubHeadersAndFinalize(result);
+  }
+  const headers = new Headers();
+  result.headers.forEach((value, key) => {
+    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,
+  });
+  if (isExternalRedirect(result)) {
+    markExternalRedirect(rewrapped);
+  }
+  return rewrapped;
+}
+
+/** Origin/basename needed to resolve soft redirect targets server-side. */
+export type SoftRedirectResolveOpts = {
+  requestOrigin: string;
+  basename?: string;
+};
+
 /**
  * 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.
+ *
+ * The header value is resolved with {@link resolveSoftRedirectUrl} so a
+ * cross-origin / unsafe-scheme target is neutralized before it leaves the
+ * server (defense-in-depth; client validators still run).
  */
-export function createSimpleRedirectResponse(redirectUrl: string): Response {
+export function createSimpleRedirectResponse(
+  redirectUrl: string,
+  opts: SoftRedirectResolveOpts & { external?: boolean },
+): Response {
+  const resolved = resolveSoftRedirectUrl(
+    redirectUrl,
+    opts.requestOrigin,
+    opts.basename,
+    opts.external,
+  );
   return createResponseWithMergedHeaders(null, {
     status: 204,
-    headers: { "X-RSC-Redirect": redirectUrl },
+    headers: { "X-RSC-Redirect": resolved },
   });
 }
 
@@ -198,6 +256,10 @@ export function carryOverRedirectHeaders(
  * 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.
+ *
+ * Soft redirect targets are resolved server-side (same-origin / external
+ * scheme rules) via `opts` before they are written into X-RSC-Redirect or
+ * handed to the Flight factory.
  */
 export function interceptRedirectForPartial(
   response: Response,
@@ -206,6 +268,7 @@ export function interceptRedirectForPartial(
     locationState?: Record<string, unknown>,
     external?: boolean,
   ) => Response,
+  opts: SoftRedirectResolveOpts,
 ): Response | null {
   if (!isRedirectResponse(response)) {
     return null;
@@ -228,7 +291,7 @@ export function interceptRedirectForPartial(
   } else if (external) {
     intercepted = createRedirectFlightResponse(redirectUrl, undefined, true);
   } else {
-    intercepted = createSimpleRedirectResponse(redirectUrl);
+    intercepted = createSimpleRedirectResponse(redirectUrl, opts);
   }
 
   carryOverRedirectHeaders(response, intercepted);

package/src/rsc/progressive-enhancement.ts

@@ -10,7 +10,7 @@ import {
   getRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
-import { getSSRSetup } from "./ssr-setup.js";
+import { createSsrHtmlStage } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -22,6 +22,7 @@ import {
   finalizeResponse,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import { renderRscResponse } from "./render-pipeline.js";
 import type { HandlerContext } from "./handler-context.js";
 import {
   extractRedirectResponse,
@@ -327,39 +328,44 @@ export async function handleProgressiveEnhancement<TEnv>(
       },
     };
 
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
+    const stageTracking = {
+      mode: "progressive-enhancement" as const,
+      routeKey: getRequestContext()._routeName,
+      actionId: directActionId ?? undefined,
+    };
+    return renderRscResponse(
+      {
+        ctx,
+        request,
+        env,
+        url,
+        payload,
+        init: {
+          // boundarylessErrorStatus is set only when the action threw and no error
+          // boundary matched; it makes the re-render carry 500 like the JS path.
+          // The redirect branch above returns before this, so a redirect re-render
+          // keeps its 308 and is never overridden.
+          ...(boundarylessErrorStatus !== undefined
+            ? { status: boundarylessErrorStatus }
+            : {}),
+          headers: { "content-type": "text/html;charset=utf-8" },
+        },
+        tracking: stageTracking,
+      },
+      {
+        // metricsStore=undefined is safe: the handler already stashed the early
+        // SSR setup promise, so this reuses it instead of starting setup again.
+        // reactFormState travels through the SSR option, not RscPayload.
+        html: createSsrHtmlStage({
+          ctx,
+          request,
+          env,
+          url,
+          metricsStore: undefined,
+          render: { formState: reactFormState, nonce },
+        }),
       },
-    });
-    // metricsStore=undefined is safe: the handler already stashed the early
-    // SSR setup promise on request variables, so getSSRSetup returns it
-    // without falling back to a fresh startSSRSetup.
-    const [ssrModule, streamMode] = await getSSRSetup(
-      ctx,
-      request,
-      env,
-      url,
-      undefined,
     );
-    // reactFormState carries the useActionState payload via the SSR-option path
-    // (renderToReadableStream({ formState })); it does NOT travel on RscPayload.
-    const htmlStream = await ssrModule.renderHTML(rscStream, {
-      formState: reactFormState,
-      nonce,
-      streamMode,
-    });
-
-    return createResponseWithMergedHeaders(htmlStream, {
-      // boundarylessErrorStatus is set only when the action threw and no error
-      // boundary matched; it makes the re-render carry 500 like the JS path.
-      // The redirect branch above returns before this, so a redirect re-render
-      // keeps its 308 and is never overridden.
-      ...(boundarylessErrorStatus !== undefined
-        ? { status: boundarylessErrorStatus }
-        : {}),
-      headers: { "content-type": "text/html;charset=utf-8" },
-    });
   };
 
   // Execute route middleware wrapping the render, if any.
@@ -475,28 +481,34 @@ async function renderPeErrorBoundary<TEnv>(
     },
   };
 
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-    onError: (error: unknown) => {
-      ctx.callOnError(error, "rendering", { request, url, env });
+  const stageTracking = {
+    mode: "progressive-enhancement-error" as const,
+    routeKey: getRequestContext()._routeName,
+    actionId: actionId ?? undefined,
+  };
+  return renderRscResponse(
+    {
+      ctx,
+      request,
+      env,
+      url,
+      payload,
+      init: {
+        status: 500,
+        headers: { "content-type": "text/html;charset=utf-8" },
+      },
+      tracking: stageTracking,
+    },
+    {
+      // Reuse the early setup promise; the driver times only renderHTML.
+      html: createSsrHtmlStage({
+        ctx,
+        request,
+        env,
+        url,
+        metricsStore: undefined,
+        render: { nonce },
+      }),
     },
-  });
-  // metricsStore=undefined is safe: the handler already stashed the early
-  // SSR setup promise on request variables, so getSSRSetup returns it
-  // without falling back to a fresh startSSRSetup.
-  const [ssrModule, streamMode] = await getSSRSetup(
-    ctx,
-    request,
-    env,
-    url,
-    undefined,
   );
-  const htmlStream = await ssrModule.renderHTML(rscStream, {
-    nonce,
-    streamMode,
-  });
-
-  return createResponseWithMergedHeaders(htmlStream, {
-    status: 500,
-    headers: { "content-type": "text/html;charset=utf-8" },
-  });
 }

package/src/rsc/redirect-guard.ts

@@ -14,7 +14,9 @@
  *
  * Soft (SPA/Flight) redirects are 200/204 responses (`X-RSC-Redirect` header or
  * `metadata.redirect` payload) and are NOT redirect Responses, so they never
- * reach this guard -- they stay validated client-side.
+ * reach this guard. They are resolved at construction time via
+ * `resolveSoftRedirectUrl` (same shared rules) so unsafe targets never leave
+ * the server; client validators remain defense-in-depth.
  *
  * Behavior on a `Location` header:
  * - same-origin / relative  -> passes through unchanged