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

package/src/rsc/rsc-rendering.ts

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

package/src/rsc/runtime-warnings.ts

@@ -0,0 +1,55 @@
+/**
+ * Runtime guardrail warnings (dev-only).
+ *
+ * W3: PE action redirect / Response handling.
+ */
+
+import {
+  createResponseWithMergedHeaders,
+  carryOverRedirectHeaders,
+} from "./helpers.js";
+import { isRedirectResponse } from "../response-utils.js";
+
+// W3 -----------------------------------------------------------------------
+
+/**
+ * Extract a redirect Response from a thrown or returned value.
+ * Returns a redirect Response to send to the client, or null if the value
+ * is not a redirect Response.
+ */
+export function extractRedirectResponse(value: unknown): Response | null {
+  if (!(value instanceof Response)) return null;
+  if (!isRedirectResponse(value)) return null;
+  const location = value.headers.get("Location")!;
+  const redirect = createResponseWithMergedHeaders(null, {
+    status: value.status,
+    headers: { Location: location },
+  });
+  carryOverRedirectHeaders(value, redirect);
+  return redirect;
+}
+
+/**
+ * Warn when a non-redirect Response is returned from an action during PE.
+ */
+export function warnNonRedirectPeResponse(): void {
+  console.warn(
+    `[rango] Server action returned a non-redirect Response during ` +
+      `progressive enhancement (no-JS) request. The Response will be ` +
+      `ignored — the page will re-render at the current URL instead.`,
+  );
+}
+
+/**
+ * Warn when a non-redirect Response is returned (not thrown) from an action
+ * on the JS (fetch) path. A raw Response cannot be serialized into Flight, so
+ * it is discarded — mirroring the PE path. Use `throw redirect('/path')` for
+ * redirects.
+ */
+export function warnNonRedirectActionResponse(actionId: string): void {
+  console.warn(
+    `[@rangojs/router] Server action "${actionId}" returned a Response ` +
+      `that is not a redirect. Non-redirect Responses cannot be serialized ` +
+      `and are ignored. Use \`throw redirect('/path')\` for redirects.`,
+  );
+}

package/src/rsc/server-action.ts

@@ -0,0 +1,376 @@
+/**
+ * Server Action Handler
+ *
+ * Handles server action execution and post-action revalidation as two
+ * separate phases:
+ *
+ * 1. executeServerAction — decodes args, runs the action, handles redirects
+ *    and error boundaries. Returns either a final Response (redirect/error)
+ *    or an ActionContinuation for the revalidation phase.
+ *
+ * 2. revalidateAfterAction — takes the continuation, matches affected
+ *    segments, builds the RSC payload, and returns the Flight response.
+ *
+ * The handler (handler.ts) runs the action BEFORE route middleware, then
+ * wraps revalidation inside route middleware — identical to a normal render.
+ */
+
+import {
+  requireRequestContext,
+  setRequestContextParams,
+} from "../server/request-context.js";
+import { appendMetric } from "../router/metrics.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import type { RscPayload } from "./types.js";
+import {
+  hasBodyContent,
+  createResponseWithMergedHeaders,
+  createSimpleRedirectResponse,
+  interceptRedirectForPartial,
+  attachLocationStateIfPresent,
+} from "./helpers.js";
+import { warnNonRedirectActionResponse } from "./runtime-warnings.js";
+import type { HandlerContext } from "./handler-context.js";
+
+/**
+ * Data flowing from action execution to the revalidation phase.
+ * When the action completes without redirect/error-boundary, the handler
+ * passes this to route middleware → revalidateAfterAction.
+ */
+export interface ActionContinuation {
+  returnValue: { ok: boolean; data: unknown };
+  actionStatus: number;
+  temporaryReferences: ReturnType<
+    HandlerContext["createTemporaryReferenceSet"]
+  >;
+  actionContext: {
+    actionId: string;
+    actionUrl: URL;
+    actionResult: unknown;
+    formData?: FormData;
+  };
+}
+
+/**
+ * Phase 1: Execute the server action.
+ *
+ * Decodes arguments, runs the action, handles redirects and error
+ * boundaries. Returns a final Response (redirect, error boundary render)
+ * or an ActionContinuation for the revalidation phase.
+ */
+export async function executeServerAction<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  actionId: string,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+): Promise<Response | ActionContinuation> {
+  const temporaryReferences = ctx.createTemporaryReferenceSet();
+
+  // Decode action arguments from request body
+  const contentType = request.headers.get("content-type") || "";
+  let args: unknown[] = [];
+  let actionFormData: FormData | undefined;
+
+  try {
+    const body = contentType.includes("multipart/form-data")
+      ? await request.formData()
+      : await request.text();
+
+    if (body instanceof FormData) {
+      actionFormData = body;
+    }
+
+    if (hasBodyContent(body)) {
+      args = await ctx.decodeReply(body, { temporaryReferences });
+    }
+  } catch (error) {
+    // Keep the original error as `cause` for server-side logging, but do not
+    // interpolate it into the message: that string can surface to the client
+    // and may leak decode internals.
+    throw new Error("Failed to decode action arguments", {
+      cause: error,
+    });
+  }
+
+  // Execute the server action
+  let returnValue: { ok: boolean; data: unknown };
+  let actionStatus = 200;
+  let loadedAction: Function | undefined;
+
+  try {
+    loadedAction = await ctx.loadServerAction(actionId);
+    let data = await loadedAction!.apply(null, args);
+
+    // Intercept redirect Responses: serializing one as the action returnValue
+    // would fail, and revalidation would run needlessly.
+    if (data instanceof Response) {
+      const intercepted = interceptRedirectForPartial(
+        data,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
+
+      // Non-redirect Response returned (not thrown): a raw Response cannot be
+      // serialized into Flight. Discard it and re-render — mirroring the PE
+      // path (progressive-enhancement.ts) so JS and no-JS behave identically.
+      if (process.env.NODE_ENV !== "production") {
+        warnNonRedirectActionResponse(actionId);
+      }
+      data = undefined;
+    }
+
+    returnValue = { ok: true, data };
+  } catch (error) {
+    // Handle thrown redirect (e.g., throw redirect('/path'))
+    if (error instanceof Response) {
+      const intercepted = interceptRedirectForPartial(
+        error,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
+
+      // Non-redirect Response thrown from action — this will be treated
+      // as a regular error and routed to the error boundary. Warn in dev
+      // since the intent is likely a redirect with a missing Location header.
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          `[@rangojs/router] Server action "${actionId}" threw a Response ` +
+            `(status ${error.status}) that is not a redirect. ` +
+            `Non-redirect Responses are treated as errors. ` +
+            `Use \`throw redirect('/path')\` for redirects.`,
+        );
+      }
+    }
+
+    returnValue = { ok: false, data: error };
+    actionStatus = 500;
+
+    // Try to render error boundary.
+    // Report the action error first so it is not lost if matchError throws.
+    let errorResult;
+    try {
+      errorResult = await ctx.router.matchError(
+        request,
+        { env },
+        error,
+        "route",
+      );
+    } catch (matchErr) {
+      // matchError failed — report the original action error as unhandled,
+      // then let the matchError failure propagate.
+      ctx.callOnError(error, "action", {
+        request,
+        url,
+        env,
+        actionId,
+        handledByBoundary: false,
+      });
+      throw matchErr;
+    }
+
+    ctx.callOnError(error, "action", {
+      request,
+      url,
+      env,
+      actionId,
+      handledByBoundary: !!errorResult,
+    });
+
+    if (errorResult) {
+      setRequestContextParams(errorResult.params, errorResult.routeName);
+
+      const payload: RscPayload = {
+        metadata: {
+          pathname: url.pathname,
+          // routerId exposed for the frontend (current app identity); see
+          // rsc-rendering.ts partial branch.
+          routerId: ctx.router.id,
+          segments: errorResult.segments,
+          isPartial: true,
+          matched: errorResult.matched,
+          diff: errorResult.diff,
+          resolvedIds: errorResult.resolvedIds,
+          params: errorResult.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.
+
+      const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+        temporaryReferences,
+        onError: (error: unknown) => {
+          ctx.callOnError(error, "rendering", { request, url, env });
+        },
+      });
+
+      return createResponseWithMergedHeaders(rscStream, {
+        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,
+        },
+      });
+    }
+  }
+
+  // Build continuation for the revalidation phase
+  const actionMeta = loadedAction as
+    | { $id?: string; $$id?: string }
+    | undefined;
+  const resolvedActionId = actionMeta?.$id ?? actionMeta?.$$id ?? actionId;
+
+  return {
+    returnValue,
+    actionStatus,
+    temporaryReferences,
+    actionContext: {
+      // Defensive copy of the already-parsed url (avoids re-parsing
+      // request.url). actionUrl is persisted into the continuation and later
+      // flows into matchPartial, so it must not alias the handler's live url.
+      actionId: resolvedActionId,
+      actionUrl: new URL(url),
+      actionResult: returnValue.data,
+      formData: actionFormData,
+    },
+  };
+}
+
+/**
+ * Phase 2: Revalidate after action.
+ *
+ * Matches affected segments, builds the RSC payload, and returns the
+ * Flight response. Called inside route middleware (same as a normal render).
+ *
+ * Invariant: the response payload MUST have isPartial: true. The client
+ * (server-action-bridge) rejects non-partial payloads because partial
+ * reconciliation requires matched/diff semantics that full renders don't
+ * provide. Redirects are the only non-partial outcome and are handled via
+ * X-RSC-Redirect headers before Flight deserialization.
+ */
+export function revalidateAfterAction<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  continuation: ActionContinuation,
+): Promise<Response> {
+  // Instrument the action-revalidation render through the unified phase API,
+  // exactly like a normal navigation render (handleRscRendering). It records
+  // "render:total" AND opens "rango.render" from one boundary covering
+  // matchPartial -> serialize, so the revalidation loaders' rango.loader spans
+  // nest under a rango.render parent instead of dangling at the request root.
+  return observePhase(PHASES.render, () =>
+    revalidateAfterActionInner(
+      ctx,
+      request,
+      env,
+      url,
+      handleStore,
+      continuation,
+    ),
+  );
+}
+
+async function revalidateAfterActionInner<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  continuation: ActionContinuation,
+): Promise<Response> {
+  const { returnValue, actionStatus, temporaryReferences, actionContext } =
+    continuation;
+  const reqCtx = requireRequestContext();
+  const metricsStore = reqCtx._metricsStore;
+
+  const matchResult = await ctx.router.matchPartial(
+    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);
+
+    if (fullMatch.redirect) {
+      // Action context is always partial — use X-RSC-Redirect header so
+      // the client can perform SPA navigation instead of fetch auto-following
+      // a raw 308 to a URL that would render full HTML.
+      return createSimpleRedirectResponse(fullMatch.redirect);
+    }
+
+    // Non-redirect: this branch is only reachable when no previous URL could
+    // be resolved (neither X-RSC-Router-Client-Path nor a usable Referer), or
+    // the previous URL was unparseable (defensive). The client requires
+    // isPartial for action responses, so producing a full payload here would
+    // be rejected. Return 500 instead.
+    throw new Error(
+      `[RSC] matchPartial returned null for a non-redirect route ` +
+        `during action revalidation (${url.pathname}). This indicates ` +
+        `a malformed action request: no previous-URL context could be ` +
+        `resolved (neither X-RSC-Router-Client-Path nor a usable Referer), ` +
+        `or the previous URL was unparseable.`,
+    );
+  }
+
+  // Return updated segments
+  setRequestContextParams(matchResult.params, matchResult.routeName);
+
+  const payload: RscPayload = {
+    metadata: {
+      pathname: url.pathname,
+      // routerId exposed for the frontend (current app identity); see
+      // rsc-rendering.ts partial branch.
+      routerId: ctx.router.id,
+      segments: matchResult.segments,
+      isPartial: true,
+      matched: matchResult.matched,
+      diff: matchResult.diff,
+      resolvedIds: matchResult.resolvedIds,
+      params: matchResult.params,
+      slots: matchResult.slots,
+      handles: handleStore.stream(),
+      version: ctx.version,
+    },
+    returnValue,
+  };
+
+  attachLocationStateIfPresent(payload);
+
+  const renderStart = performance.now();
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    temporaryReferences,
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
+  const rscSerializeDur = performance.now() - renderStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  // render:total is recorded by the observePhase wrapper in revalidateAfterAction.
+  appendMetric(metricsStore, "rsc-serialize", renderStart, rscSerializeDur);
+
+  return createResponseWithMergedHeaders(rscStream, {
+    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,
+    },
+  });
+}