feat(dev): detect 'use cache' module-scope deadlocks early in dev (#1126)

packages/vinext/src/index.ts

@@ -16,6 +16,7 @@ import { handleApiRoute } from "./server/api-handler.js";
 import { installSocketErrorBackstop } from "./server/socket-error-backstop.js";
 import { shouldInvalidateAppRouteFile } from "./server/dev-route-files.js";
 import { createDirectRunner } from "./server/dev-module-runner.js";
+import { initUseCacheProbePool, tearDownUseCacheProbePool } from "./server/use-cache-probe-pool.js";
 import { generateRscEntry } from "./entries/app-rsc-entry.js";
 import { generateSsrEntry } from "./entries/app-ssr-entry.js";
 import { generateBrowserEntry } from "./entries/app-browser-entry.js";
@@ -2041,6 +2042,9 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           invalidateAppRouteCache();
           invalidateRscEntryModule();
           invalidateRootParamsModule();
+          // Tear down the use-cache probe pool so the next probe starts with
+          // fresh code after HMR invalidation.
+          tearDownUseCacheProbePool();
         }
 
         // Node throws on unhandled 'error' events on sockets. When a browser
@@ -2134,6 +2138,14 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           //      it is flushed to the client.
           //   2. Logs the full request after res finishes, using those timings.
           if (hasAppDir) {
+            // Initialize the "use cache" deadlock probe pool for the App
+            // Router dev server. We bind to the RSC environment because
+            // "use cache" functions run inside the RSC module graph.
+            const rscEnv = server.environments["rsc"];
+            if (rscEnv) {
+              initUseCacheProbePool(rscEnv);
+            }
+
             server.middlewares.use((req, res, next) => {
               const url = req.url ?? "/";
               // Skip Vite internals, HMR, and static assets.

packages/vinext/src/server/dev-module-runner.ts

@@ -65,7 +65,7 @@ import type { DevEnvironment } from "vite";
  * environment types — including Cloudflare's custom environments that don't
  * support the hot-channel-based transport.
  */
-type DevEnvironmentLike = {
+export type DevEnvironmentLike = {
   fetchModule: (
     id: string,
     importer?: string,
@@ -129,3 +129,51 @@ export function createDirectRunner(environment: DevEnvironmentLike | DevEnvironm
     new ESModulesEvaluator(),
   );
 }
+
+/**
+ * Create a fresh ModuleRunner with its own isolated module graph.
+ *
+ * Used by the "use cache" deadlock probe to re-import a cache function
+ * with zero shared module-scope state from the main request pipeline.
+ * Each probe gets a brand-new `EvaluatedModules` instance so top-level
+ * `Map`s, `Promise`s, etc. are recreated from scratch.
+ *
+ * The transport delegates to the same `environment.fetchModule()`, so
+ * Vite transforms and HMR still work, but the *evaluated* module cache
+ * is completely separate.
+ */
+export function createProbeRunner(environment: DevEnvironmentLike | DevEnvironment): ModuleRunner {
+  return new ModuleRunner(
+    {
+      transport: {
+        // oxlint-disable-next-line @typescript-eslint/no-explicit-any
+        invoke: async (payload: any) => {
+          const { name, data: args } = payload.data;
+          if (name === "fetchModule") {
+            const [id, importer, options] = args as [
+              string,
+              string | undefined,
+              { cached?: boolean; startOffset?: number } | undefined,
+            ];
+            return {
+              result: await environment.fetchModule(id, importer, options),
+            };
+          }
+          if (name === "getBuiltins") {
+            return { result: [] };
+          }
+          return {
+            error: {
+              name: "Error",
+              message: `[vinext] Unexpected ModuleRunner invoke: ${name}`,
+            },
+          };
+        },
+      },
+      createImportMeta: createNodeImportMeta,
+      sourcemapInterceptor: false,
+      hmr: false,
+    },
+    new ESModulesEvaluator(),
+  );
+}

packages/vinext/src/server/use-cache-probe-pool.ts

@@ -0,0 +1,188 @@
+/**
+ * use-cache-probe-pool.ts
+ *
+ * Manages isolated ModuleRunners for "use cache" deadlock probes.
+ *
+ * In dev mode, when a cache fill appears stuck, we re-run the same cache
+ * function in a fresh module graph. If it completes there but the main fill
+ * is still hung, the hang is attributable to module-scope shared state
+ * (e.g. a top-level Map used to dedupe fetches) from the outer render.
+ *
+ * Unlike Next.js (which uses jest-worker with real OS processes), vinext
+ * creates a fresh Vite ModuleRunner per probe. Each runner has its own
+ * EvaluatedModules instance, so top-level module state is recreated from
+ * scratch while still using the same Vite transform pipeline.
+ *
+ * The pool is torn down on HMR / file invalidation so the next probe
+ * starts with fresh transformed code.
+ */
+
+import type { DevEnvironment } from "vite";
+import { createProbeRunner, type DevEnvironmentLike } from "./dev-module-runner.js";
+import { ModuleRunner } from "vite/module-runner";
+import { setUseCacheProbe } from "vinext/shims/use-cache-probe-globals";
+import { UseCacheTimeoutError } from "vinext/shims/use-cache-errors";
+
+let _probeEnvironment: DevEnvironmentLike | DevEnvironment | null = null;
+
+/**
+ * Initialize the probe pool with the Vite dev environment.
+ *
+ * Called once during configureServer() when the App Router dev server starts.
+ */
+export function initUseCacheProbePool(environment: DevEnvironmentLike | DevEnvironment): void {
+  if (_probeEnvironment) {
+    // Already initialized — no-op. The environment is the same for the
+    // lifetime of the dev server.
+    return;
+  }
+  _probeEnvironment = environment;
+
+  setUseCacheProbe(async (msg) => {
+    // Create a fresh runner per probe so the module graph is completely
+    // isolated from previous probes. Reusing runners would leave stale
+    // top-level state in EvaluatedModules.
+    const runner = createProbeRunner(_probeEnvironment!);
+    const { id, kind, encodedArguments, request, timeoutMs } = msg;
+
+    // Internal timeout so the probe aborts before the outer render timeout.
+    const deadline = Date.now() + timeoutMs;
+
+    try {
+      // Import the cache-runtime shim in the isolated runner.
+      // The shim's registerCachedFunction will create fresh module-scope state.
+      const cacheRuntime = (await runner.import("vinext/shims/cache-runtime")) as Record<
+        string,
+        unknown
+      >;
+      const registerCachedFunction = cacheRuntime.registerCachedFunction as
+        | (<T extends (...args: unknown[]) => Promise<unknown>>(
+            fn: T,
+            id: string,
+            variant?: string,
+          ) => T)
+        | undefined;
+
+      if (!registerCachedFunction) {
+        return false;
+      }
+
+      // We need to locate the original cached function module in the isolated
+      // runner. The function id is "<modulePath>:<exportName>". We split it
+      // to find the module and the export.
+      const lastColon = id.lastIndexOf(":");
+      const modulePath = lastColon >= 0 ? id.slice(0, lastColon) : id;
+      const exportName = lastColon >= 0 ? id.slice(lastColon + 1) : "default";
+
+      // Import the module containing the original "use cache" function.
+      const mod = (await runner.import(modulePath)) as Record<string, unknown>;
+      const originalFn = mod[exportName];
+      if (typeof originalFn !== "function") {
+        return false;
+      }
+
+      // Wrap it with registerCachedFunction so the probe runs through the
+      // same cache-runtime path (fresh ALS, no shared state).
+      const variant = kind === "private" ? "private" : "";
+      const wrapped = registerCachedFunction(
+        originalFn as (...args: unknown[]) => Promise<unknown>,
+        id,
+        variant,
+      );
+
+      // Decode the arguments (simple JSON fallback; RSC encodeReply is
+      // not available in the probe because we lack the client environment).
+      // For deadlock detection, the exact argument values matter less than
+      // the fact that the function body executes with a fresh module scope.
+      let args: unknown[] = [];
+      if (typeof encodedArguments === "string") {
+        try {
+          args = JSON.parse(encodedArguments);
+          if (!Array.isArray(args)) args = [args];
+        } catch {
+          args = [];
+        }
+      }
+
+      // Run the function with a reconstructed request store so private caches
+      // that read cookies()/headers()/draftMode() see the same values.
+      // Race against the internal timeout.
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        return false;
+      }
+
+      await Promise.race([
+        runWithProbeRequestStore(runner, request, async () => wrapped(...args)),
+        new Promise<never>((_, reject) => {
+          const t = setTimeout(() => reject(new UseCacheTimeoutError()), remaining);
+          // Ensure timer is cleaned up on success via unref if available.
+          if (typeof (t as NodeJS.Timeout).unref === "function") {
+            (t as NodeJS.Timeout).unref();
+          }
+        }),
+      ]);
+
+      return true;
+    } catch {
+      // Probe failure is inconclusive — the function might genuinely hang
+      // even in isolation, or the module import failed. Fall back to the
+      // regular timeout.
+      return false;
+    } finally {
+      runner.close().catch(() => {});
+    }
+  });
+}
+
+/**
+ * Tear down the probe pool. Called on HMR / file invalidation so the next
+ * probe starts with fresh code.
+ */
+export function tearDownUseCacheProbePool(): void {
+  _probeEnvironment = null;
+  setUseCacheProbe(undefined);
+}
+
+/**
+ * Reconstruct a minimal request store in the probe runner so that
+ * cookies(), headers(), and draftMode() behave correctly.
+ */
+async function runWithProbeRequestStore<T>(
+  runner: ModuleRunner,
+  requestSnapshot: {
+    headers: [string, string][];
+    cookieHeader: string | undefined;
+    urlPathname: string;
+    urlSearch: string;
+    rootParams: Record<string, unknown>;
+    isDraftMode: boolean;
+    isHmrRefresh: boolean;
+  },
+  fn: () => Promise<T>,
+): Promise<T> {
+  // Import the ALS-backed request-context modules through the probe runner
+  // so they load inside the isolated module graph, not the main runner's.
+  const { createRequestContext, runWithRequestContext } = (await runner.import(
+    "vinext/shims/unified-request-context",
+  )) as typeof import("vinext/shims/unified-request-context");
+
+  const { headersContextFromRequest } = (await runner.import(
+    "vinext/shims/headers",
+  )) as typeof import("vinext/shims/headers");
+
+  // Build a Request from the snapshot so headersContextFromRequest works.
+  const url = new URL(requestSnapshot.urlPathname + requestSnapshot.urlSearch, "http://localhost");
+  const request = new Request(url, {
+    headers: new Headers(requestSnapshot.headers),
+  });
+
+  const headersContext = headersContextFromRequest(request);
+  const ctx = createRequestContext({
+    headersContext,
+    executionContext: null,
+    rootParams: requestSnapshot.rootParams as Record<string, string | string[]>,
+  });
+
+  return runWithRequestContext(ctx, fn);
+}

packages/vinext/src/shims/cache-runtime.ts

@@ -42,6 +42,8 @@ import {
   getRequestContext,
   runWithUnifiedStateMutation,
 } from "./unified-request-context.js";
+import { UseCacheTimeoutError, UseCacheDeadlockError } from "./use-cache-errors.js";
+import { getUseCacheProbe, type UseCacheProbeRequestSnapshot } from "./use-cache-probe-globals.js";
 
 // ---------------------------------------------------------------------------
 // Cache execution context — AsyncLocalStorage for cacheLife/cacheTag
@@ -399,7 +401,74 @@ export function registerCachedFunction<T extends (...args: any[]) => Promise<any
     // In dev mode, always execute fresh — skip shared cache lookup/storage.
     // This ensures HMR changes are reflected immediately.
     if (isDev) {
-      return executeWithContext(fn, args, cacheVariant);
+      const USE_CACHE_TIMEOUT_MS = 54_000;
+      const fillDeadlineAt = performance.now() + USE_CACHE_TIMEOUT_MS;
+
+      const timeoutError = new UseCacheTimeoutError();
+      const deadlockError = new UseCacheDeadlockError();
+
+      let probeTimer: ReturnType<typeof setTimeout> | undefined;
+      let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+      let probePromise: Promise<never> | null = null;
+      const probe = getUseCacheProbe();
+
+      if (probe) {
+        // Capture the current request store snapshot for the probe.
+        const requestCtx = getRequestContext();
+        const headers = requestCtx.headersContext?.headers;
+        const navCtx = requestCtx.serverContext;
+        const requestSnapshot: UseCacheProbeRequestSnapshot = {
+          headers: headers ? Array.from(headers.entries()) : [],
+          cookieHeader: headers?.get("cookie") ?? undefined,
+          urlPathname: navCtx?.pathname ?? "/",
+          urlSearch: navCtx?.searchParams?.toString() ?? "",
+          rootParams: requestCtx.rootParams ?? {},
+          isDraftMode: false,
+          isHmrRefresh: false,
+        };
+
+        probePromise = new Promise<never>((_, reject) => {
+          probeTimer = setTimeout(() => {
+            const probeInternalTimeoutMs = fillDeadlineAt - performance.now() - 1_000;
+            if (probeInternalTimeoutMs <= 0) return;
+
+            probe({
+              id,
+              kind: cacheVariant,
+              encodedArguments: JSON.stringify(args),
+              request: requestSnapshot,
+              timeoutMs: probeInternalTimeoutMs,
+            }).then(
+              (completed) => {
+                if (completed) reject(deadlockError);
+              },
+              () => {},
+            );
+          }, 10_000);
+        });
+        // Swallow rejection when execution wins the race.
+        probePromise.catch(() => {});
+      }
+
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutTimer = setTimeout(() => reject(timeoutError), USE_CACHE_TIMEOUT_MS);
+        if (typeof (timeoutTimer as NodeJS.Timeout).unref === "function") {
+          (timeoutTimer as NodeJS.Timeout).unref();
+        }
+      });
+      // Swallow rejection when execution wins the race.
+      timeoutPromise.catch(() => {});
+
+      const executionPromise = executeWithContext(fn, args, cacheVariant);
+
+      const promises: Promise<unknown>[] = [executionPromise];
+      if (probePromise) promises.push(probePromise);
+      promises.push(timeoutPromise);
+
+      return Promise.race(promises).finally(() => {
+        if (probeTimer !== undefined) clearTimeout(probeTimer);
+        if (timeoutTimer !== undefined) clearTimeout(timeoutTimer);
+      });
     }
 
     // Shared cache ("use cache" / "use cache: remote")