@rangojs/router 0.0.0-experimental.150 → 0.0.0-experimental.152

package/src/router/prerender-match.ts

@@ -206,6 +206,11 @@ export async function matchForPrerender<TEnv = any>(
       pathname,
       searchParams: new URLSearchParams(),
       _variables: variables,
+      build: true,
+      // Inert here: the prerender-collect / static-render pass has no live
+      // PPR-shell decision to gate; dynamic() reaches the shell axis only on a
+      // live request or a shell capture.
+      dynamic: () => {},
       get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
       set: ((keyOrVar: any, value: any) => {
         contextSet(variables, keyOrVar, value);
@@ -476,6 +481,8 @@ export async function renderStaticSegment<TEnv = any>(
     pathname: "/",
     searchParams: syntheticUrl.searchParams,
     _variables: {},
+    build: true,
+    dynamic: () => {},
     get: () => undefined as any,
     set: () => {},
     params: {},

package/src/router/router-interfaces.ts

@@ -366,12 +366,6 @@ export interface RangoInternal<
    */
   readonly telemetry?: TelemetrySink;
 
-  /**
-   * Whether ?__debug_manifest is allowed in production.
-   * Always enabled in development.
-   */
-  readonly allowDebugManifest: boolean;
-
   /**
    * Resolved timeout configuration (merged from shorthand + structured).
    */

package/src/router/router-options.ts

@@ -126,14 +126,6 @@ export interface RangoOptions<TEnv = any> {
    */
   debugPerformance?: boolean;
 
-  /**
-   * Allow the `?__debug_manifest` query parameter to return route manifest data as JSON.
-   * In development mode this is always enabled regardless of this setting.
-   * Defaults to false. Set to true to enable in production.
-   * @internal
-   */
-  allowDebugManifest?: boolean;
-
   /**
    * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
    * the cache status of the matched route, for use by testing primitives such

package/src/router.ts

@@ -158,7 +158,6 @@ export function createRouter<TEnv = any>(
     prefetchConcurrency: prefetchConcurrencyOption,
     stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
-    allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
     tracing: tracingOption,
     ssr: ssrOption,
@@ -1021,9 +1020,6 @@ export function createRouter<TEnv = any>(
     // undefined when unconfigured and call sites gate on truthiness.
     telemetry: telemetrySink,
 
-    // Expose debug manifest flag for handler
-    allowDebugManifest: allowDebugManifestOption,
-
     // Expose origin check configuration for handler (default: enabled)
     originCheck: originCheckOption ?? true,
 

package/src/rsc/handler.ts

@@ -25,10 +25,14 @@ import type {
   SSRModule,
 } from "./types.js";
 import {
+  RSC_FLIGHT_HTML_PHASES,
+  RSC_FLIGHT_ONLY_PHASES,
   createResponseWithMergedHeaders,
   finalizeResponse,
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
+  observeRscHtmlStage,
+  renderRscFlightStage,
 } from "./helpers.js";
 import { guardOutgoingRedirect } from "./redirect-guard.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
@@ -52,8 +56,6 @@ import {
 import { contextSet } from "../context-var.js";
 import {
   hasCachedManifest,
-  getRouteTrie,
-  getPrecomputedEntries,
   waitForManifestReady,
   getRouterManifest,
   getRouterTrie,
@@ -301,17 +303,26 @@ export function createRSCHandler<
         ...(locationState && { locationState }),
       },
     };
-    const rscStream = renderToReadableStream<RscPayload>(redirectPayload, {
-      onError: (error: unknown) => {
-        const reqCtx = _getRequestContext<TEnv>();
-        if (!reqCtx) return;
-        callOnError(error, "rendering", {
-          request: reqCtx.request,
-          url: reqCtx.url,
-          env: reqCtx.env,
-        });
-      },
-    });
+    const reqCtx = _getRequestContext<TEnv>();
+    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,
+              phases: RSC_FLIGHT_ONLY_PHASES,
+            },
+          },
+          performance.now(),
+        ).stream
+      : renderToReadableStream<RscPayload>(redirectPayload);
     return createResponseWithMergedHeaders(rscStream, {
       status: 200,
       headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -632,35 +643,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
@@ -1171,13 +1153,31 @@ export function createRSCHandler<
             },
           };
 
-          const rscStream = renderToReadableStream(payload, {
-            onError: (error: unknown) => {
-              callOnError(error, "rendering", { request, url, env });
+          const isNotFoundFlightResponse = isRscRequest(
+            request,
+            url,
+            isPartial,
+          );
+          const notFoundStageTracking = {
+            mode: isPartial ? ("partial" as const) : ("full" as const),
+            routeKey,
+            phases: isNotFoundFlightResponse
+              ? RSC_FLIGHT_ONLY_PHASES
+              : RSC_FLIGHT_HTML_PHASES,
+          };
+          const rscStream = renderRscFlightStage(
+            {
+              ctx: { renderToReadableStream, callOnError },
+              request,
+              url,
+              env,
+              payload,
+              tracking: notFoundStageTracking,
             },
-          });
+            performance.now(),
+          ).stream;
 
-          if (isRscRequest(request, url, isPartial)) {
+          if (isNotFoundFlightResponse) {
             return createResponseWithMergedHeaders(rscStream, {
               status: 404,
               headers: {
@@ -1196,10 +1196,14 @@ export function createRSCHandler<
             url,
             getRequestContext()._metricsStore,
           );
-          const htmlStream = await ssrModule.renderHTML(rscStream, {
-            nonce,
-            streamMode,
-          });
+          const htmlStream = await observeRscHtmlStage(
+            { url, tracking: notFoundStageTracking },
+            () =>
+              ssrModule.renderHTML(rscStream, {
+                nonce,
+                streamMode,
+              }),
+          );
 
           return createResponseWithMergedHeaders(htmlStream, {
             status: 404,

package/src/rsc/helpers.ts

@@ -18,7 +18,468 @@ import {
 } from "../redirect-origin.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import { formatCacheSignalHeader } from "../router/telemetry.js";
+import { appendMetric } from "../router/metrics.js";
 import type { RscPayload } from "./types.js";
+import type { HandlerContext } from "./handler-context.js";
+
+export interface RscRenderStageInput<TEnv> {
+  ctx: Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError">;
+  request: Request;
+  url: URL;
+  env: TEnv;
+  payload: RscPayload;
+  init: ResponseInit;
+  temporaryReferences?: unknown;
+  recordSerializeMetric?: boolean;
+  tracking?: RscRenderStageTracking;
+}
+
+export type RscRenderMode =
+  | "unknown"
+  | "full"
+  | "partial"
+  | "action-revalidation"
+  | "progressive-enhancement"
+  | "progressive-enhancement-error";
+
+export type RscRenderPhase = "payload" | "flight" | "html" | "response";
+
+export const RSC_RENDER_FLIGHT_RESPONSE_PHASES: readonly RscRenderPhase[] = [
+  "payload",
+  "flight",
+  "response",
+];
+
+export const RSC_RENDER_HTML_RESPONSE_PHASES: readonly RscRenderPhase[] = [
+  "payload",
+  "flight",
+  "html",
+  "response",
+];
+
+export const RSC_FLIGHT_ONLY_PHASES: readonly RscRenderPhase[] = ["flight"];
+
+export const RSC_FLIGHT_HTML_PHASES: readonly RscRenderPhase[] = [
+  "flight",
+  "html",
+];
+
+export interface RscRenderStageProgress {
+  completed: number;
+  total: number;
+}
+
+export interface RscRenderStageContext {
+  mode: RscRenderMode;
+  phase: RscRenderPhase;
+  pathname: string;
+  progress: RscRenderStageProgress;
+  startedAt: number;
+  phaseStartedAt: number;
+  routeKey?: string;
+  actionId?: string;
+}
+
+export type RscRenderStageEvent =
+  | {
+      type: "stage:yield";
+      context: RscRenderStageContext;
+    }
+  | {
+      type: "stage:start";
+      context: RscRenderStageContext;
+    }
+  | {
+      type: "stage:complete";
+      context: RscRenderStageContext;
+      durationMs: number;
+    }
+  | {
+      type: "stage:error";
+      context: RscRenderStageContext;
+      durationMs: number;
+      error: unknown;
+    };
+
+export interface RscRenderStageTracking {
+  mode?: RscRenderMode;
+  routeKey?: string;
+  actionId?: string;
+  phases?: readonly RscRenderPhase[];
+  totalStages?: number;
+  onEvent?: (event: RscRenderStageEvent) => void;
+}
+
+export interface RscFlightStageInput<TEnv> {
+  ctx: Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError">;
+  request: Request;
+  url: URL;
+  env: TEnv;
+  payload: RscPayload;
+  temporaryReferences?: unknown;
+  recordSerializeMetric?: boolean;
+  tracking?: RscRenderStageTracking;
+}
+
+export interface RscHtmlStageInput {
+  url: URL;
+  tracking?: RscRenderStageTracking;
+}
+
+export type RscRenderStage =
+  | {
+      type: "payload";
+      payload: RscPayload;
+      init: ResponseInit;
+      context: RscRenderStageContext;
+    }
+  | {
+      type: "flight";
+      payload: RscPayload;
+      stream: ReadableStream<Uint8Array>;
+      init: ResponseInit;
+      durationMs: number;
+      context: RscRenderStageContext;
+    };
+
+export type RscFlightStage = Extract<RscRenderStage, { type: "flight" }>;
+
+export interface RscRenderStageControl {
+  payload?: RscPayload;
+  init?: ResponseInit;
+  body?: BodyInit | null;
+}
+
+interface RscFlightStageResult {
+  stage: RscFlightStage;
+  control: RscRenderStageControl | undefined;
+}
+
+type RscRenderStageSink = NonNullable<RscRenderStageTracking["onEvent"]>;
+
+function rscStagePhases(
+  tracking: RscRenderStageTracking | undefined,
+): readonly RscRenderPhase[] {
+  const phases = tracking?.phases;
+  if (phases && phases.length > 0) return phases;
+  const total = tracking?.totalStages;
+  if (total === 1) return RSC_FLIGHT_ONLY_PHASES;
+  if (total === 2) return RSC_FLIGHT_HTML_PHASES;
+  if (total === 4) return RSC_RENDER_HTML_RESPONSE_PHASES;
+  return RSC_RENDER_FLIGHT_RESPONSE_PHASES;
+}
+
+function createRscStageContext(
+  input: { url: URL; tracking?: RscRenderStageTracking },
+  phase: RscRenderPhase,
+  startedAt: number,
+  phaseStartedAt: number,
+): RscRenderStageContext {
+  const phases = rscStagePhases(input.tracking);
+  const phaseIndex = phases.indexOf(phase);
+  const total = phases.length;
+  const completed = phaseIndex >= 0 ? phaseIndex + 1 : total;
+  return {
+    mode: input.tracking?.mode ?? "unknown",
+    phase,
+    pathname: input.url.pathname,
+    progress: { completed, total },
+    startedAt,
+    phaseStartedAt,
+    ...(input.tracking?.routeKey && { routeKey: input.tracking.routeKey }),
+    ...(input.tracking?.actionId && { actionId: input.tracking.actionId }),
+  };
+}
+
+function getRscStageSink(input: {
+  tracking?: RscRenderStageTracking;
+}): RscRenderStageSink | undefined {
+  return input.tracking?.onEvent;
+}
+
+function emitRscStageEvent(
+  sink: RscRenderStageSink | undefined,
+  createEvent: () => RscRenderStageEvent,
+): void {
+  if (!sink) return;
+  try {
+    sink(createEvent());
+  } catch (error) {
+    if (process.env.NODE_ENV !== "production") {
+      console.error("[RSC] render stage event sink failed:", error);
+    }
+  }
+}
+
+export function renderRscFlightStage<TEnv>(
+  input: RscFlightStageInput<TEnv>,
+  startedAt: number,
+  init: ResponseInit = {},
+): RscFlightStage {
+  const phaseStartedAt = performance.now();
+  const context = createRscStageContext(
+    input,
+    "flight",
+    startedAt,
+    phaseStartedAt,
+  );
+  const sink = getRscStageSink(input);
+  emitRscStageEvent(sink, () => ({ type: "stage:start", context }));
+
+  try {
+    const stream = input.ctx.renderToReadableStream<RscPayload>(input.payload, {
+      temporaryReferences: input.temporaryReferences,
+      onError: (error: unknown) => {
+        input.ctx.callOnError(error, "rendering", {
+          request: input.request,
+          url: input.url,
+          env: input.env,
+        });
+      },
+    });
+    const durationMs = performance.now() - phaseStartedAt;
+    if (input.recordSerializeMetric === true) {
+      appendMetric(
+        _getRequestContext()?._metricsStore,
+        "rsc-serialize",
+        phaseStartedAt,
+        durationMs,
+      );
+    }
+    emitRscStageEvent(sink, () => ({
+      type: "stage:complete",
+      context,
+      durationMs,
+    }));
+
+    return {
+      type: "flight" as const,
+      payload: input.payload,
+      stream,
+      init,
+      durationMs,
+      context,
+    };
+  } catch (error) {
+    emitRscStageEvent(sink, () => ({
+      type: "stage:error",
+      context,
+      durationMs: performance.now() - phaseStartedAt,
+      error,
+    }));
+    throw error;
+  }
+}
+
+async function* createRscFlightStages<TEnv>(
+  input: RscRenderStageInput<TEnv>,
+  payload: RscPayload,
+  init: ResponseInit,
+  startedAt: number,
+): AsyncGenerator<
+  RscFlightStage,
+  RscFlightStageResult,
+  RscRenderStageControl | undefined
+> {
+  const stage = renderRscFlightStage(
+    {
+      ctx: input.ctx,
+      request: input.request,
+      url: input.url,
+      env: input.env,
+      payload,
+      temporaryReferences: input.temporaryReferences,
+      recordSerializeMetric: input.recordSerializeMetric ?? true,
+      tracking: input.tracking,
+    },
+    startedAt,
+    init,
+  );
+  const sink = getRscStageSink(input);
+  emitRscStageEvent(sink, () => ({
+    type: "stage:yield",
+    context: stage.context,
+  }));
+  const control = yield stage;
+  return { stage, control };
+}
+
+export async function observeRscHtmlStage<T>(
+  input: RscHtmlStageInput,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const startedAt = performance.now();
+  const sink = getRscStageSink(input);
+  const context = sink
+    ? createRscStageContext(input, "html", startedAt, startedAt)
+    : undefined;
+  emitRscStageEvent(sink, () => ({
+    type: "stage:start",
+    context: context!,
+  }));
+  try {
+    const result = await fn();
+    emitRscStageEvent(sink, () => ({
+      type: "stage:complete",
+      context: context!,
+      durationMs: performance.now() - startedAt,
+    }));
+    return result;
+  } catch (error) {
+    emitRscStageEvent(sink, () => ({
+      type: "stage:error",
+      context: context!,
+      durationMs: performance.now() - startedAt,
+      error,
+    }));
+    throw error;
+  }
+}
+
+export function createRscStageDebugSink(
+  log: (message: string, details?: Record<string, unknown>) => void = (
+    message,
+    details,
+  ) => console.debug(message, details),
+): (event: RscRenderStageEvent) => void {
+  return (event) => {
+    const { context } = event;
+    log(`[RSC][stage] ${event.type} ${context.phase}`, {
+      mode: context.mode,
+      pathname: context.pathname,
+      routeKey: context.routeKey,
+      actionId: context.actionId,
+      progress: `${context.progress.completed}/${context.progress.total}`,
+      ...("durationMs" in event && { durationMs: event.durationMs }),
+      ...("error" in event && { error: event.error }),
+    });
+  };
+}
+
+/**
+ * Stage the common RSC render flow as a resumable async generator:
+ * payload inspection/mutation -> Flight stream creation -> response finalization.
+ * HTML callers pause at the Flight stage, render SSR from that stream, then
+ * resume with the HTML body/init so header merging still happens once.
+ */
+export async function* createRscRenderStages<TEnv>(
+  input: RscRenderStageInput<TEnv>,
+): AsyncGenerator<RscRenderStage, Response, RscRenderStageControl | undefined> {
+  const startedAt = performance.now();
+  let payload = input.payload;
+  let init = input.init;
+
+  const payloadContext = createRscStageContext(
+    input,
+    "payload",
+    startedAt,
+    startedAt,
+  );
+  const sink = getRscStageSink(input);
+  emitRscStageEvent(sink, () => ({
+    type: "stage:yield",
+    context: payloadContext,
+  }));
+  const payloadControl = yield {
+    type: "payload" as const,
+    payload,
+    init,
+    context: payloadContext,
+  };
+  payload = payloadControl?.payload ?? payload;
+  init = payloadControl?.init ?? init;
+
+  const flightResult = yield* createRscFlightStages(
+    input,
+    payload,
+    init,
+    startedAt,
+  );
+  const flightControl = flightResult.control;
+
+  const body =
+    flightControl && "body" in flightControl
+      ? flightControl.body!
+      : flightResult.stage.stream;
+
+  const phaseStartedAt = performance.now();
+  const responseContext = sink
+    ? createRscStageContext(input, "response", startedAt, phaseStartedAt)
+    : undefined;
+  emitRscStageEvent(sink, () => ({
+    type: "stage:start",
+    context: responseContext!,
+  }));
+  try {
+    const response = createResponseWithMergedHeaders(body, {
+      ...init,
+      ...flightControl?.init,
+    });
+    emitRscStageEvent(sink, () => ({
+      type: "stage:complete",
+      context: responseContext!,
+      durationMs: performance.now() - phaseStartedAt,
+    }));
+    return response;
+  } catch (error) {
+    emitRscStageEvent(sink, () => ({
+      type: "stage:error",
+      context: responseContext!,
+      durationMs: performance.now() - phaseStartedAt,
+      error,
+    }));
+    throw error;
+  }
+}
+
+export async function runRscRenderStages(
+  stages: AsyncGenerator<
+    RscRenderStage,
+    Response,
+    RscRenderStageControl | undefined
+  >,
+): Promise<Response> {
+  for (;;) {
+    const step = await stages.next();
+    if (step.done) return step.value;
+  }
+}
+
+export async function readRscFlightStage(
+  stages: AsyncGenerator<
+    RscRenderStage,
+    Response,
+    RscRenderStageControl | undefined
+  >,
+): Promise<RscFlightStage> {
+  const payloadStage = await stages.next();
+  if (payloadStage.done || payloadStage.value.type !== "payload") {
+    throw new Error("[RSC] render stage pipeline skipped payload stage");
+  }
+
+  const flightStage = await stages.next();
+  if (flightStage.done || flightStage.value.type !== "flight") {
+    throw new Error("[RSC] render stage pipeline skipped Flight stream");
+  }
+
+  return flightStage.value;
+}
+
+export async function finishRscRenderStages(
+  stages: AsyncGenerator<
+    RscRenderStage,
+    Response,
+    RscRenderStageControl | undefined
+  >,
+  control?: RscRenderStageControl,
+): Promise<Response> {
+  const responseStage = await stages.next(control);
+  if (!responseStage.done) {
+    throw new Error("[RSC] render stage pipeline did not finish response");
+  }
+
+  return responseStage.value;
+}
 
 /**
  * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,