@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/router/segment-resolution/fresh.ts

@@ -7,7 +7,11 @@
 
 import type { ReactNode } from "react";
 import { invariant } from "../../errors";
-import type { EntryData } from "../../server/context";
+import {
+  getParallelEntries,
+  getParallelSlotEntries,
+  type EntryData,
+} from "../../server/context";
 import type {
   HandlerContext,
   InternalHandlerContext,
@@ -15,6 +19,8 @@ import type {
 } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { resolveLoaderData } from "./loader-cache.js";
+import { _getRequestContext } from "../../server/request-context.js";
+import { appendMetric } from "../metrics.js";
 import {
   handleHandlerResult,
   tryStaticHandler,
@@ -22,6 +28,56 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
 } from "./helpers.js";
+import { getRouterContext } from "../router-context.js";
+import { resolveSink, safeEmit } from "../telemetry.js";
+import {
+  track,
+  RSCRouterContext,
+  runInsideLoaderScope,
+} from "../../server/context.js";
+
+// ---------------------------------------------------------------------------
+// Streamed handler telemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a fire-and-forget rejection observer to a streamed handler promise.
+ * React catches the actual error via its error boundary; this only emits
+ * the handler.error telemetry event.
+ */
+function observeStreamedHandler(
+  promise: Promise<ReactNode>,
+  segmentId: string,
+  segmentType: string,
+  pathname?: string,
+  routeKey?: string,
+  params?: Record<string, string>,
+): void {
+  let routerCtx;
+  try {
+    routerCtx = getRouterContext();
+  } catch {
+    return;
+  }
+  if (!routerCtx?.telemetry) return;
+  const sink = resolveSink(routerCtx.telemetry);
+  const reqId = routerCtx.requestId;
+  promise.catch((err: unknown) => {
+    const errorObj = err instanceof Error ? err : new Error(String(err));
+    safeEmit(sink, {
+      type: "handler.error",
+      timestamp: performance.now(),
+      requestId: reqId,
+      segmentId,
+      segmentType,
+      error: errorObj,
+      handledByBoundary: true,
+      pathname,
+      routeKey,
+      params,
+    });
+  });
+}
 
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
@@ -44,9 +100,11 @@ export async function resolveLoaders<TEnv>(
   const shortCode = shortCodeOverride ?? entry.shortCode;
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
+  const ms = _getRequestContext()?._metricsStore;
 
   if (!loadingDisabled) {
-    return loaderEntries.map((loaderEntry, i) => {
+    // Streaming loaders: promises kick off now, settle during RSC serialization.
+    const segments = loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;
       const segmentId = `${shortCode}D${i}.${loader.$$id}`;
       return {
@@ -58,7 +116,9 @@ export async function resolveLoaders<TEnv>(
         params: ctx.params,
         loaderId: loader.$$id,
         loaderData: deps.wrapLoaderPromise(
-          resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+          runInsideLoaderScope(() =>
+            resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+          ),
           entry,
           segmentId,
           ctx.pathname,
@@ -66,18 +126,38 @@ export async function resolveLoaders<TEnv>(
         belongsToRoute,
       };
     });
+
+    return segments;
   }
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  const pendingLoaderData = loaderEntries.map((loaderEntry) =>
-    resolveLoaderData(loaderEntry, ctx, ctx.pathname),
-  );
-  await Promise.all(pendingLoaderData);
+  const pendingLoaderData = loaderEntries.map((loaderEntry) => {
+    const start = performance.now();
+    const promise = runInsideLoaderScope(() =>
+      resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+    );
+    return { promise, start, loaderId: loaderEntry.loader.$$id };
+  });
+  await Promise.all(pendingLoaderData.map((p) => p.promise));
 
   return loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
+    const pending = pendingLoaderData[i]!;
+    if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
+      // All loaders ran in parallel via Promise.all — each span covers
+      // from its own kickoff to the batch settlement, giving a ceiling
+      // on that loader's contribution to the overall wait.
+      const batchEnd = performance.now();
+      appendMetric(
+        ms,
+        `loader:${loader.$$id}`,
+        pending.start,
+        batchEnd - pending.start,
+        2,
+      );
+    }
     return {
       id: segmentId,
       namespace: entry.id,
@@ -87,7 +167,7 @@ export async function resolveLoaders<TEnv>(
       params: ctx.params,
       loaderId: loader.$$id,
       loaderData: deps.wrapLoaderPromise(
-        pendingLoaderData[i]!,
+        pending.promise,
         entry,
         segmentId,
         ctx.pathname,
@@ -128,23 +208,14 @@ export async function resolveSegment<TEnv>(
       segments.push(...loaderSegments);
     }
 
-    for (const parallelEntry of entry.parallel) {
-      const parallelSegments = await resolveParallelEntry(
-        parallelEntry,
-        params,
-        context,
-        false,
-        entry.shortCode,
-        deps,
-        options,
-      );
-      segments.push(...parallelSegments);
-    }
-
+    // Handler-first: layout handler executes before its parallels and orphan
+    // layouts so that ctx.set() values are visible to all children.
     (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
       entry.shortCode;
 
+    const doneLayoutHandler = track(`handler:${entry.id}`, 2);
     const component = await resolveLayoutComponent(entry, context);
+    doneLayoutHandler();
 
     segments.push({
       id: entry.shortCode,
@@ -160,6 +231,26 @@ export async function resolveSegment<TEnv>(
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
     });
 
+    const resolvedParallelEntries = new Set<string>();
+    for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+      entry.parallel,
+    )) {
+      const parallelSegments = await resolveParallelEntry(
+        parallelEntry,
+        params,
+        context,
+        false,
+        entry.shortCode,
+        deps,
+        options,
+        routeKey,
+        [slot],
+        !resolvedParallelEntries.has(parallelEntry.id),
+      );
+      segments.push(...parallelSegments);
+      resolvedParallelEntries.add(parallelEntry.id);
+    }
+
     for (const orphan of entry.layout) {
       const orphanSegments = await resolveOrphanLayout(
         orphan,
@@ -169,6 +260,7 @@ export async function resolveSegment<TEnv>(
         false,
         deps,
         options,
+        routeKey,
       );
       segments.push(...orphanSegments);
     }
@@ -192,12 +284,31 @@ export async function resolveSegment<TEnv>(
       entry.shortCode,
     );
     if (component === undefined) {
+      const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
         const result = handleHandlerResult(entry.handler(context));
-        component =
-          result instanceof Promise ? deps.trackHandler(result) : result;
+        if (result instanceof Promise) {
+          result.finally(doneRouteHandler).catch(() => {});
+          const tracked = deps.trackHandler(result, {
+            segmentId: entry.shortCode,
+            segmentType: entry.type,
+          });
+          observeStreamedHandler(
+            tracked,
+            entry.shortCode,
+            entry.type,
+            context.pathname,
+            routeKey,
+            params,
+          );
+          component = tracked;
+        } else {
+          doneRouteHandler();
+          component = result;
+        }
       } else {
         component = handleHandlerResult(await entry.handler(context));
+        doneRouteHandler();
       }
     }
 
@@ -210,11 +321,15 @@ export async function resolveSegment<TEnv>(
         true,
         deps,
         options,
+        routeKey,
       );
       segments.push(...orphanSegments);
     }
 
-    for (const parallelEntry of entry.parallel) {
+    const resolvedParallelEntries = new Set<string>();
+    for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+      entry.parallel,
+    )) {
       const parallelSegments = await resolveParallelEntry(
         parallelEntry,
         params,
@@ -223,8 +338,12 @@ export async function resolveSegment<TEnv>(
         entry.shortCode,
         deps,
         options,
+        routeKey,
+        [slot],
+        !resolvedParallelEntries.has(parallelEntry.id),
       );
       segments.push(...parallelSegments);
+      resolvedParallelEntries.add(parallelEntry.id);
     }
 
     segments.push({
@@ -232,7 +351,7 @@ export async function resolveSegment<TEnv>(
       namespace: entry.id,
       type: "route",
       index: 0,
-      component,
+      component: component ?? null,
       loading: entry.loading === false ? null : entry.loading,
       transition: entry.transition,
       params,
@@ -257,6 +376,7 @@ export async function resolveOrphanLayout<TEnv>(
   belongsToRoute: boolean,
   deps: SegmentResolutionDeps<TEnv>,
   options?: ResolveSegmentOptions,
+  routeKey?: string,
 ): Promise<ResolvedSegment[]> {
   invariant(
     orphan.type === "layout" || orphan.type === "cache",
@@ -274,20 +394,11 @@ export async function resolveOrphanLayout<TEnv>(
     segments.push(...loaderSegments);
   }
 
-  for (const parallelEntry of orphan.parallel) {
-    const parallelSegments = await resolveParallelEntry(
-      parallelEntry,
-      params,
-      context,
-      belongsToRoute,
-      orphan.shortCode,
-      deps,
-      options,
-    );
-    segments.push(...parallelSegments);
-  }
-
+  // Handler-first: orphan layout handler executes before its parallels
+  // so that ctx.set() values are visible to parallel children.
+  const doneOrphanHandler = track(`handler:${orphan.id}`, 2);
   const component = await resolveLayoutComponent(orphan, context);
+  doneOrphanHandler();
 
   segments.push({
     id: orphan.shortCode,
@@ -303,6 +414,26 @@ export async function resolveOrphanLayout<TEnv>(
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
+  const resolvedParallelEntries = new Set<string>();
+  for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+    orphan.parallel,
+  )) {
+    const parallelSegments = await resolveParallelEntry(
+      parallelEntry,
+      params,
+      context,
+      belongsToRoute,
+      orphan.shortCode,
+      deps,
+      options,
+      routeKey,
+      [slot],
+      !resolvedParallelEntries.has(parallelEntry.id),
+    );
+    segments.push(...parallelSegments);
+    resolvedParallelEntries.add(parallelEntry.id);
+  }
+
   return segments;
 }
 
@@ -317,6 +448,9 @@ export async function resolveParallelEntry<TEnv>(
   parentShortCode: string,
   deps: SegmentResolutionDeps<TEnv>,
   options?: ResolveSegmentOptions,
+  routeKey?: string,
+  slotNames?: `@${string}`[],
+  includeLoaders: boolean = true,
 ): Promise<ResolvedSegment[]> {
   invariant(
     parallelEntry.type === "parallel",
@@ -331,7 +465,12 @@ export async function resolveParallelEntry<TEnv>(
     | ReactNode
   >;
 
-  for (const [slot, handler] of Object.entries(slots)) {
+  const slotsToResolve = slotNames ?? (Object.keys(slots) as `@${string}`[]);
+
+  for (const slot of slotsToResolve) {
+    // Try static lookup first — in production, handler bodies are evicted
+    // and replaced with stubs that have no .handler property (undefined).
+    // The static store holds the pre-rendered component for these slots.
     let component: ReactNode | undefined = await tryStaticSlot(
       parallelEntry,
       slot,
@@ -339,15 +478,42 @@ export async function resolveParallelEntry<TEnv>(
     );
 
     if (component === undefined) {
+      const handler = slots[slot];
+      if (handler === undefined) {
+        continue;
+      }
+      const doneParallelHandler = track(
+        `handler:${parallelEntry.id}.${slot}`,
+        2,
+      );
       const hasLoadingFallback =
         parallelEntry.loading !== undefined && parallelEntry.loading !== false;
       if (hasLoadingFallback) {
         const result =
           typeof handler === "function" ? handler(context) : handler;
-        component = result as ReactNode;
+        if (result instanceof Promise) {
+          result.finally(doneParallelHandler).catch(() => {});
+          const tracked = deps.trackHandler(result, {
+            segmentId: `${parentShortCode}.${slot}`,
+            segmentType: "parallel",
+          });
+          observeStreamedHandler(
+            tracked,
+            `${parentShortCode}.${slot}`,
+            "parallel",
+            context.pathname,
+            routeKey,
+            params,
+          );
+          component = tracked as ReactNode;
+        } else {
+          doneParallelHandler();
+          component = result as ReactNode;
+        }
       } else {
         component =
           typeof handler === "function" ? await handler(context) : handler;
+        doneParallelHandler();
       }
     }
 
@@ -369,7 +535,7 @@ export async function resolveParallelEntry<TEnv>(
     });
   }
 
-  if (!parallelEntry.loading && !options?.skipLoaders) {
+  if (!options?.skipLoaders && includeLoaders) {
     const loaderSegments = await resolveLoaders(
       parallelEntry,
       context,
@@ -377,6 +543,15 @@ export async function resolveParallelEntry<TEnv>(
       deps,
       parentShortCode,
     );
+    // Tag parallel-owned loaders so renderSegments can stream them
+    // using the parallel's loading() instead of awaiting on the layout
+    const parallelLoading =
+      parallelEntry.loading === false ? undefined : parallelEntry.loading;
+    if (parallelLoading) {
+      for (const seg of loaderSegments) {
+        seg.parallelLoading = parallelLoading;
+      }
+    }
     segments.push(...loaderSegments);
   }
 
@@ -405,7 +580,21 @@ export async function resolveAllSegments<TEnv>(
     safeRequest = context.request;
   } catch {}
 
+  // Get telemetry sink from RouterContext (may not exist during prerendering)
+  let telemetry;
+  try {
+    telemetry = getRouterContext()?.telemetry;
+  } catch {}
+
   for (const entry of entries) {
+    // Set ALS flag when entering a cache() boundary so that ctx.get()
+    // can guard non-cacheable variable reads. Also guards response-level
+    // side effects (headers.set). Persists for all descendant entries.
+    if (entry.type === "cache") {
+      const store = RSCRouterContext.getStore();
+      if (store) store.insideCacheScope = true;
+    }
+    const doneEntry = track(`segment:${entry.id}`, 1);
     const resolvedSegments = await resolveWithErrorBoundary(
       entry,
       params,
@@ -422,9 +611,10 @@ export async function resolveAllSegments<TEnv>(
         ),
       (seg) => [seg],
       deps,
-      { request: safeRequest, url: context.url, routeKey },
+      { request: safeRequest, url: context.url, routeKey, telemetry },
       context.pathname,
     );
+    doneEntry();
     // Deduplicate by segment ID. include() scopes can produce entries that
     // resolve the same shared layout/loader segment. Duplicates in the segment
     // array propagate to the client's matched[] and change the React tree depth.
@@ -448,11 +638,53 @@ export async function resolveLoadersOnly<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
 ): Promise<ResolvedSegment[]> {
   const loaderSegments: ResolvedSegment[] = [];
+  const seenIds = new Set<string>();
+
+  async function collectEntryLoaders(
+    entry: EntryData,
+    belongsToRoute: boolean,
+    shortCodeOverride?: string,
+  ): Promise<void> {
+    // Skip if all loaders from this entry have already been resolved
+    // via a parent (e.g., cache boundary wrapping a layout with shared loaders).
+    const entryLoaders = entry.loader ?? [];
+    const sc = shortCodeOverride ?? entry.shortCode;
+    const allAlreadySeen =
+      entryLoaders.length > 0 &&
+      entryLoaders.every((le, i) =>
+        seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
+      );
+    if (!allAlreadySeen) {
+      const segments = await resolveLoaders(
+        entry,
+        context,
+        belongsToRoute,
+        deps,
+        shortCodeOverride,
+      );
+      for (const seg of segments) {
+        if (!seenIds.has(seg.id)) {
+          seenIds.add(seg.id);
+          loaderSegments.push(seg);
+        }
+      }
+    }
+
+    const seenParallelEntryIds = new Set<string>();
+    for (const parallelEntry of getParallelEntries(entry.parallel)) {
+      if (seenParallelEntryIds.has(parallelEntry.id)) continue;
+      seenParallelEntryIds.add(parallelEntry.id);
+      await collectEntryLoaders(parallelEntry, belongsToRoute, entry.shortCode);
+    }
+
+    const childBelongsToRoute = belongsToRoute || entry.type === "route";
+    for (const layoutEntry of entry.layout) {
+      await collectEntryLoaders(layoutEntry, childBelongsToRoute);
+    }
+  }
 
   for (const entry of entries) {
-    const belongsToRoute = entry.type === "route";
-    const segments = await resolveLoaders(entry, context, belongsToRoute, deps);
-    loaderSegments.push(...segments);
+    await collectEntryLoaders(entry, entry.type === "route");
   }
 
   return loaderSegments;

package/src/router/segment-resolution/helpers.ts

@@ -8,7 +8,7 @@
  * - Error boundary segment creation
  */
 
-import type { ReactNode } from "react";
+import { createElement, type ReactNode } from "react";
 import { DataNotFoundError } from "../../errors";
 import {
   createErrorInfo,
@@ -23,6 +23,8 @@ import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
+import type { TelemetrySink } from "../telemetry.js";
+import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
 // ---------------------------------------------------------------------------
 // Handler result processing
@@ -116,6 +118,7 @@ export interface ErrorReportContext {
   env?: any;
   isPartial?: boolean;
   requestStartTime?: number;
+  telemetry?: TelemetrySink;
 }
 
 /**
@@ -150,45 +153,66 @@ export function catchSegmentError<TEnv>(
       metadata,
       requestStartTime: report.requestStartTime,
     });
+    if (report.telemetry) {
+      const errorObj =
+        error instanceof Error ? error : new Error(String(error));
+      safeEmit(resolveSink(report.telemetry), {
+        type: "handler.error",
+        timestamp: performance.now(),
+        requestId: report.request ? getRequestId(report.request) : undefined,
+        segmentId: entry.shortCode,
+        segmentType: entry.type,
+        error: errorObj,
+        handledByBoundary,
+        pathname,
+        routeKey: report.routeKey,
+        params,
+      });
+    }
   };
 
   const setResponseStatus = (status: number) => {
     const reqCtx = getRequestContext();
     if (reqCtx) {
-      reqCtx.setStatus(status);
+      reqCtx._setStatus(status);
     }
   };
 
   if (error instanceof DataNotFoundError) {
     const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
+    // Fall back to router's notFound component, then a plain default
+    const notFoundOption = deps.notFoundComponent;
+    const defaultFallback =
+      typeof notFoundOption === "function"
+        ? notFoundOption({ pathname: pathname ?? "" })
+        : (notFoundOption ?? createElement("h1", null, "Not Found"));
+    const effectiveNotFoundFallback = notFoundFallback ?? defaultFallback;
 
-    if (notFoundFallback) {
-      const notFoundInfo = createNotFoundInfo(
-        error,
-        entry.shortCode,
-        entry.type,
-        pathname,
-      );
+    const notFoundInfo = createNotFoundInfo(
+      error,
+      entry.shortCode,
+      entry.type,
+      pathname,
+    );
 
-      reportError(true, {
-        notFound: true,
-        message: notFoundInfo.message,
-      });
+    reportError(true, {
+      notFound: true,
+      message: notFoundInfo.message,
+    });
 
-      debugLog("segment", "notFound boundary handled error", {
-        segmentId: entry.shortCode,
-        message: notFoundInfo.message,
-      });
+    debugLog("segment", "notFound boundary handled error", {
+      segmentId: entry.shortCode,
+      message: notFoundInfo.message,
+    });
 
-      setResponseStatus(404);
+    setResponseStatus(404);
 
-      return createNotFoundSegment(
-        notFoundInfo,
-        notFoundFallback,
-        entry,
-        params,
-      );
-    }
+    return createNotFoundSegment(
+      notFoundInfo,
+      effectiveNotFoundFallback,
+      entry,
+      params,
+    );
   }
 
   const fallback = deps.findNearestErrorBoundary(entry);