@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

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

@@ -22,7 +22,11 @@ import type {
   SegmentRevalidationResult,
   ActionContext,
 } from "../types.js";
-import { debugLog } from "../logging.js";
+import {
+  debugLog,
+  pushRevalidationTraceEntry,
+  isTraceActive,
+} from "../logging.js";
 import { resolveLoaderData } from "./loader-cache.js";
 import {
   handleHandlerResult,
@@ -31,6 +35,84 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
 } from "./helpers.js";
+import { getRouterContext } from "../router-context.js";
+import { resolveSink, safeEmit } from "../telemetry.js";
+
+// ---------------------------------------------------------------------------
+// Telemetry helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a fire-and-forget rejection observer to a streamed handler promise.
+ * Silently no-ops when called outside RouterContext (e.g. in unit tests).
+ */
+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,
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Revalidation telemetry helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit revalidation.decision telemetry for a segment if a sink is configured.
+ * Called after evaluateRevalidation returns to capture the decision.
+ * Silently no-ops when called outside RouterContext (e.g. in unit tests).
+ */
+function emitRevalidationDecision(
+  segmentId: string,
+  pathname: string,
+  routeKey: string,
+  shouldRevalidate: boolean,
+): void {
+  let routerCtx;
+  try {
+    routerCtx = getRouterContext();
+  } catch {
+    return;
+  }
+  if (routerCtx?.telemetry) {
+    safeEmit(resolveSink(routerCtx.telemetry), {
+      type: "revalidation.decision",
+      timestamp: performance.now(),
+      requestId: routerCtx.requestId,
+      segmentId,
+      pathname,
+      routeKey,
+      shouldRevalidate,
+    });
+  }
+}
 
 // ---------------------------------------------------------------------------
 // Revalidation path (partial match)
@@ -81,7 +163,20 @@ export async function resolveLoadersWithRevalidation<TEnv>(
       }) => {
         const shouldRun = await revalidate(
           async () => {
-            if (!clientSegmentIds.has(segmentId)) return true;
+            if (!clientSegmentIds.has(segmentId)) {
+              if (isTraceActive()) {
+                pushRevalidationTraceEntry({
+                  segmentId,
+                  segmentType: "loader",
+                  belongsToRoute,
+                  source: "loader",
+                  defaultShouldRevalidate: true,
+                  finalShouldRevalidate: true,
+                  reason: "new-segment",
+                });
+              }
+              return true;
+            }
 
             const dummySegment: ResolvedSegment = {
               id: segmentId,
@@ -109,11 +204,13 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               context: ctx,
               actionContext,
               stale,
+              traceSource: "loader",
             });
           },
           async () => true,
           () => false,
         );
+        emitRevalidationDecision(segmentId, ctx.pathname, routeKey, shouldRun);
         return { shouldRun, loaderEntry, loader, segmentId, index };
       },
     ),
@@ -156,6 +253,7 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
   routeKey: string,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
+  stale?: boolean,
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
   const allLoaderSegments: ResolvedSegment[] = [];
   const allMatchedIds: string[] = [];
@@ -174,6 +272,8 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
       routeKey,
       deps,
       actionContext,
+      undefined, // shortCodeOverride
+      stale,
     );
     allLoaderSegments.push(...segments);
     allMatchedIds.push(...matchedIds);
@@ -279,9 +379,35 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       }
 
       const shouldResolve = await (async () => {
-        if (isFullRefetch) return true;
-        if (!clientSegmentIds.has(parallelId))
-          return belongsToRoute || isNewParent;
+        if (isFullRefetch) {
+          if (isTraceActive()) {
+            pushRevalidationTraceEntry({
+              segmentId: parallelId,
+              segmentType: "parallel",
+              belongsToRoute,
+              source: "parallel",
+              defaultShouldRevalidate: true,
+              finalShouldRevalidate: true,
+              reason: "full-refetch",
+            });
+          }
+          return true;
+        }
+        if (!clientSegmentIds.has(parallelId)) {
+          const result = belongsToRoute || isNewParent;
+          if (isTraceActive()) {
+            pushRevalidationTraceEntry({
+              segmentId: parallelId,
+              segmentType: "parallel",
+              belongsToRoute,
+              source: "parallel",
+              defaultShouldRevalidate: result,
+              finalShouldRevalidate: result,
+              reason: result ? "new-segment" : "skip-parent-chain",
+            });
+          }
+          return result;
+        }
 
         const dummySegment: ResolvedSegment = {
           id: parallelId,
@@ -313,8 +439,15 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
           context,
           actionContext,
           stale,
+          traceSource: "parallel",
         });
       })();
+      emitRevalidationDecision(
+        parallelId,
+        context.pathname,
+        routeKey,
+        shouldResolve,
+      );
 
       let component: ReactNode | undefined;
       if (shouldResolve) {
@@ -327,9 +460,25 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         if (!shouldResolve) {
           component = null;
         } else if (hasLoadingFallback) {
-          component = (
-            typeof handler === "function" ? handler(context) : handler
-          ) as ReactNode;
+          const result =
+            typeof handler === "function" ? handler(context) : handler;
+          if (result instanceof Promise) {
+            const tracked = deps.trackHandler(result, {
+              segmentId: parallelId,
+              segmentType: "parallel",
+            });
+            observeStreamedHandler(
+              tracked,
+              parallelId,
+              "parallel",
+              context.pathname,
+              routeKey,
+              params,
+            );
+            component = tracked as ReactNode;
+          } else {
+            component = result as ReactNode;
+          }
         } else {
           component =
             typeof handler === "function" ? await handler(context) : handler;
@@ -407,7 +556,24 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         clientHasSegment: hasSegment,
         belongsToRoute,
       });
-      if (!hasSegment) return true;
+      if (!hasSegment) {
+        if (isTraceActive()) {
+          const segType =
+            entry.type === "cache"
+              ? "layout"
+              : (entry.type as "layout" | "route");
+          pushRevalidationTraceEntry({
+            segmentId: entry.shortCode,
+            segmentType: segType,
+            belongsToRoute,
+            source: "segment-resolution",
+            defaultShouldRevalidate: true,
+            finalShouldRevalidate: true,
+            reason: "new-segment",
+          });
+        }
+        return true;
+      }
 
       const dummySegment: ResolvedSegment = {
         id: entry.shortCode,
@@ -442,6 +608,12 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         actionContext,
         stale,
       });
+      emitRevalidationDecision(
+        entry.shortCode,
+        context.pathname,
+        routeKey,
+        shouldRevalidate,
+      );
       debugLog("segment.revalidate", "entry revalidation decision", {
         segmentId: entry.shortCode,
         shouldRevalidate,
@@ -462,10 +634,22 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       }
       if (!actionContext) {
         const result = handleHandlerResult(routeEntry.handler(context));
-        return {
-          content:
-            result instanceof Promise ? deps.trackHandler(result) : result,
-        };
+        if (result instanceof Promise) {
+          const tracked = deps.trackHandler(result, {
+            segmentId: entry.shortCode,
+            segmentType: entry.type,
+          });
+          observeStreamedHandler(
+            tracked,
+            entry.shortCode,
+            entry.type,
+            context.pathname,
+            routeKey,
+            params,
+          );
+          return { content: tracked };
+        }
+        return { content: result };
       }
       debugLog("segment.action", "resolving action route with awaited value", {
         entryId: entry.id,
@@ -590,31 +774,32 @@ export async function resolveSegmentWithRevalidation<TEnv>(
     }
   }
 
-  const parallelResult = await resolveParallelSegmentsWithRevalidation(
-    entry,
-    params,
-    context,
-    belongsToRoute,
-    clientSegmentIds,
-    prevParams,
-    request,
-    prevUrl,
-    nextUrl,
-    routeKey,
-    deps,
-    actionContext,
-    stale,
-  );
-  segments.push(...parallelResult.segments);
-  matchedIds.push(...parallelResult.matchedIds);
-
-  // Push handler BEFORE orphan layouts for layout/cache entries (matching SSR
-  // order in resolveSegment). Route handler was already executed and is pushed
-  // after children for tree composition.
   if (routeHandlerResult) {
+    // Route entry: handler already executed above; resolve parallels
+    // (handler data visible) then push handler segment last for tree order.
+    const parallelResult = await resolveParallelSegmentsWithRevalidation(
+      entry,
+      params,
+      context,
+      belongsToRoute,
+      clientSegmentIds,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      routeKey,
+      deps,
+      actionContext,
+      stale,
+    );
+    segments.push(...parallelResult.segments);
+    matchedIds.push(...parallelResult.matchedIds);
+
     segments.push(routeHandlerResult.segment);
     matchedIds.push(routeHandlerResult.matchedId);
   } else {
+    // Layout/cache entry: handler-first — resolve handler before parallels
+    // so ctx.set() values are visible to parallel children.
     const handlerResult = await resolveEntryHandlerWithRevalidation(
       entry,
       params,
@@ -632,9 +817,25 @@ export async function resolveSegmentWithRevalidation<TEnv>(
     );
     segments.push(handlerResult.segment);
     matchedIds.push(handlerResult.matchedId);
-  }
 
-  if (entry.type === "layout" || entry.type === "cache") {
+    const parallelResult = await resolveParallelSegmentsWithRevalidation(
+      entry,
+      params,
+      context,
+      belongsToRoute,
+      clientSegmentIds,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      routeKey,
+      deps,
+      actionContext,
+      stale,
+    );
+    segments.push(...parallelResult.segments);
+    matchedIds.push(...parallelResult.matchedIds);
+
     for (const orphan of entry.layout) {
       const orphanResult = await resolveOrphanLayoutWithRevalidation(
         orphan,
@@ -705,6 +906,82 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   segments.push(...loaderResult.segments);
   matchedIds.push(...loaderResult.matchedIds);
 
+  // Handler-first: resolve orphan layout handler before its parallels
+  // so ctx.set() values are visible to parallel children.
+  matchedIds.push(orphan.shortCode);
+
+  const component = await revalidate(
+    async () => {
+      if (!clientSegmentIds.has(orphan.shortCode)) {
+        if (isTraceActive()) {
+          pushRevalidationTraceEntry({
+            segmentId: orphan.shortCode,
+            segmentType: "layout",
+            belongsToRoute,
+            source: "orphan-layout",
+            defaultShouldRevalidate: true,
+            finalShouldRevalidate: true,
+            reason: "new-segment",
+          });
+        }
+        return true;
+      }
+
+      const dummySegment: ResolvedSegment = {
+        id: orphan.shortCode,
+        namespace: orphan.id,
+        type: "layout",
+        index: 0,
+        component: null as any,
+        params,
+        belongsToRoute,
+        layoutName: orphan.id,
+        ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
+      };
+
+      const shouldRevalidate = await evaluateRevalidation({
+        segment: dummySegment,
+        prevParams,
+        getPrevSegment: null,
+        request,
+        prevUrl,
+        nextUrl,
+        revalidations: orphan.revalidate.map((fn, i) => ({
+          name: `revalidate${i}`,
+          fn,
+        })),
+        routeKey,
+        context,
+        actionContext,
+        stale,
+        traceSource: "orphan-layout",
+      });
+      emitRevalidationDecision(
+        orphan.shortCode,
+        context.pathname,
+        routeKey,
+        shouldRevalidate,
+      );
+      return shouldRevalidate;
+    },
+    async () => resolveLayoutComponent(orphan, context),
+    () => null,
+  );
+
+  segments.push({
+    id: orphan.shortCode,
+    namespace: orphan.id,
+    type: "layout",
+    index: 0,
+    component,
+    params,
+    belongsToRoute,
+    layoutName: orphan.id,
+    loading: orphan.loading === false ? null : orphan.loading,
+    transition: orphan.transition,
+    ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
+  });
+
   for (const parallelEntry of orphan.parallel) {
     invariant(
       parallelEntry.type === "parallel",
@@ -743,7 +1020,20 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       matchedIds.push(parallelId);
 
       const shouldResolve = await (async () => {
-        if (!clientSegmentIds.has(parallelId)) return true;
+        if (!clientSegmentIds.has(parallelId)) {
+          if (isTraceActive()) {
+            pushRevalidationTraceEntry({
+              segmentId: parallelId,
+              segmentType: "parallel",
+              belongsToRoute,
+              source: "parallel",
+              defaultShouldRevalidate: true,
+              finalShouldRevalidate: true,
+              reason: "new-segment",
+            });
+          }
+          return true;
+        }
 
         const dummySegment: ResolvedSegment = {
           id: parallelId,
@@ -775,8 +1065,15 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
           context,
           actionContext,
           stale,
+          traceSource: "parallel",
         });
       })();
+      emitRevalidationDecision(
+        parallelId,
+        context.pathname,
+        routeKey,
+        shouldResolve,
+      );
 
       let component: ReactNode | undefined;
       if (shouldResolve) {
@@ -789,9 +1086,25 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         if (!shouldResolve) {
           component = null;
         } else if (hasLoadingFallback) {
-          component = (
-            typeof handler === "function" ? handler(context) : handler
-          ) as ReactNode;
+          const result =
+            typeof handler === "function" ? handler(context) : handler;
+          if (result instanceof Promise) {
+            const tracked = deps.trackHandler(result, {
+              segmentId: parallelId,
+              segmentType: "parallel",
+            });
+            observeStreamedHandler(
+              tracked,
+              parallelId,
+              "parallel",
+              context.pathname,
+              routeKey,
+              params,
+            );
+            component = tracked as ReactNode;
+          } else {
+            component = result as ReactNode;
+          }
         } else {
           component =
             typeof handler === "function" ? await handler(context) : handler;
@@ -817,59 +1130,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     }
   }
 
-  matchedIds.push(orphan.shortCode);
-
-  const component = await revalidate(
-    async () => {
-      if (!clientSegmentIds.has(orphan.shortCode)) return true;
-
-      const dummySegment: ResolvedSegment = {
-        id: orphan.shortCode,
-        namespace: orphan.id,
-        type: "layout",
-        index: 0,
-        component: null as any,
-        params,
-        belongsToRoute,
-        layoutName: orphan.id,
-        ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
-      };
-
-      return await evaluateRevalidation({
-        segment: dummySegment,
-        prevParams,
-        getPrevSegment: null,
-        request,
-        prevUrl,
-        nextUrl,
-        revalidations: orphan.revalidate.map((fn, i) => ({
-          name: `revalidate${i}`,
-          fn,
-        })),
-        routeKey,
-        context,
-        actionContext,
-        stale,
-      });
-    },
-    async () => resolveLayoutComponent(orphan, context),
-    () => null,
-  );
-
-  segments.push({
-    id: orphan.shortCode,
-    namespace: orphan.id,
-    type: "layout",
-    index: 0,
-    component,
-    params,
-    belongsToRoute,
-    layoutName: orphan.id,
-    loading: orphan.loading === false ? null : orphan.loading,
-    transition: orphan.transition,
-    ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
-  });
-
   return { segments, matchedIds };
 }
 
@@ -898,6 +1158,8 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
   const seenSegIds = new Set<string>();
   const seenMatchIds = new Set<string>();
 
+  const telemetry = getRouterContext()?.telemetry;
+
   for (const entry of entries) {
     if (entry.type === "route" && interceptResult) {
       debugLog(
@@ -937,7 +1199,9 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
         ),
       (seg) => ({ segments: [seg], matchedIds: [seg.id] }),
       deps,
-      undefined,
+      telemetry
+        ? { request, url: context.url, routeKey, isPartial: true, telemetry }
+        : undefined,
       pathname,
     );
 

package/src/router/segment-wrappers.ts

@@ -50,6 +50,7 @@ export interface SegmentWrappers<TEnv = any> {
       actionResult?: any;
       formData?: FormData;
     },
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
   buildEntryRevalidateMap: (
     entries: EntryData[],
@@ -158,6 +159,7 @@ export function createSegmentWrappers<TEnv = any>(
       actionResult?: any;
       formData?: FormData;
     },
+    stale?: boolean,
   ): ReturnType<typeof _resolveLoadersOnlyWithRevalidation> {
     return _resolveLoadersOnlyWithRevalidation(
       entries,
@@ -170,6 +172,7 @@ export function createSegmentWrappers<TEnv = any>(
       routeKey,
       segmentDeps,
       actionContext,
+      stale,
     );
   }