Fix tag cache stale logic and update tests

examples/e2e/app-router/e2e/revalidateTag.test.ts

@@ -105,7 +105,7 @@ test("Revalidate tag - stale data served first", async ({ page, request }) => {
 	const staleResponse = await responsePromise;
 	const staleHeaders = staleResponse.headers();
 	const staleCache = staleHeaders["x-nextjs-cache"] ?? staleHeaders["x-opennext-cache"];
-	expect(staleCache).toMatch(/^(STALE|HIT)$/);
+	expect(staleCache).toMatch(/^(STALE)$/);
 
 	const staleTime = await page.getByTestId("cached-time").textContent();
 	// Stale content must match the pre-revalidation value
@@ -129,6 +129,19 @@ test("Revalidate tag - stale data served first", async ({ page, request }) => {
 	// After background regen the cached value must have been updated
 	expect(freshTime).not.toBeNull();
 	expect(freshTime).not.toEqual(originalTime);
+
+	// Now we want to verfiy that the next entries stays fresh (HIT) after the first stale entry
+	responsePromise = page.waitForResponse(
+		(response) => response.url().includes("/revalidate-tag/stale") && response.status() === 200
+	);
+	await page.goto("/revalidate-tag/stale");
+	const finalResponse = await responsePromise;
+	const finalHeaders = finalResponse.headers();
+	const finalCache = finalHeaders["x-nextjs-cache"] ?? finalHeaders["x-opennext-cache"];
+	expect(finalCache).toEqual("HIT");
+
+	const finalTime = await page.getByTestId("cached-time").textContent();
+	expect(finalTime).toEqual(freshTime);
 });
 
 test("Revalidate path", async ({ page, request }) => {

packages/cloudflare/src/api/overrides/incremental-cache/regional-cache.ts

@@ -45,6 +45,10 @@ type Options = {
 	 * Note: When this is enabled, make sure that the cache gets purged
 	 *       either by enabling the auto cache purging feature or manually.
 	 *
+	 * This is currently not compatible with swr types of revalidateTag (i.e. on Next 16+, anything different than `revalidateTag("tag", { expire: 0 })`),
+	 * unless you also enable the `shouldLazilyUpdateOnCacheHit` option to make sure the cache gets updated in the background after a hit,
+	 * and ONLY use it for pages, not data cache entries.
+	 *
 	 * @default `true` if the auto cache purging is enabled, `false` otherwise.
 	 */
 	bypassTagCacheOnCacheHit?: boolean;

packages/cloudflare/src/api/overrides/tag-cache/d1-next-tag-cache.spec.ts

@@ -395,6 +395,17 @@ describe("D1NextModeTagCache", () => {
 			expect(result).toBe(false);
 		});
 
+		it("should return false when revalidatedAt <= lastModified even if stale > lastModified", async () => {
+			const now = 2000;
+			vi.spyOn(Date, "now").mockReturnValue(now);
+			// revalidatedAt=500 <= lastModified=1000, so the stale window is from a previous ISR cycle
+			mockRaw.mockResolvedValue([[`${FALLBACK_BUILD_ID}/tag1`, 500, 1500, null]]);
+
+			const result = await tagCache.isStale(["tag1"], 1000);
+
+			expect(result).toBe(false);
+		});
+
 		it("should return false when expire <= now (tag expired)", async () => {
 			const now = 2000;
 			vi.spyOn(Date, "now").mockReturnValue(now);

packages/cloudflare/src/api/overrides/tag-cache/d1-next-tag-cache.ts

@@ -105,8 +105,13 @@ export class D1NextModeTagCache implements NextModeTagCache {
 
 			const isStale = [...result.values()].some((v) => {
 				if (v == null) return false;
-				const { stale, expire } = v;
-				if (stale == null || stale <= (lastModified ?? now)) return false;
+				const { revalidatedAt, stale, expire } = v;
+				// A tag is stale when both its stale timestamp and its revalidatedAt are newer than the page.
+				// revalidatedAt > lastModified ensures the revalidation that set this stale window happened
+				// after the page was generated, preventing a stale signal from a previous ISR cycle.
+				const isInStaleWindow =
+					stale != null && revalidatedAt > (lastModified ?? now) && (lastModified ?? now) <= stale;
+				if (!isInStaleWindow) return false;
 				return expire == null || expire > now;
 			});
 

packages/cloudflare/src/api/overrides/tag-cache/do-sharded-tag-cache.spec.ts

@@ -349,6 +349,14 @@ describe("DOShardedTagCache", () => {
 			expect(await cache.isStale(["tag1"], 200)).toBe(false);
 		});
 
+		it("should return false when revalidatedAt <= lastModified even if stale > lastModified", async () => {
+			const cache = shardedDOTagCache();
+			cache.getFromRegionalCache = vi.fn().mockResolvedValueOnce([]);
+			// revalidatedAt=100 <= lastModified=200, so the stale window is from a previous ISR cycle
+			getTagDataMock.mockResolvedValueOnce({ tag1: { revalidatedAt: 100, stale: 300, expire: null } });
+			expect(await cache.isStale(["tag1"], 200)).toBe(false);
+		});
+
 		it("should return from regional cache if available", async () => {
 			vi.useFakeTimers();
 			vi.setSystemTime(500);

packages/cloudflare/src/api/overrides/tag-cache/do-sharded-tag-cache.ts

@@ -191,8 +191,13 @@ class ShardedDOTagCache implements NextModeTagCache {
 			const tagData = await this.#resolveTagData(tags);
 			const result = [...tagData.values()].some((data) => {
 				if (data == null) return false;
-				const { stale, expire } = data;
-				if (stale == null || stale <= (lastModified ?? now)) return false;
+				const { revalidatedAt, stale, expire } = data;
+				// A tag is stale when both its stale timestamp and its revalidatedAt are newer than the page.
+				// revalidatedAt > lastModified ensures the revalidation that set this stale window happened
+				// after the page was generated, preventing a stale signal from a previous ISR cycle.
+				const isInStaleWindow =
+					stale != null && revalidatedAt > (lastModified ?? now) && (lastModified ?? now) <= stale;
+				if (!isInStaleWindow) return false;
 				return expire == null || expire > now;
 			});
 			debugCache("ShardedDOTagCache", `isStale tags=${tags} at=${lastModified} -> ${result}`);

packages/cloudflare/src/api/overrides/tag-cache/kv-next-tag-cache.spec.ts

@@ -344,6 +344,19 @@ describe("KVNextModeTagCache", () => {
 			expect(result).toBe(false);
 		});
 
+		it("should return false when revalidatedAt <= lastModified even if stale > lastModified", async () => {
+			const now = 2000;
+			vi.spyOn(Date, "now").mockReturnValue(now);
+			// revalidatedAt=500 <= lastModified=1000, so the stale window is from a previous ISR cycle
+			mockGet.mockResolvedValue(
+				new Map([[`${FALLBACK_BUILD_ID}/tag1`, { revalidatedAt: 500, stale: 1500, expire: null }]])
+			);
+
+			const result = await tagCache.isStale(["tag1"], 1000);
+
+			expect(result).toBe(false);
+		});
+
 		it("should return false when expire <= now (tag expired)", async () => {
 			const now = 2000;
 			vi.spyOn(Date, "now").mockReturnValue(now);

packages/cloudflare/src/api/overrides/tag-cache/kv-next-tag-cache.ts

@@ -180,8 +180,13 @@ export class KVNextModeTagCache implements NextModeTagCache {
 			const isStale = [...result.values()].some((v) => {
 				if (v == null) return false;
 				const stale = getStale(v);
-				if (stale == null || stale <= (lastModified ?? now)) return false;
 				const expire = getExpire(v);
+				// A tag is stale when both its stale timestamp and its revalidatedAt are newer than the page.
+				// revalidatedAt > lastModified ensures the revalidation that set this stale window happened
+				// after the page was generated, preventing a stale signal from a previous ISR cycle.
+				const isInStaleWindow =
+					stale != null && getRevalidatedAt(v) > (lastModified ?? now) && (lastModified ?? now) <= stale;
+				if (!isInStaleWindow) return false;
 				return expire == null || expire > now;
 			});