@rangojs/router 0.5.1 → 0.5.2

package/src/rsc/server-action.ts

@@ -29,11 +29,22 @@ import {
   createSimpleRedirectResponse,
   interceptRedirectForPartial,
   attachLocationStateIfPresent,
+  matchAndRecordParams,
 } from "./helpers.js";
-import { renderRscResponse } from "./render-pipeline.js";
+import {
+  createRenderStageTraceBridge,
+  renderRscResponse,
+} from "./render-pipeline.js";
+import {
+  createRoutineTrace,
+  runRoutine,
+  step,
+  type RoutinePlan,
+} from "./routine-plan.js";
 import { warnNonRedirectActionResponse } from "./runtime-warnings.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { MatchResult } from "../types.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
 /**
  * Data flowing from action execution to the revalidation phase.
@@ -350,6 +361,17 @@ export function revalidateAfterAction<TEnv>(
   );
 }
 
+interface ActionRevalidationInput<TEnv> {
+  ctx: HandlerContext<TEnv>;
+  request: Request;
+  env: TEnv;
+  url: URL;
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"];
+  continuation: ActionContinuation;
+  renderSpan: TraceSpan;
+  reqCtx: ReturnType<typeof getRequestContext>;
+}
+
 async function revalidateAfterActionInner<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
@@ -359,14 +381,8 @@ async function revalidateAfterActionInner<TEnv>(
   continuation: ActionContinuation,
   renderSpan: TraceSpan,
 ): Promise<Response> {
-  const {
-    returnValue,
-    actionStatus,
-    temporaryReferences,
-    actionContext,
-    errorBoundary,
-  } = continuation;
   const reqCtx = getRequestContext();
+  const { actionContext } = continuation;
   // Expose the action that triggered this revalidation to the transition({ when })
   // gate (covers both the error-boundary and success gate calls below). Mirrors
   // the action fields a revalidate() predicate sees.
@@ -381,76 +397,63 @@ async function revalidateAfterActionInner<TEnv>(
   // in the background. See registerCachedFunction in cache/cache-runtime.ts.
   reqCtx._inActionRevalidation = true;
 
+  const trace = INTERNAL_RANGO_DEBUG
+    ? createRoutineTrace("action-revalidation")
+    : undefined;
+  const input: ActionRevalidationInput<TEnv> = {
+    ctx,
+    request,
+    env,
+    url,
+    handleStore,
+    continuation,
+    renderSpan,
+    reqCtx,
+  };
+  try {
+    return await runRoutine(actionRevalidationPlan(input), {
+      trace,
+      owner: reqCtx,
+    });
+  } finally {
+    if (trace) {
+      console.log(
+        `[routine] ${request.method} ${url.pathname} (${trace.name})\n${trace.format()}`,
+      );
+    }
+  }
+}
+
+/**
+ * The action-revalidation plan: render the deferred error boundary if the
+ * action threw and one matched, otherwise match affected segments (falling
+ * back to a full match for redirects) and render the partial payload.
+ */
+function* actionRevalidationPlan<TEnv>(
+  input: ActionRevalidationInput<TEnv>,
+): RoutinePlan<Response> {
+  const { ctx, request, env, url, continuation } = input;
+  const { actionContext, errorBoundary } = continuation;
+
   // Action threw and a boundary matched: render the (already-matched) error
   // boundary here so it runs inside the route-middleware wrapper, exactly like
-  // the success branch below. setRequestContextParams + the payload mirror the
-  // pre-deferral render that executeServerAction used to do inline.
+  // the success branch below.
   if (errorBoundary) {
-    setRequestContextParams(errorBoundary.params, errorBoundary.routeName);
-
-    const errorPayload: RscPayload = {
-      metadata: {
-        pathname: url.pathname,
-        // routerId exposed for the frontend (current app identity); see
-        // rsc-rendering.ts partial branch.
-        routerId: ctx.router.id,
-        segments: gateTransitions(
-          errorBoundary.segments,
-          reqCtx,
-          ctx.router.onError,
-        ),
-        isPartial: true,
-        matched: errorBoundary.matched,
-        diff: errorBoundary.diff,
-        resolvedIds: errorBoundary.resolvedIds,
-        params: errorBoundary.params,
-        isError: true,
-        handles: handleStore.stream(),
-        version: ctx.version,
-      },
-      returnValue,
-    };
-
-    // Intentionally omit attachLocationState for error payloads: location state
-    // is a success-only semantic. Error boundary responses update the error UI
-    // but should not mutate browser history state.
-
-    return renderRscResponse({
-      ctx,
-      request,
-      env,
-      url,
-      payload: errorPayload,
-      temporaryReferences,
-      init: {
-        status: actionStatus,
-        headers: {
-          "content-type": "text/x-component;charset=utf-8",
-          // Router identity for the client's pre-decode integrity check (the
-          // action apply path has no post-decode guard). See response-adapter.
-          "X-RSC-Router-Id": ctx.router.id,
-        },
-      },
-      tracking: {
-        mode: "action-revalidation",
-        routeKey: reqCtx._routeName,
-        actionId: actionContext?.actionId,
-        span: renderSpan,
-      },
-    });
+    return yield* step("render", () =>
+      renderActionBoundaryResponse(input, errorBoundary),
+    );
   }
 
-  const matchResult = await ctx.router.matchPartial(
-    request,
-    { env },
-    actionContext,
+  const matchResult = yield* step("match:partial", () =>
+    matchPartialAndRecord(ctx, request, env, actionContext),
   );
 
   if (!matchResult) {
     // matchPartial returns null when the route is a redirect or no previous-URL
     // context could be resolved. Check for redirect first.
-    const fullMatch = await ctx.router.match(request, { env });
-    setRequestContextParams(fullMatch.params, fullMatch.routeName);
+    const fullMatch = yield* step("match:fallback", () =>
+      matchAndRecordParams(ctx, request, env),
+    );
 
     if (fullMatch.redirect) {
       // Action context is always partial — use X-RSC-Redirect header so
@@ -476,8 +479,111 @@ async function revalidateAfterActionInner<TEnv>(
     );
   }
 
-  // Return updated segments
-  setRequestContextParams(matchResult.params, matchResult.routeName);
+  return yield* step("render", () =>
+    renderRevalidationResponse(input, matchResult),
+  );
+}
+
+/** matchPartial that stamps params/routeName when a result exists. */
+async function matchPartialAndRecord<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  actionContext: ActionContinuation["actionContext"],
+): Promise<
+  Awaited<ReturnType<HandlerContext<TEnv>["router"]["matchPartial"]>>
+> {
+  const matchResult = await ctx.router.matchPartial(
+    request,
+    { env },
+    actionContext,
+  );
+  if (matchResult) {
+    setRequestContextParams(matchResult.params, matchResult.routeName);
+  }
+  return matchResult;
+}
+
+/**
+ * Render the deferred action error boundary. setRequestContextParams + the
+ * payload mirror the pre-deferral render that executeServerAction used to do
+ * inline.
+ */
+function renderActionBoundaryResponse<TEnv>(
+  input: ActionRevalidationInput<TEnv>,
+  errorBoundary: MatchResult,
+): Promise<Response> {
+  const { ctx, request, env, url, handleStore, continuation, reqCtx } = input;
+  const { returnValue, actionStatus, temporaryReferences, actionContext } =
+    continuation;
+
+  setRequestContextParams(errorBoundary.params, errorBoundary.routeName);
+
+  const errorPayload: RscPayload = {
+    metadata: {
+      pathname: url.pathname,
+      // routerId exposed for the frontend (current app identity); see
+      // rsc-rendering.ts partial branch.
+      routerId: ctx.router.id,
+      segments: gateTransitions(
+        errorBoundary.segments,
+        reqCtx,
+        ctx.router.onError,
+      ),
+      isPartial: true,
+      matched: errorBoundary.matched,
+      diff: errorBoundary.diff,
+      resolvedIds: errorBoundary.resolvedIds,
+      params: errorBoundary.params,
+      isError: true,
+      handles: handleStore.stream(),
+      version: ctx.version,
+    },
+    returnValue,
+  };
+
+  // Intentionally omit attachLocationState for error payloads: location state
+  // is a success-only semantic. Error boundary responses update the error UI
+  // but should not mutate browser history state.
+
+  return renderRscResponse({
+    ctx,
+    request,
+    env,
+    url,
+    payload: errorPayload,
+    temporaryReferences,
+    init: {
+      status: actionStatus,
+      headers: {
+        "content-type": "text/x-component;charset=utf-8",
+        // Router identity for the client's pre-decode integrity check (the
+        // action apply path has no post-decode guard). See response-adapter.
+        "X-RSC-Router-Id": ctx.router.id,
+      },
+    },
+    tracking: {
+      mode: "action-revalidation",
+      routeKey: input.reqCtx._routeName,
+      actionId: actionContext?.actionId,
+      span: input.renderSpan,
+      onEvent:
+        reqCtx._activeRoutine &&
+        createRenderStageTraceBridge(reqCtx._activeRoutine),
+    },
+  });
+}
+
+/** Render the updated segments after a successful action. */
+function renderRevalidationResponse<TEnv>(
+  input: ActionRevalidationInput<TEnv>,
+  matchResult: NonNullable<
+    Awaited<ReturnType<HandlerContext<TEnv>["router"]["matchPartial"]>>
+  >,
+): Promise<Response> {
+  const { ctx, request, env, url, handleStore, continuation, reqCtx } = input;
+  const { returnValue, actionStatus, temporaryReferences, actionContext } =
+    continuation;
 
   const payload: RscPayload = {
     metadata: {
@@ -524,7 +630,10 @@ async function revalidateAfterActionInner<TEnv>(
       mode: "action-revalidation",
       routeKey: reqCtx._routeName,
       actionId: actionContext?.actionId,
-      span: renderSpan,
+      span: input.renderSpan,
+      onEvent:
+        reqCtx._activeRoutine &&
+        createRenderStageTraceBridge(reqCtx._activeRoutine),
     },
   });
 }

package/src/rsc/shell-capture-constants.ts

@@ -25,3 +25,21 @@
  * docs/design/ppr-shell-resume.md (Cost model).
  */
 export const SHELL_CAPTURE_MAX_WAIT_MS = 15_000;
+
+/**
+ * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
+ * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
+ * captureShellHTML, AFTER the capture's router.match(); a handler wedged on a
+ * never-settling upstream await (autobarn pilot: a 30s+ tarpitting fetch)
+ * wedges the task with no deadline in force. The task's settle path releases
+ * the per-key stampede guard and the serialized capture-queue slot, so an
+ * unbounded task strands BOTH for the isolate's lifetime.
+ *
+ * 25s: above one full-budget attempt plus overhead (cutting a second attempt
+ * short is an acceptable loss — every terminal path backs the key off anyway),
+ * and below workerd's ~30s waitUntil grace so the cap timer still fires in a
+ * live context. When workerd kills the context BEFORE the cap fires, the timer
+ * dies with it — that stranding is healed by scheduleShellCapture's staleness
+ * check on the stampede guard, keyed off the same constant.
+ */
+export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;

package/src/rsc/shell-capture.ts

@@ -26,7 +26,10 @@ import {
   captureQueueDepths,
   enqueueSerializedCapture,
 } from "./capture-queue.js";
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
+import {
+  SHELL_CAPTURE_MAX_WAIT_MS,
+  SHELL_CAPTURE_TASK_HARD_CAP_MS,
+} from "./shell-capture-constants.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import type { TraceSpan } from "../router/tracing.js";
@@ -185,15 +188,64 @@ function delay(ms: number): Promise<void> {
 }
 
 /**
- * Module-level in-flight key set: the stampede guard for background captures, and
+ * Bound one capture task at {@link SHELL_CAPTURE_TASK_HARD_CAP_MS}. Rejects on
+ * expiry so the caller's existing catch applies backoff + reporting and its
+ * settle path releases the stampede guard and queue slot; resolves/rejects
+ * transparently otherwise. The timer is unref'd so a pending cap never holds a
+ * Node dev process open.
+ */
+function raceTaskHardCap<T>(task: Promise<T>, key: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `capture task for ${key} exceeded the ${SHELL_CAPTURE_TASK_HARD_CAP_MS}ms hard cap; ` +
+            `a handler is likely wedged on a never-settling await`,
+        ),
+      );
+    }, SHELL_CAPTURE_TASK_HARD_CAP_MS);
+    (timer as { unref?: () => void }).unref?.();
+    task.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error: unknown) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Module-level in-flight key map: the stampede guard for background captures, and
  * its single owner. One capture runs per key per isolate; concurrent MISS/stale
  * requests for the same key coalesce onto the first (the rest see the key present
  * in scheduleShellCapture and skip). Added when a capture is scheduled and cleared
- * in the task's finally once it settles, so a later request can recapture when TTL
- * rolls. Living here (not split across the middleware) keeps the add/clear
- * lifecycle in one layer.
+ * in the task's settle paths via a token-guarded release, so a later request can
+ * recapture when TTL rolls. Living here (not split across the middleware) keeps
+ * the add/clear lifecycle in one layer.
+ *
+ * The value is the owning task's token ({@link CaptureGuardToken}) rather than
+ * a bare set entry: workerd can kill a capture's waitUntil context before its
+ * finally runs (or the task can wedge past every deadline), stranding the key.
+ * scheduleShellCapture treats an entry older than
+ * SHELL_CAPTURE_TASK_HARD_CAP_MS as abandoned and reclaims it; the token guard
+ * keeps a late-settling stale task from releasing its replacement's entry.
  */
-const inFlightCaptures = new Set<string>();
+interface CaptureGuardToken {
+  startedAt: number;
+}
+
+const inFlightCaptures = new Map<string, CaptureGuardToken>();
+
+/** Token-guarded release: only the entry's owning task may clear it. */
+function releaseCaptureGuard(key: string, token: CaptureGuardToken): void {
+  if (inFlightCaptures.get(key) === token) {
+    inFlightCaptures.delete(key);
+  }
+}
 
 /**
  * Refused-capture backoff bounds. The window is EXPONENTIAL in the consecutive
@@ -918,9 +970,17 @@ export function scheduleShellCapture(
   descriptor: ShellCaptureDescriptor,
 ): void {
   const key = descriptor.key;
-  if (inFlightCaptures.has(key)) {
-    publishCaptureDebugEvent(descriptor, { key, outcome: "skip-in-flight" });
-    return;
+  const inFlight = inFlightCaptures.get(key);
+  if (inFlight) {
+    if (Date.now() - inFlight.startedAt <= SHELL_CAPTURE_TASK_HARD_CAP_MS) {
+      publishCaptureDebugEvent(descriptor, { key, outcome: "skip-in-flight" });
+      return;
+    }
+    // Older than the task hard cap: the owning task never settled (wedged
+    // render, or workerd killed its context before the release ran). Treat the
+    // key as abandoned and schedule a replacement — the set() below installs a
+    // new token, and the stale task's token-guarded release can no longer
+    // touch it.
   }
   // Refused/failed within the window → skip the doomed re-render (one probe per
   // key per window per isolate). Expired entries self-evict inside the check.
@@ -942,7 +1002,8 @@ export function scheduleShellCapture(
     publishCaptureDebugEvent(descriptor, { key, outcome: "skip-inert-store" });
     return;
   }
-  inFlightCaptures.add(key);
+  const guardToken: CaptureGuardToken = { startedAt: Date.now() };
+  inFlightCaptures.set(key, guardToken);
   const captureTask = async (span: TraceSpan) => {
     try {
       const setupUrl = descriptor.navigationOnly
@@ -962,14 +1023,24 @@ export function scheduleShellCapture(
       ) {
         return;
       }
-      const outcome = await runShellCapture(
-        ctx,
-        request,
-        env,
-        url,
-        reqCtx,
-        resolvedSsrModule,
-        descriptor,
+      // Hard-capped: SHELL_CAPTURE_MAX_WAIT_MS arms only inside
+      // captureShellHTML, AFTER the capture's router.match() — a handler
+      // wedged on a never-settling upstream await has no deadline in force
+      // and would strand the stampede guard and the queue slot (autobarn
+      // pilot). The cap rejects, riding the existing catch: backoff +
+      // reportCacheError + token-guarded release. The abandoned attempt keeps
+      // running until its context dies; nothing awaits it.
+      const outcome = await raceTaskHardCap(
+        runShellCapture(
+          ctx,
+          request,
+          env,
+          url,
+          reqCtx,
+          resolvedSsrModule,
+          descriptor,
+        ),
+        key,
       );
       span.setAttribute("rango.background.outcome", outcome);
       // Update the negative cache off the terminal outcome. A stored shell clears
@@ -998,7 +1069,7 @@ export function scheduleShellCapture(
       });
       reportCacheError(error, "cache-write", "[ShellCache] capture", reqCtx);
     } finally {
-      inFlightCaptures.delete(key);
+      releaseCaptureGuard(key, guardToken);
     }
   };
   // Serialize capture EXECUTION per isolate (capture-queue.ts): concurrent
@@ -1049,7 +1120,7 @@ export function scheduleShellCapture(
         );
       } catch (error) {
         if (error instanceof CaptureQueueFullError) {
-          inFlightCaptures.delete(key);
+          releaseCaptureGuard(key, guardToken);
           span.setAttribute("rango.background.outcome", "skip-capacity");
           publishCaptureDebugEvent(descriptor, {
             key,
@@ -1061,7 +1132,7 @@ export function scheduleShellCapture(
           // Dropped unrun after waiting past the queue budget: no backoff (the
           // route is not doomed, the isolate was busy) — a later request
           // re-probes the key.
-          inFlightCaptures.delete(key);
+          releaseCaptureGuard(key, guardToken);
           span.setAttribute("rango.background.outcome", "skip-queue-timeout");
           span.setAttribute(
             "rango.background.queue_wait_ms",

package/src/server/request-context.ts

@@ -57,6 +57,7 @@ import {
   warnInvalidTheme,
 } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RoutineTrace } from "../rsc/routine-plan.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import {
   assertCachedHeaderWriteAllowed,
@@ -663,6 +664,9 @@ export interface RequestContext<
    */
   _renderForeground?: RenderForegroundCursor;
 
+  /** @internal Request routine currently executing, used by timeout diagnostics. */
+  _activeRoutine?: RoutineTrace;
+
   /** @internal Keep the render cursor active for timeout support. */
   _renderDiagnosticsEnabled?: boolean;
 
@@ -767,6 +771,7 @@ export type PublicRequestContext<
   | "_debugPerformance"
   | "_metricsStore"
   | "_renderForeground"
+  | "_activeRoutine"
   | "_renderDiagnosticsEnabled"
   | "_handlerStart"
   | "_tracing"
@@ -1323,6 +1328,7 @@ export function createRequestContext<TEnv>(
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
     _renderForeground: undefined,
+    _activeRoutine: undefined,
     _renderDiagnosticsEnabled: undefined,
     _handlerStart: undefined,
 

package/src/ssr/ssr-root.tsx

@@ -97,6 +97,7 @@ function createSsrEventController(opts: {
     }),
     subscribeToAction: () => () => {},
     subscribeToHandles: () => () => {},
+    flushRouteState: () => {},
     setHandleData: () => {},
     getHandleState: () => handleState,
     setRouteSegmentIds: () => {},

package/src/vite/encryption-key.ts

@@ -0,0 +1,29 @@
+import { randomBytes } from "node:crypto";
+
+// plugin-rsc encrypts inline-action bound args with a key read from
+// `virtual:vite-rsc/encryption-key`, which defaults to a fresh random key PER
+// plugin instance. The build-discovery temp server (which renders Static/
+// Prerender output) is a separate plugin instance from the main build, so by
+// default it encrypts prerendered bound args with a key the runtime never has --
+// `decryptActionBoundArgs` then fails on invocation. We hand both the SAME key
+// via plugin-rsc's `defineEncryptionKey` so build-time-encrypted bound args
+// decrypt at runtime.
+//
+// Cached per process so the temp server (created during the main build's
+// buildStart) and the main build share one key. Overridable via
+// RANGO_ENCRYPTION_KEY for a stable key across builds/deploys; otherwise a fresh
+// key is generated per build (matching plugin-rsc's default posture, where the
+// key is emitted into the build output regardless).
+let cachedKey: string | undefined;
+
+export function buildEncryptionKey(): string {
+  cachedKey ??=
+    process.env.RANGO_ENCRYPTION_KEY ?? randomBytes(32).toString("base64");
+  return cachedKey;
+}
+
+// The value plugin-rsc inlines as `export default () => (<expr>)`. A JSON string
+// literal, so the emitted runtime key module is a plain base64 string.
+export function defineEncryptionKeyExpr(): string {
+  return JSON.stringify(buildEncryptionKey());
+}

package/src/vite/plugins/expose-action-id.ts

@@ -3,6 +3,7 @@ import MagicString from "magic-string";
 import path from "node:path";
 import fs from "node:fs";
 import { normalizePath } from "./expose-id-utils.js";
+import { registerServerReferenceRegex } from "./server-reference-pattern.js";
 import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
 const debug = createRangoDebugger(NS.transform);
@@ -133,8 +134,7 @@ function applyRegisterReferenceWrapping(
     return false;
   }
 
-  const pattern =
-    /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+  const pattern = registerServerReferenceRegex();
 
   let hasChanges = false;
   let match: RegExpExecArray | null;

package/src/vite/plugins/expose-internal-ids.ts

@@ -68,6 +68,52 @@ const VIRTUAL_HANDLER_PREFIX = "virtual:handler-extract:";
 // Consolidated plugin
 // ---------------------------------------------------------------------------
 
+interface RscScanPluginApi {
+  manager?: { isScanBuild?: boolean };
+}
+
+/**
+ * Stub export-only loader modules before plugin-rsc reduces scan modules to
+ * imports. The regular post transform remains authoritative outside scan builds.
+ *
+ * Handles and location-state definitions are intentionally excluded: handle
+ * collect functions run in the browser, and location-state definitions are
+ * callable browser objects. Their dependencies must remain visible to non-RSC
+ * validation rather than being hidden behind an opaque scan stub.
+ */
+export function createLoaderScanStubPlugin(): Plugin {
+  let projectRoot = "";
+  let rscApi: RscScanPluginApi | undefined;
+
+  return {
+    name: "@rangojs/router:loader-scan-stubs",
+    apply: "build",
+    configResolved(config) {
+      projectRoot = config.root;
+      rscApi = config.plugins.find((plugin) => plugin.name === "rsc:minimal")
+        ?.api as RscScanPluginApi | undefined;
+    },
+    transform(code, id) {
+      if (
+        !rscApi?.manager?.isScanBuild ||
+        this.environment?.name === "rsc" ||
+        id.includes("/node_modules/") ||
+        !code.includes("createLoader") ||
+        !hasCreateLoaderImport(code)
+      ) {
+        return;
+      }
+
+      const fnNames = getImportedFnNames(code, "createLoader");
+      const bindings = collectCreateExportBindings(code, fnNames);
+      const filePath = normalizePath(path.relative(projectRoot, id));
+      return (
+        generateClientLoaderStubs(bindings, code, filePath, true) ?? undefined
+      );
+    },
+  };
+}
+
 export function exposeInternalIds(options?: { forceBuild?: boolean }): Plugin {
   let config: ResolvedConfig;
   let isBuild = false;