@rangojs/router 0.0.0-experimental.65 → 0.0.0-experimental.66

package/dist/vite/index.js

@@ -1733,7 +1733,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.65",
+  version: "0.0.0-experimental.66",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.65",
+  "version": "0.0.0-experimental.66",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/router/loader-resolution.ts

@@ -21,7 +21,7 @@ import type {
 } from "../types";
 import type { LoaderRevalidationResult, ActionContext } from "./types";
 import { isHandle, collectHandleData, type Handle } from "../handle.js";
-import type { HandleStore, HandleData } from "../server/handle-store.js";
+import { buildHandleSnapshot } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isInsideLoaderScope } from "../server/context.js";
@@ -284,10 +284,9 @@ function createLoaderExecutor<TEnv>(
             );
           }
           const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
-          const snapshot = buildHandleSnapshot(
-            reqCtx._handleStore,
-            segmentOrder,
-          );
+          const snapshot =
+            reqCtx._renderBarrierHandleSnapshot ??
+            buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
           return collectHandleData(item, snapshot, segmentOrder);
         }
 
@@ -324,6 +323,17 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
+        // Bidirectional deadlock check: if a handler already started
+        // awaiting this loader, calling rendered() would deadlock.
+        if (reqCtx._handlerLoaderDeps?.has(currentLoaderId)) {
+          throw new Error(
+            `Deadlock: loader "${currentLoaderId}" called ctx.rendered() but a handler ` +
+              `is already awaiting this loader via ctx.use(). The handler blocks ` +
+              `segment resolution, which blocks the barrier, which blocks this loader. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+
         // Register this loader as waiting for the barrier so that
         // setupLoaderAccess can detect deadlocks when a handler
         // tries to await the same loader via ctx.use().
@@ -354,25 +364,6 @@ function createLoaderExecutor<TEnv>(
   return useLoader;
 }
 
-/**
- * Build a HandleData snapshot from the HandleStore using segment ordering.
- * Reads data directly from the store for each segment in order.
- */
-function buildHandleSnapshot(
-  handleStore: HandleStore,
-  segmentOrder: string[],
-): HandleData {
-  const data: HandleData = {};
-  for (const segmentId of segmentOrder) {
-    const segData = handleStore.getDataForSegment(segmentId);
-    for (const handleName in segData) {
-      if (!data[handleName]) data[handleName] = {};
-      data[handleName][segmentId] = segData[handleName];
-    }
-  }
-  return data;
-}
-
 /**
  * Set up the use() method on handler context to access loaders and handles.
  *
@@ -386,15 +377,22 @@ export function setupLoaderAccess<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   loaderPromises: Map<string, Promise<any>>,
 ): void {
-  // Eagerly capture the HandleStore at setup time (before pipeline async ops).
-  // In workerd/Cloudflare, dynamic imports and fetch() in the match pipeline
-  // can disrupt AsyncLocalStorage, causing getRequestContext() to return
-  // undefined when handlers later call ctx.use(handle). Capturing early
-  // ensures the store reference survives ALS disruption.
-  const handleStoreRef = _getRequestContext()?._handleStore;
+  // Eagerly capture the request context and HandleStore at setup time
+  // (before pipeline async ops). In workerd/Cloudflare, dynamic imports and
+  // fetch() in the match pipeline can disrupt AsyncLocalStorage, causing
+  // getRequestContext() to return undefined when handlers later call
+  // ctx.use(handle). Capturing early ensures references survive ALS disruption.
+  const reqCtxRef = _getRequestContext();
+  const handleStoreRef = reqCtxRef?._handleStore;
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
+  // Track whether we're inside a handle push callback. Loaders started
+  // from push callbacks (e.g. push(async () => ctx.use(Loader))) do NOT
+  // block segment resolution, so they must not be registered as handler
+  // dependencies for deadlock detection.
+  let insideHandlePush = false;
+
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;
@@ -414,28 +412,53 @@ export function setupLoaderAccess<TEnv>(
       ) => {
         if (!store) return;
 
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
+        if (typeof dataOrFn === "function") {
+          // Mark scope so ctx.use(loader) calls inside the callback
+          // are not registered as handler-to-loader deps.
+          insideHandlePush = true;
+          try {
+            const result = (dataOrFn as () => Promise<unknown>)();
+            store.push(handle.$$id, segmentId, result);
+          } finally {
+            insideHandlePush = false;
+          }
+          return;
+        }
 
-        store.push(handle.$$id, segmentId, valueOrPromise);
+        store.push(handle.$$id, segmentId, dataOrFn);
       };
     }
 
-    // Deadlock guard: if a HANDLER awaits a loader that called rendered(),
-    // the handler blocks segment resolution which blocks the barrier.
-    // Skip this check when inside a DSL loader scope (resolveLoaderData
-    // also calls ctx.use() but that's DSL-to-DSL, not handler-to-loader).
+    // Deadlock guard and handler-to-loader dependency tracking.
+    // Skip when inside a DSL loader scope (resolveLoaderData also calls
+    // ctx.use() but that's DSL-to-DSL, not handler-to-loader) or when
+    // inside a handle push callback (push callbacks don't block segment
+    // resolution so they can't cause rendered() deadlocks).
     const loader = item as LoaderDefinition<any, any>;
-    if (loaderPromises.has(loader.$$id) && !isInsideLoaderScope()) {
-      const reqCtx = _getRequestContext();
-      if (reqCtx?._renderBarrierWaiters?.has(loader.$$id)) {
-        throw new Error(
-          `Deadlock: handler is awaiting loader "${loader.$$id}" which called ctx.rendered(). ` +
-            `The loader is waiting for segment resolution, but the handler blocks resolution. ` +
-            `Move the data dependency to a loader-to-loader pattern instead.`,
-        );
+    if (!isInsideLoaderScope() && !insideHandlePush) {
+      const reqCtx = reqCtxRef ?? _getRequestContext();
+      if (reqCtx) {
+        // Direction 1: handler awaits loader that already called rendered()
+        if (
+          loaderPromises.has(loader.$$id) &&
+          reqCtx._renderBarrierWaiters?.has(loader.$$id)
+        ) {
+          throw new Error(
+            `Deadlock: handler is awaiting loader "${loader.$$id}" which called ctx.rendered(). ` +
+              `The loader is waiting for segment resolution, but the handler blocks resolution. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+        // Direction 2: track dep so rendered() can detect the deadlock
+        // if the loader calls it later. Skip when the barrier has already
+        // resolved — no deadlock is possible (rendered() resolves immediately).
+        // _renderBarrierSegmentOrder is undefined before resolution, string[]
+        // after. This also prevents false positives from handle push callbacks
+        // that resume after their first await (post-barrier-resolution).
+        if (reqCtx._renderBarrierSegmentOrder === undefined) {
+          if (!reqCtx._handlerLoaderDeps) reqCtx._handlerLoaderDeps = new Set();
+          reqCtx._handlerLoaderDeps.add(loader.$$id);
+        }
       }
     }
 

package/src/router/match-middleware/cache-lookup.ts

@@ -194,11 +194,13 @@ async function* yieldFromStore<TEnv>(
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
-  // Set streaming flag and resolve render barrier.
+  // Set streaming flag (once) and resolve render barrier.
   const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
   const barrierReqCtx = reqCtx ?? _getRequestContext();
   if (barrierReqCtx) {
-    barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    if (barrierReqCtx._treeHasStreaming === undefined) {
+      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
     barrierReqCtx._resolveRenderBarrier(segments);
   }
 
@@ -623,10 +625,12 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
-    // Set streaming flag and resolve render barrier.
+    // Set streaming flag (once) and resolve render barrier.
     const barrierReqCtx = _getRequestContext();
     if (barrierReqCtx) {
-      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+      if (barrierReqCtx._treeHasStreaming === undefined) {
+        barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+      }
       barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
     }
 

package/src/router/match-middleware/segment-resolution.ts

@@ -168,7 +168,7 @@ export function withSegmentResolution<TEnv>(
     }
 
     const reqCtx = _getRequestContext();
-    if (reqCtx) {
+    if (reqCtx && reqCtx._treeHasStreaming === undefined) {
       reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
     }
 

package/src/rsc/handler.ts

@@ -1090,7 +1090,11 @@ export function createRSCHandler<
             },
           };
 
-          const rscStream = renderToReadableStream(payload);
+          const rscStream = renderToReadableStream(payload, {
+            onError: (error: unknown) => {
+              callOnError(error, "rendering", { request, url, env });
+            },
+          });
 
           const isRscRequest =
             isPartial ||

package/src/rsc/loader-fetch.ts

@@ -168,8 +168,19 @@ export async function handleLoaderFetch<TEnv>(
             loaderResult: unknown;
           }
           const loaderPayload: LoaderPayload = { loaderResult: result };
-          const rscStream =
-            ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
+          const rscStream = ctx.renderToReadableStream<LoaderPayload>(
+            loaderPayload,
+            {
+              onError: (error: unknown) => {
+                ctx.callOnError(error, "rendering", {
+                  request,
+                  url,
+                  env,
+                  loaderName: loaderId,
+                });
+              },
+            },
+          );
 
           return createResponseWithMergedHeaders(rscStream, {
             headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -199,7 +210,16 @@ export async function handleLoaderFetch<TEnv>(
         name: err.name,
       },
     };
-    const rscStream = ctx.renderToReadableStream(errorPayload);
+    const rscStream = ctx.renderToReadableStream(errorPayload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", {
+          request,
+          url,
+          env,
+          loaderName: loaderId,
+        });
+      },
+    });
 
     return createResponseWithMergedHeaders(rscStream, {
       status: 500,

package/src/rsc/progressive-enhancement.ts

@@ -259,7 +259,11 @@ export async function handleProgressiveEnhancement<TEnv>(
       formState: actionResult,
     };
 
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
     // metricsStore=undefined is safe: the handler already stashed the early
     // SSR setup promise on request variables, so getSSRSetup returns it
     // without falling back to a fresh startSSRSetup.
@@ -360,7 +364,11 @@ async function renderPeErrorBoundary<TEnv>(
     },
   };
 
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
   // metricsStore=undefined is safe: the handler already stashed the early
   // SSR setup promise on request variables, so getSSRSetup returns it
   // without falling back to a fresh startSSRSetup.

package/src/rsc/rsc-rendering.ts

@@ -173,7 +173,11 @@ export async function handleRscRendering<TEnv>(
 
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+  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(

package/src/rsc/server-action.ts

@@ -226,6 +226,9 @@ export async function executeServerAction<TEnv>(
 
       const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
         temporaryReferences,
+        onError: (error: unknown) => {
+          ctx.callOnError(error, "rendering", { request, url, env });
+        },
       });
 
       return createResponseWithMergedHeaders(rscStream, {
@@ -332,6 +335,9 @@ export async function revalidateAfterAction<TEnv>(
   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.

package/src/rsc/types.ts

@@ -70,6 +70,7 @@ export interface RSCDependencies {
     payload: T,
     options?: {
       temporaryReferences?: unknown;
+      onError?: (error: unknown) => string | void;
     },
   ) => ReadableStream<Uint8Array>;
 

package/src/server/handle-store.ts

@@ -13,6 +13,25 @@
  */
 export type HandleData = Record<string, Record<string, unknown[]>>;
 
+/**
+ * Build a HandleData snapshot from a HandleStore using segment ordering.
+ * Reads data directly from the store for each segment in order.
+ */
+export function buildHandleSnapshot(
+  handleStore: HandleStore,
+  segmentOrder: string[],
+): HandleData {
+  const data: HandleData = {};
+  for (const segmentId of segmentOrder) {
+    const segData = handleStore.getDataForSegment(segmentId);
+    for (const handleName in segData) {
+      if (!data[handleName]) data[handleName] = {};
+      data[handleName][segmentId] = segData[handleName];
+    }
+  }
+  return data;
+}
+
 function createLateHandlePushError(
   handleName: string,
   segmentId: string,

package/src/server/request-context.ts

@@ -26,7 +26,12 @@ import {
   contextSet,
   isNonCacheable,
 } from "../context-var.js";
-import { createHandleStore, type HandleStore } from "./handle-store.js";
+import {
+  createHandleStore,
+  buildHandleSnapshot,
+  type HandleStore,
+  type HandleData,
+} from "./handle-store.js";
 import { isHandle } from "../handle.js";
 import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
@@ -306,6 +311,19 @@ export interface RequestContext<
    */
   _renderBarrierWaiters?: Set<string>;
 
+  /**
+   * @internal Loader IDs that handlers have started awaiting via ctx.use().
+   * Used for bidirectional deadlock detection: if a loader later calls
+   * rendered() and a handler already awaits it, we can detect the deadlock.
+   */
+  _handlerLoaderDeps?: Set<string>;
+
+  /**
+   * @internal Cached HandleData snapshot built at barrier resolution time.
+   * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
+   */
+  _renderBarrierHandleSnapshot?: HandleData;
+
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
@@ -362,6 +380,8 @@ export type PublicRequestContext<
   | "_renderBarrierSegmentOrder"
   | "_treeHasStreaming"
   | "_renderBarrierWaiters"
+  | "_handlerLoaderDeps"
+  | "_renderBarrierHandleSnapshot"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
@@ -808,10 +828,18 @@ export function createRequestContext<TEnv>(
   ) => {
     if (barrierResolved) return;
     barrierResolved = true;
-    ctx._renderBarrierSegmentOrder = segments
+    const segOrder = segments
       .filter((s) => s.type !== "loader")
       .map((s) => s.id);
+    ctx._renderBarrierSegmentOrder = segOrder;
+    // Build and cache handle snapshot so loader ctx.use(handle) calls
+    // don't rebuild it on every invocation.
+    ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
+      handleStore,
+      segOrder,
+    );
     ctx._renderBarrierWaiters = undefined;
+    ctx._handlerLoaderDeps = undefined;
     if (resolveBarrier) resolveBarrier();
   };
   Object.defineProperty(ctx, "_renderBarrier", {