fix(cache): inherit route revalidate for tagged fetches (#2985)

* fix(cache): inherit route revalidate for tagged fetches

* fix(cache): inherit the live fetch revalidate interval

Author: james-elicx

packages/vinext/src/entries/app-rsc-entry.ts

@@ -500,6 +500,18 @@ function __resolveRouteDynamicConfig(route) {
   }).dynamicConfig ?? null;
 }
 
+function __resolveRouteRevalidateSeconds(route) {
+  return __resolveAppPageSegmentConfig({
+    layouts: route.layouts,
+    page: route.page,
+    parallelSegments: Object.values(route.slots ?? {}).flatMap((slot) => [
+      slot.layout,
+      ...(slot.configLayouts ?? []),
+      slot.page ?? slot.default,
+    ]),
+  }).revalidateSeconds;
+}
+
 function __resolveRouteRuntime(route) {
   return __resolveAppPageSegmentConfig({
     layouts: route.layouts,
@@ -964,6 +976,9 @@ export default createAppRscHandler({
       resolveRouteFetchCacheMode(targetRoute) {
         return __resolveRouteFetchCacheMode(targetRoute);
       },
+      resolveRouteRevalidateSeconds(targetRoute) {
+        return __resolveRouteRevalidateSeconds(targetRoute);
+      },
       resolveRouteDynamicConfig(targetRoute) {
         return __resolveRouteDynamicConfig(targetRoute);
       },
@@ -1197,6 +1212,9 @@ export default createAppRscHandler({
       resolveRouteFetchCacheMode(targetRoute) {
         return __resolveRouteFetchCacheMode(targetRoute);
       },
+      resolveRouteRevalidateSeconds(targetRoute) {
+        return __resolveRouteRevalidateSeconds(targetRoute);
+      },
       resolveRouteDynamicConfig(targetRoute) {
         return __resolveRouteDynamicConfig(targetRoute);
       },

packages/vinext/src/server/app-page-dispatch.ts

@@ -30,6 +30,7 @@ import {
   peekDynamicFetchObservations,
   runWithFetchDedupe,
   setCurrentFetchCacheMode,
+  setCurrentFetchRevalidate,
   setCurrentForceDynamicFetchDefault,
   setCurrentFetchSoftTags,
   setRefreshStaleFetchesInForeground,
@@ -396,6 +397,7 @@ export type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   revalidateSeconds: number | null;
   renderedPathAndSearch?: string | null;
   resolveRouteFetchCacheMode?: (route: TRoute) => FetchCacheMode | null;
+  resolveRouteRevalidateSeconds?: (route: TRoute) => number | null;
   resolveRouteDynamicConfig?: (route: TRoute) => string | null | undefined;
   rootForbiddenModule?: AppPageModule | null;
   rootNotFoundModule?: AppPageModule | null;
@@ -541,6 +543,7 @@ async function runAppPageRevalidationContext<
     cleanPathname: string;
     displayPathname?: string;
     currentFetchCacheMode?: FetchCacheMode | null;
+    currentFetchRevalidate?: number | null;
     draftModeSecret: string;
     dynamicConfig?: string;
     params: AppPageParams;
@@ -561,6 +564,7 @@ async function runAppPageRevalidationContext<
   const requestContext = createRequestContext({
     headersContext,
     currentFetchCacheMode: options.currentFetchCacheMode ?? null,
+    currentFetchRevalidate: options.currentFetchRevalidate ?? null,
     currentForceDynamicFetchDefault: options.dynamicConfig === "force-dynamic",
     executionContext: getRequestExecutionContext(),
     unstableCacheRevalidation: "foreground",
@@ -659,6 +663,7 @@ async function dispatchAppPageInner<TRoute extends AppPageDispatchRoute>(
 
   setCurrentFetchSoftTags(buildAppPageTags(options.cleanPathname, [], route.routeSegments));
   setCurrentFetchCacheMode(options.fetchCache ?? null);
+  setCurrentFetchRevalidate(currentRevalidateSeconds);
   setCurrentForceDynamicFetchDefault(isForceDynamic);
 
   if (options.hasPageModule && !options.hasPageDefaultExport) {
@@ -781,6 +786,9 @@ async function dispatchAppPageInner<TRoute extends AppPageDispatchRoute>(
             currentFetchCacheMode:
               options.resolveRouteFetchCacheMode?.(revalidationTarget.route) ??
               (revalidationTarget.route === route ? (options.fetchCache ?? null) : null),
+            currentFetchRevalidate:
+              options.resolveRouteRevalidateSeconds?.(revalidationTarget.route) ??
+              (revalidationTarget.route === route ? currentRevalidateSeconds : null),
             draftModeSecret: options.draftModeSecret,
             dynamicConfig: revalidationDynamicConfig,
             params: revalidationTarget.navigationParams,
@@ -938,6 +946,7 @@ async function dispatchAppPageInner<TRoute extends AppPageDispatchRoute>(
         setHeadersContext(requestHeadersContext);
       }
       setCurrentFetchCacheMode(options.resolveRouteFetchCacheMode?.(interceptRoute) ?? null);
+      setCurrentFetchRevalidate(options.resolveRouteRevalidateSeconds?.(interceptRoute) ?? null);
       setCurrentForceDynamicFetchDefault(sourceDynamicConfig === "force-dynamic");
       return options.buildPageElement(
         interceptRoute,

packages/vinext/src/server/app-route-handler-dispatch.ts

@@ -3,6 +3,7 @@ import {
   getCollectedFetchTags,
   ensureFetchPatch,
   setCurrentFetchCacheMode,
+  setCurrentFetchRevalidate,
   setCurrentFetchSoftTags,
   setCurrentForceDynamicFetchDefault,
   type FetchCacheMode,
@@ -117,6 +118,7 @@ async function runInRouteHandlerRevalidationContext(
     draftModeSecret: string;
     dynamicConfig?: string;
     fetchCacheMode: FetchCacheMode | null;
+    revalidateSeconds: number | null;
     routePattern: string;
     routeSegments: string[];
   },
@@ -143,6 +145,7 @@ async function runInRouteHandlerRevalidationContext(
     // The revalidation render runs in a fresh request context, so the fetch
     // defaults applied by `dispatchAppRouteHandler` must be re-applied here.
     setCurrentFetchCacheMode(options.fetchCacheMode);
+    setCurrentFetchRevalidate(options.revalidateSeconds);
     setCurrentForceDynamicFetchDefault(options.dynamicConfig === "force-dynamic");
     try {
       await renderFn();
@@ -232,6 +235,7 @@ export async function dispatchAppRouteHandler(
   // where handlers ignored their `fetchCache`/`force-dynamic` segment config.
   const fetchCacheMode = resolveAppRouteHandlerFetchCacheMode(handler);
   setCurrentFetchCacheMode(fetchCacheMode);
+  setCurrentFetchRevalidate(revalidateSeconds);
   setCurrentForceDynamicFetchDefault(handler.dynamic === "force-dynamic");
 
   if (
@@ -282,6 +286,7 @@ export async function dispatchAppRouteHandler(
             draftModeSecret: options.draftModeSecret,
             dynamicConfig: handler.dynamic,
             fetchCacheMode,
+            revalidateSeconds,
             routePattern: route.pattern,
             routeSegments: route.routeSegments,
           },

packages/vinext/src/server/app-server-action-execution.ts

@@ -11,6 +11,7 @@ import {
 import {
   type FetchCacheMode,
   setCurrentFetchCacheMode,
+  setCurrentFetchRevalidate,
   setCurrentFetchSoftTags,
   setCurrentForceDynamicFetchDefault,
 } from "vinext/shims/fetch-cache";
@@ -322,6 +323,7 @@ export type HandleServerActionRscRequestOptions<
   ) => BodyInit | null | Promise<BodyInit | null>;
   reportRequestError: AppServerActionErrorReporter;
   resolveRouteFetchCacheMode?: (route: TRoute) => FetchCacheMode | null;
+  resolveRouteRevalidateSeconds?: (route: TRoute) => number | null;
   resolveRouteDynamicConfig?: (route: TRoute) => string | null | undefined;
   resolveRouteRuntime?: (route: TRoute) => AppServerActionRouteRuntime;
   request: Request;
@@ -1669,6 +1671,9 @@ export async function handleServerActionRscRequest<
       setCurrentFetchCacheMode(
         options.resolveRouteFetchCacheMode?.(actionRerenderTarget.route) ?? null,
       );
+      setCurrentFetchRevalidate(
+        options.resolveRouteRevalidateSeconds?.(actionRerenderTarget.route) ?? null,
+      );
       setCurrentForceDynamicFetchDefault(actionRerenderDynamicConfig === "force-dynamic");
       setCurrentFetchSoftTags(
         buildServerActionPageTags(actionRerenderTarget.route, options.cleanPathname),

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

@@ -24,7 +24,7 @@ import { Buffer } from "node:buffer";
 import { getDataCacheHandler, type CachedFetchValue, type CacheHandler } from "./cache-handler.js";
 import { encodeCacheTags } from "../utils/encode-cache-tag.js";
 import { getOrCreateAls } from "./internal/als-registry.js";
-import { markDynamicUsage } from "./headers.js";
+import { getHeadersContext, markDynamicUsage } from "./headers.js";
 import { _hasPendingRevalidatedTag, _setRequestScopedCacheLife } from "./cache-request-state.js";
 import { getRequestExecutionContext } from "./request-context.js";
 import {
@@ -555,6 +555,7 @@ export type FetchCacheState = {
   currentRequestTags: string[];
   currentFetchSoftTags: string[];
   currentFetchCacheMode: FetchCacheMode | null;
+  currentFetchRevalidate: number | null;
   currentForceDynamicFetchDefault: boolean;
   dynamicFetchUrls: Set<string>;
   refreshStaleFetchesInForeground: boolean;
@@ -592,6 +593,7 @@ const _fallbackState = (_g[_FALLBACK_KEY] ??= {
   currentRequestTags: [],
   currentFetchSoftTags: [],
   currentFetchCacheMode: null,
+  currentFetchRevalidate: null,
   currentForceDynamicFetchDefault: false,
   dynamicFetchUrls: new Set<string>(),
   refreshStaleFetchesInForeground: false,
@@ -615,6 +617,7 @@ function _resetFallbackState(isFetchDedupeActive: boolean): void {
   _fallbackState.currentRequestTags = [];
   _fallbackState.currentFetchSoftTags = [];
   _fallbackState.currentFetchCacheMode = null;
+  _fallbackState.currentFetchRevalidate = null;
   _fallbackState.currentForceDynamicFetchDefault = false;
   _fallbackState.dynamicFetchUrls = new Set<string>();
   _fallbackState.refreshStaleFetchesInForeground = false;
@@ -632,6 +635,13 @@ function recordDynamicFetchObservation(input: string | URL | Request): void {
 
 function markUncachedFetchForPageOutput(input: string | URL | Request): void {
   recordDynamicFetchObservation(input);
+  // Next.js lowers the active prerender store to zero when an uncached fetch
+  // makes the render dynamic. `force-static` is the exception: dynamic usage
+  // is suppressed there, so later metadata-only fetches keep inheriting the
+  // configured route interval.
+  if (getHeadersContext()?.forceStatic !== true) {
+    _getState().currentFetchRevalidate = 0;
+  }
   markDynamicUsage();
 }
 
@@ -645,6 +655,13 @@ function recordFiniteFetchRevalidate(revalidateSeconds: number): void {
   }
 }
 
+function lowerCurrentFetchRevalidate(revalidateSeconds: number): void {
+  const state = _getState();
+  if (state.currentFetchRevalidate === null || revalidateSeconds < state.currentFetchRevalidate) {
+    state.currentFetchRevalidate = revalidateSeconds;
+  }
+}
+
 function shouldRefreshStaleFetchInForeground(): boolean {
   return _getState().refreshStaleFetchesInForeground;
 }
@@ -797,6 +814,10 @@ export function setCurrentFetchCacheMode(mode: FetchCacheMode | null): void {
   _getState().currentFetchCacheMode = mode;
 }
 
+export function setCurrentFetchRevalidate(revalidate: number | null): void {
+  _getState().currentFetchRevalidate = revalidate;
+}
+
 export function setCurrentForceDynamicFetchDefault(enabled: boolean): void {
   _getState().currentForceDynamicFetchDefault = enabled;
 }
@@ -1178,11 +1199,20 @@ function createPatchedFetch(): typeof globalThis.fetch {
     } else if (typeof nextOpts?.revalidate === "number" && nextOpts.revalidate > 0) {
       revalidateSeconds = nextOpts.revalidate;
     } else {
-      // Has `next` options but no explicit revalidate — Next.js defaults to
-      // caching when `next` is present (force-cache behavior).
-      // If only tags are specified, cache indefinitely.
+      // During prerender, a fetch without an explicit cache lifetime inherits
+      // the active route's revalidate value in Next.js. Tags make this fetch
+      // cacheable, but do not independently make it cache indefinitely.
       if (nextOpts?.tags && nextOpts.tags.length > 0) {
-        revalidateSeconds = ONE_YEAR_SECONDS;
+        const routeRevalidate = _getState().currentFetchRevalidate;
+        if (routeRevalidate === 0) {
+          const cleanInit = stripNextFromInit(init, cacheDirective);
+          markUncachedFetchForPageOutput(input);
+          return dedupeFetch(input, cleanInit);
+        }
+        revalidateSeconds =
+          routeRevalidate === null || routeRevalidate === Infinity
+            ? ONE_YEAR_SECONDS
+            : routeRevalidate;
       } else {
         // next: {} with no revalidate or tags — pass through
         const cleanInit = stripNextFromInit(init, cacheDirective);
@@ -1199,6 +1229,12 @@ function createPatchedFetch(): typeof globalThis.fetch {
     // recording both cacheable and dynamic is conservative — a false "unsafe"
     // result costs performance, not correctness.
     recordCacheableFetchObservation(input);
+    if (typeof nextOpts?.revalidate === "number" && nextOpts.revalidate > 0) {
+      // Upstream mutates the active prerender store when an explicit fetch
+      // lifetime is shorter. Later metadata-only fetches inherit that live
+      // minimum rather than the route's original segment-config seed.
+      lowerCurrentFetchRevalidate(nextOpts.revalidate);
+    }
     recordFiniteFetchRevalidate(revalidateSeconds);
     const reqTags = _getState().currentRequestTags;
     const tags = encodeCacheTags(nextOpts?.tags ?? []);
@@ -1440,6 +1476,7 @@ export async function runWithFetchCache<T>(fn: () => Promise<T>): Promise<T> {
       currentRequestTags: [],
       currentFetchSoftTags: [],
       currentFetchCacheMode: null,
+      currentFetchRevalidate: null,
       currentForceDynamicFetchDefault: false,
       dynamicFetchUrls: new Set<string>(),
       refreshStaleFetchesInForeground: false,

packages/vinext/src/shims/unified-request-context.ts

@@ -119,6 +119,7 @@ export function createRequestContext(opts?: Partial<UnifiedRequestContext>): Uni
     currentRequestTags: [],
     currentFetchSoftTags: [],
     currentFetchCacheMode: null,
+    currentFetchRevalidate: null,
     currentForceDynamicFetchDefault: false,
     dynamicFetchUrls: new Set<string>(),
     refreshStaleFetchesInForeground: false,

tests/app-page-dispatch.test.ts

@@ -318,6 +318,7 @@ type CreateDispatchOptionsOverrides = {
   request?: Request;
   revalidateSeconds?: number | null;
   resolveRouteFetchCacheMode?: DispatchOptions["resolveRouteFetchCacheMode"];
+  resolveRouteRevalidateSeconds?: DispatchOptions["resolveRouteRevalidateSeconds"];
   resolveRouteDynamicConfig?: DispatchOptions["resolveRouteDynamicConfig"];
   route?: TestRoute;
   scheduleBackgroundRegeneration?: DispatchOptions["scheduleBackgroundRegeneration"];
@@ -414,6 +415,7 @@ function createDispatchOptions(overrides: CreateDispatchOptionsOverrides = {}) {
     request: overrides.request ?? new Request("https://example.test/posts/hello"),
     revalidateSeconds: overrides.revalidateSeconds ?? null,
     resolveRouteFetchCacheMode: overrides.resolveRouteFetchCacheMode,
+    resolveRouteRevalidateSeconds: overrides.resolveRouteRevalidateSeconds,
     resolveRouteDynamicConfig: overrides.resolveRouteDynamicConfig,
     route,
     runWithSuppressedHookWarning<T>(probe: () => Promise<T>) {
@@ -2393,6 +2395,9 @@ describe("app page dispatch", () => {
     const resolveRouteFetchCacheMode = vi.fn((route: TestRoute) =>
       route === sourceRoute ? "force-cache" : null,
     );
+    const resolveRouteRevalidateSeconds = vi.fn((route: TestRoute) =>
+      route === sourceRoute ? 30 : null,
+    );
     const { options } = createDispatchOptions({
       buildPageElement,
       cleanPathname: "/photos/123",
@@ -2437,6 +2442,7 @@ describe("app page dispatch", () => {
       mountedSlotsHeader: "slot:modal:/feed",
       revalidateSeconds: 60,
       resolveRouteFetchCacheMode,
+      resolveRouteRevalidateSeconds,
       route: currentRoute,
       scheduleBackgroundRegeneration,
       searchParams: new URLSearchParams("tab=popular"),
@@ -2450,6 +2456,7 @@ describe("app page dispatch", () => {
 
     const [routeArg, paramsArg, optsArg, searchParamsArg] = buildPageElement.mock.calls[0];
     expect(resolveRouteFetchCacheMode).toHaveBeenCalledWith(sourceRoute);
+    expect(resolveRouteRevalidateSeconds).toHaveBeenCalledWith(sourceRoute);
     expect(routeArg).toBe(sourceRoute);
     expect(paramsArg).toEqual({});
     expect(searchParamsArg.toString()).toBe("tab=popular");

tests/app-route-handler-dispatch.test.ts

@@ -403,6 +403,7 @@ describe("app route handler dispatch", () => {
   it("applies the force-dynamic fetch default before invoking the route handler", async () => {
     const fetchCacheShims = await import("../packages/vinext/src/shims/fetch-cache.js");
     const modeSpy = vi.spyOn(fetchCacheShims, "setCurrentFetchCacheMode");
+    const revalidateSpy = vi.spyOn(fetchCacheShims, "setCurrentFetchRevalidate");
     const forceDynamicSpy = vi.spyOn(fetchCacheShims, "setCurrentForceDynamicFetchDefault");
 
     let forceDynamicDefaultAtHandlerTime: boolean | undefined;
@@ -449,14 +450,17 @@ describe("app route handler dispatch", () => {
     expect(response.status).toBe(200);
     expect(forceDynamicDefaultAtHandlerTime).toBe(true);
     expect(fetchCacheModeAtHandlerTime).toBeNull();
+    expect(revalidateSpy).toHaveBeenCalledWith(null);
 
     modeSpy.mockRestore();
+    revalidateSpy.mockRestore();
     forceDynamicSpy.mockRestore();
   });
 
   it("applies the handler's explicit fetchCache export without the force-dynamic default", async () => {
     const fetchCacheShims = await import("../packages/vinext/src/shims/fetch-cache.js");
     const modeSpy = vi.spyOn(fetchCacheShims, "setCurrentFetchCacheMode");
+    const revalidateSpy = vi.spyOn(fetchCacheShims, "setCurrentFetchRevalidate");
     const forceDynamicSpy = vi.spyOn(fetchCacheShims, "setCurrentForceDynamicFetchDefault");
 
     let forceDynamicDefaultAtHandlerTime: boolean | undefined;
@@ -501,14 +505,17 @@ describe("app route handler dispatch", () => {
     expect(response.status).toBe(200);
     expect(forceDynamicDefaultAtHandlerTime).toBe(false);
     expect(fetchCacheModeAtHandlerTime).toBe("force-cache");
+    expect(revalidateSpy).toHaveBeenCalledWith(null);
 
     modeSpy.mockRestore();
+    revalidateSpy.mockRestore();
     forceDynamicSpy.mockRestore();
   });
 
   it("re-applies the handler's fetch cache mode inside the background regeneration context", async () => {
     const fetchCacheShims = await import("../packages/vinext/src/shims/fetch-cache.js");
     const modeSpy = vi.spyOn(fetchCacheShims, "setCurrentFetchCacheMode");
+    const revalidateSpy = vi.spyOn(fetchCacheShims, "setCurrentFetchRevalidate");
     const forceDynamicSpy = vi.spyOn(fetchCacheShims, "setCurrentForceDynamicFetchDefault");
 
     let scheduledRender: (() => Promise<void>) | undefined;
@@ -566,9 +573,11 @@ describe("app route handler dispatch", () => {
 
     expect(forceDynamicDefaultAtRegenTime).toBe(false);
     expect(fetchCacheModeAtRegenTime).toBe("force-cache");
+    expect(revalidateSpy).toHaveBeenLastCalledWith(60);
     expect(afterRan).toBe(true);
 
     modeSpy.mockRestore();
+    revalidateSpy.mockRestore();
     forceDynamicSpy.mockRestore();
   });