Cache: route all caching through the cache override

.changeset/cache-consolidate-override.md

@@ -0,0 +1,32 @@
+---
+"@opennextjs/core": major
+"@opennextjs/cloudflare": minor
+---
+
+Route all caching through the `cache` override
+
+The incremental cache and the tag cache no longer run inside the server function. They run in the
+cache handler function, which the server, the middleware and the composable cache reach through the
+`cache` override. Tag revalidation - `hasBeenRevalidated`, `writeTags` and CDN invalidation - moves
+with them, so `get`, `set` and `revalidateTags` now handle tags transparently.
+
+`incrementalCache` and `tagCache` are removed from `default.override` and from the middleware
+override. Configurations that are not created by `defineCloudflareConfig` should move them to the
+top level `cacheHandler` option and set `default.override.cache`:
+
+```diff
+  default: {
+    override: {
+-     incrementalCache: "s3",
+-     tagCache: "dynamodb",
++     cache: "local",
+    },
+  },
++ cacheHandler: {
++   incrementalCache: "s3",
++   tagCache: "dynamodb",
++ },
+```
+
+`defineCloudflareConfig` is unchanged: it now wires the cache to the `OpenNextCache` entrypoint on
+its own.

examples/app-pages-router/open-next.config.ts

@@ -3,9 +3,8 @@ import type { OpenNextConfig, OverrideOptions } from "@opennextjs/core/types/ope
 const devOverride = {
 	wrapper: "express-dev",
 	converter: "node",
-	incrementalCache: "fs-dev",
+	cache: "local",
 	queue: "direct",
-	tagCache: "fs-dev-nextMode",
 } satisfies OverrideOptions;
 
 export default {
@@ -26,6 +25,14 @@ export default {
 		},
 		loader: "fs-dev",
 	},
+	cacheHandler: {
+		override: {
+			wrapper: "dummy",
+			converter: "dummy",
+		},
+		incrementalCache: "fs-dev",
+		tagCache: "fs-dev-nextMode",
+	},
 	// You can override the build command here so that you don't have to rebuild next every time you make a change
 	// buildCommand: "echo 'No build command'",
 } satisfies OpenNextConfig;

examples/app-router/open-next.config.ts

@@ -5,9 +5,8 @@ export default {
 		override: {
 			wrapper: "express-dev",
 			converter: "node",
-			incrementalCache: "fs-dev",
+			cache: "local",
 			queue: "direct",
-			tagCache: "fs-dev-nextMode",
 		},
 	},
 
@@ -19,6 +18,15 @@ export default {
 		loader: "fs-dev",
 	},
 
+	cacheHandler: {
+		override: {
+			wrapper: "dummy",
+			converter: "dummy",
+		},
+		incrementalCache: "fs-dev",
+		tagCache: "fs-dev-nextMode",
+	},
+
 	// You can override the build command here so that you don't have to rebuild next every time you make a change
 	//buildCommand: "echo 'No build command'",
 } satisfies OpenNextConfig;

examples/experimental/open-next.config.ts

@@ -5,9 +5,8 @@ export default {
 		override: {
 			wrapper: "express-dev",
 			converter: "node",
-			incrementalCache: "fs-dev",
 			queue: "direct",
-			tagCache: "fs-dev-nextMode",
+			cache: "local",
 		},
 	},
 
@@ -19,6 +18,15 @@ export default {
 		loader: "fs-dev",
 	},
 
+	cacheHandler: {
+		override: {
+			wrapper: "dummy",
+			converter: "dummy",
+		},
+		incrementalCache: "fs-dev",
+		tagCache: "fs-dev-nextMode",
+	},
+
 	// You can override the build command here so that you don't have to rebuild next every time you make a change
 	//buildCommand: "echo 'No build command'",
 } satisfies OpenNextConfig;

examples/pages-router/open-next.config.ts

@@ -3,9 +3,8 @@ export default {
 		override: {
 			wrapper: "express-dev",
 			converter: "node",
-			incrementalCache: "fs-dev",
 			queue: "direct",
-			tagCache: "dummy",
+			cache: "local",
 		},
 	},
 
@@ -17,6 +16,15 @@ export default {
 		loader: "fs-dev",
 	},
 
+	cacheHandler: {
+		override: {
+			wrapper: "dummy",
+			converter: "dummy",
+		},
+		incrementalCache: "fs-dev",
+		tagCache: "dummy",
+	},
+
 	// You can override the build command here so that you don't have to rebuild next every time you make a change
 	//buildCommand: "echo 'No build command'",
 };

packages/aws/src/adapter.ts

@@ -10,9 +10,14 @@ export default buildAdapter((_config, buildOpts: BuildOptions) => ({
 		server: {
 			wrapper: "@opennextjs/aws/overrides/wrappers/aws-lambda-streaming.js",
 			converter: "@opennextjs/aws/overrides/converters/aws-streaming.js",
+			cache: "@opennextjs/core/overrides/cache/local.js",
+			queue: "@opennextjs/aws/overrides/queue/sqs.js",
+		},
+		cache: {
+			wrapper: "@opennextjs/aws/overrides/wrappers/aws-lambda.js",
+			converter: "@opennextjs/aws/overrides/converters/aws-apigw-v2.js",
 			incrementalCache: "@opennextjs/aws/overrides/incrementalCache/s3.js",
 			tagCache: "@opennextjs/aws/overrides/tagCache/dynamodb.js",
-			queue: "@opennextjs/aws/overrides/queue/sqs.js",
 		},
 		revalidation: {
 			wrapper: "@opennextjs/aws/overrides/wrappers/aws-lambda.js",
@@ -31,8 +36,7 @@ export default buildAdapter((_config, buildOpts: BuildOptions) => ({
 		middleware: {
 			wrapper: "@opennextjs/aws/overrides/wrappers/aws-lambda.js",
 			converter: "@opennextjs/aws/overrides/converters/aws-cloudfront.js",
-			incrementalCache: "@opennextjs/aws/overrides/incrementalCache/s3-lite.js",
-			tagCache: "@opennextjs/aws/overrides/tagCache/dynamodb-lite.js",
+			cache: "@opennextjs/core/overrides/cache/local.js",
 			queue: "@opennextjs/aws/overrides/queue/sqs-lite.js",
 		},
 	},

packages/cloudflare/src/api/config.spec.ts

@@ -22,8 +22,7 @@ describe("defineCloudflareConfig", () => {
 			wrapper: "node",
 			converter: "node",
 			generateDockerfile: true,
-			incrementalCache: "dummy",
-			tagCache: "dummy",
+			cache: "dummy",
 			queue: "dummy",
 		});
 		expect(config.middleware).toMatchObject({

packages/cloudflare/src/api/config.ts

@@ -13,6 +13,7 @@ import type {
 } from "@opennextjs/core/types/overrides.js";
 
 import assetResolver from "./overrides/asset-resolver/index.js";
+import serviceCache from "./overrides/cache/service-cache.js";
 
 export type Override<T extends BaseOverride> = "dummy" | T | LazyLoadedOverride<T>;
 
@@ -89,16 +90,14 @@ export function defineCloudflareConfig(config: CloudflareOverrides = {}): OpenNe
 				wrapper: "node" as const,
 				converter: "node" as const,
 				generateDockerfile: true,
-				incrementalCache: "dummy" as const,
-				tagCache: "dummy" as const,
+				cache: "dummy" as const,
 				queue: "dummy" as const,
 			}
 		: {
 				wrapper: "cloudflare-node" as const,
 				converter: "edge" as const,
 				proxyExternalRequest: "fetch" as const,
-				incrementalCache: resolveIncrementalCache(incrementalCache),
-				tagCache: resolveTagCache(tagCache),
+				cache: () => serviceCache,
 				queue: resolveQueue(queue),
 				cdnInvalidation: resolveCdnInvalidation(cachePurge),
 			};
@@ -108,6 +107,12 @@ export function defineCloudflareConfig(config: CloudflareOverrides = {}): OpenNe
 			override: defaultOverride,
 			routePreloadingBehavior,
 		},
+		// The cache runs in the same worker, behind the `OpenNextCache` named entrypoint.
+		cacheHandler: {
+			incrementalCache: resolveIncrementalCache(incrementalCache),
+			tagCache: resolveTagCache(tagCache),
+			cdnInvalidation: resolveCdnInvalidation(cachePurge),
+		},
 		// node:crypto is used to compute cache keys
 		edgeExternals: ["node:crypto"],
 		cloudflare: {
@@ -120,8 +125,7 @@ export function defineCloudflareConfig(config: CloudflareOverrides = {}): OpenNe
 				wrapper: "cloudflare-edge",
 				converter: "edge",
 				proxyExternalRequest: "fetch",
-				incrementalCache: resolveIncrementalCache(incrementalCache),
-				tagCache: resolveTagCache(tagCache),
+				cache: () => serviceCache,
 				queue: resolveQueue(queue),
 			},
 			assetResolver: () => assetResolver,

packages/cloudflare/src/api/overrides/cache/service-cache.spec.ts

@@ -28,13 +28,20 @@ describe("serviceCache", () => {
 	});
 
 	describe("get", () => {
-		it("requests the key and the cache type", async () => {
-			await serviceCache.get("key/with/slashes", "fetch");
+		it("requests the key, the cache type and the additional tags", async () => {
+			await serviceCache.get("key/with/slashes", "fetch", ["tag1", "tag2"]);
 
 			const { url, method } = lastRequest();
 			expect(method).toBe("GET");
 			expect(url.pathname).toBe(`/cache/${encodeURIComponent("key/with/slashes")}`);
 			expect(url.searchParams.get("type")).toBe("fetch");
+			expect(url.searchParams.get("tags")).toBe("tag1,tag2");
+		});
+
+		it("omits the tags when there is none", async () => {
+			await serviceCache.get("key", "cache", []);
+
+			expect(lastRequest().url.searchParams.has("tags")).toBe(false);
 		});
 
 		it("returns null on a cache miss", async () => {
@@ -63,13 +70,17 @@ describe("serviceCache", () => {
 	describe("set", () => {
 		// The cache type is part of the key for the incremental caches, it has to be forwarded
 		// or entries would be written where they are not read from.
-		it("sends the value and the cache type", async () => {
-			await serviceCache.set("key", { kind: "FETCH", data: { headers: {}, body: "b", url: "u" } }, "fetch");
+		it("sends the value, cache type, and additional tags", async () => {
+			await serviceCache.set("key", { kind: "FETCH", data: { headers: {}, body: "b", url: "u" } }, "fetch", [
+				"tag1",
+				"tag2",
+			]);
 
 			const { url, method, body } = lastRequest();
 			expect(method).toBe("PUT");
 			expect(url.pathname).toBe("/cache/key");
 			expect(url.searchParams.get("type")).toBe("fetch");
+			expect(url.searchParams.get("tags")).toBe("tag1,tag2");
 			expect(JSON.parse(body as string)).toEqual({
 				value: { kind: "FETCH", data: { headers: {}, body: "b", url: "u" } },
 			});

packages/cloudflare/src/api/overrides/cache/service-cache.ts

@@ -35,12 +35,16 @@ function getCacheService(): Service {
 	return service;
 }
 
-function getCacheUrl(key: string, cacheType?: CacheEntryType) {
+function getCacheUrl(key: string, cacheType?: CacheEntryType, additionalTags?: string[]) {
 	const url = new URL(`/cache/${encodeURIComponent(key)}`, CACHE_ORIGIN);
 
 	if (cacheType) {
 		url.searchParams.set("type", cacheType);
 	}
+	if (additionalTags && additionalTags.length > 0) {
+		url.searchParams.set("tags", additionalTags.join(","));
+	}
+
 	return url.href;
 }
 
@@ -67,8 +71,8 @@ function ensureResponseOk(response: Pick<Response, "ok" | "status">, operation:
 const serviceCache = {
 	name: NAME,
 
-	get: async (key, cacheType) => {
-		const response = await getCacheService().fetch(getCacheUrl(key, cacheType));
+	get: async (key, cacheType, additionalTags) => {
+		const response = await getCacheService().fetch(getCacheUrl(key, cacheType, additionalTags));
 
 		const body = await response.text();
 		const headers: Record<string, string> = {};
@@ -80,8 +84,8 @@ const serviceCache = {
 		return parseCacheGetResponse(headers, body) as any;
 	},
 
-	set: async (key, value, cacheType) => {
-		const response = await getCacheService().fetch(getCacheUrl(key, cacheType), {
+	set: async (key, value, cacheType, additionalTags) => {
+		const response = await getCacheService().fetch(getCacheUrl(key, cacheType, additionalTags), {
 			method: "PUT",
 			headers: { "Content-Type": "application/json" },
 			body: JSON.stringify({ value }),

packages/cloudflare/src/api/overrides/internal.ts

@@ -34,7 +34,10 @@ export function computeCacheKey(key: string, options: KeyOptions) {
 
 export function isPurgeCacheEnabled(): boolean {
 	// The `?` is required at `openNextConfig?` or the Open Next build fails because of a type error
-	const cdnInvalidation = globalThis.openNextConfig?.default?.override?.cdnInvalidation;
+	// The cache handler function only has `cacheHandler` populated, the other functions only have `default`.
+	const cdnInvalidation =
+		globalThis.openNextConfig?.cacheHandler?.cdnInvalidation ??
+		globalThis.openNextConfig?.default?.override?.cdnInvalidation;
 
 	return cdnInvalidation !== undefined && cdnInvalidation !== "dummy";
 }

packages/cloudflare/src/cli/build/utils/ensure-cf-config.spec.ts

@@ -11,7 +11,7 @@ describe("ensureCloudflareConfig", () => {
 
 	test("rejects binding-backed caches in container mode", () => {
 		const config = defineCloudflareConfig({ container: true });
-		config.default.override!.incrementalCache = () => ({ name: "unsupported" }) as never;
+		config.default.override!.cache = () => ({ name: "unsupported" }) as never;
 
 		expect(() => ensureCloudflareConfig(config)).toThrow("Cloudflare Containers");
 	});