feat(core): honour Cache-Control on cache entries

The cache handler function now derives freshness from the entry's
`Cache-Control` rather than from the revalidation timestamp alone.

- New `utils/cache-control.ts` parses `s-maxage`, `stale-while-revalidate` and
  `must-revalidate`, and the resulting fresh / stale / expired state travels
  back to the caller through the response headers that `cache-get.ts` reads.
- `cacheInterceptor` follows the same state.
- The `fetch` and `local` cache overrides forward the cache type in `set`:
  incremental caches that key entries on the type were writing them where `get`
  does not look.

Author: conico974

.changeset/cache-control-revalidation.md

@@ -0,0 +1,13 @@
+---
+"@opennextjs/core": patch
+---
+
+Derive revalidation from `Cache-Control` on cache entries
+
+The cache handler function now parses the `Cache-Control` of an entry to decide whether it is fresh,
+stale or expired, instead of relying on the revalidation timestamp alone. `s-maxage`,
+`stale-while-revalidate` and `must-revalidate` are honoured, and the resulting state is carried back
+to the caller in the response headers.
+
+The `fetch` and `local` cache overrides also forward the cache type when writing an entry.
+Incremental caches that key entries on the type were writing them where `get` does not look.

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

@@ -56,13 +56,14 @@ describe("serviceCache", () => {
 						"x-opennext-cache-type": "cache",
 						"x-opennext-cache-sub-type": "route",
 						"x-opennext-cache-last-modified": "1234",
+						"x-opennext-cache-revalidate": "60",
 					},
 				})
 			);
 
 			await expect(serviceCache.get("key")).resolves.toEqual({
 				lastModified: 1234,
-				value: expect.objectContaining({ type: "route", body: "body" }),
+				value: expect.objectContaining({ type: "route", body: "body", revalidate: 60 }),
 			});
 		});
 	});

packages/core/src/adapters/cache-adapter.ts

@@ -4,7 +4,6 @@ import type { StoredComposableCacheEntry } from "@/types/cache";
 import type { InternalEvent, InternalResult } from "@/types/open-next";
 import type {
 	CacheEntryType,
-	CachedFile,
 	CachedFetchValue,
 	CacheValue,
 	OpenNextHandlerOptions,
@@ -13,6 +12,7 @@ import type {
 
 import { createGenericHandler } from "../core/createGenericHandler.js";
 import { resolveCdnInvalidation, resolveIncrementalCache, resolveTagCache } from "../core/resolve.js";
+import { computeEntryCacheControl } from "../utils/cache-control.js";
 import { getTagsFromValue, isStale, writeTags } from "../utils/cache.js";
 import { runWithOpenNextRequestContext } from "../utils/promise.js";
 import { toReadableStream } from "../utils/stream.js";
@@ -130,19 +130,23 @@ async function handleGet(
 			};
 		}
 
-		if (result.value && !result.shouldBypassTagCache) {
-			let tags: string[] = [...additionalTags];
+		// The tags are also used to make the response purgeable, so they are derived for every hit,
+		// including the ones bypassing the tag cache.
+		let tags: string[] = [...additionalTags];
+
+		if (cacheType === "cache") {
+			tags = [...tags, ...getTagsFromValue(result.value as CacheValue<"cache">)];
+		} else if (cacheType === "fetch") {
+			const fetchValue = result.value as CachedFetchValue;
+			tags = [...tags, ...(fetchValue.tags ?? []), ...(fetchValue.data?.tags ?? [])];
+		} else if (cacheType === "composable") {
+			const composableValue = result.value as StoredComposableCacheEntry;
+			tags = [...tags, ...(composableValue.tags ?? [])];
+		}
 
-			if (cacheType === "cache") {
-				tags = [...tags, ...getTagsFromValue(result.value as CacheValue<"cache">)];
-			} else if (cacheType === "fetch") {
-				const fetchValue = result.value as CachedFetchValue;
-				tags = [...tags, ...(fetchValue.tags ?? []), ...(fetchValue.data?.tags ?? [])];
-			} else if (cacheType === "composable") {
-				const composableValue = result.value as StoredComposableCacheEntry;
-				tags = [...tags, ...(composableValue.tags ?? [])];
-			}
+		let isEntryStale = false;
 
+		if (!result.shouldBypassTagCache) {
 			const lastModified = result.lastModified ?? Date.now();
 
 			if (tags.length > 0) {
@@ -163,13 +167,15 @@ async function handleGet(
 			}
 
 			// Check if the cache entry is stale (valid but needs background revalidation)
-			const _isStale = tags.length > 0 ? await isStale(key, tags, lastModified) : false;
-			if (_isStale) {
+			isEntryStale = tags.length > 0 ? await isStale(key, tags, lastModified) : false;
+			if (isEntryStale) {
 				result.lastModified = 1;
 			}
 		}
 
-		return buildCacheGetResponse(result);
+		// We default to the entry key when no tag is found, so that page router based entries can also
+		// be purged this way.
+		return buildCacheGetResponse(result, isEntryStale, tags.length > 0 ? tags : [key]);
 	} catch (e) {
 		error("Failed to get cache entry", e);
 		return buildErrorResponse("Failed to get cache entry", 500);
@@ -399,14 +405,24 @@ async function handleRevalidateTags(body?: Buffer): Promise<InternalResult> {
 // Cache GET response builder //
 /////////////////////////////
 
-function buildCacheGetResponse(result: WithLastModified<CacheValue<CacheEntryType>>): InternalResult {
+function buildCacheGetResponse(
+	result: WithLastModified<CacheValue<CacheEntryType>>,
+	isStaleFromTagCache: boolean,
+	tags: string[]
+): InternalResult {
 	const value = result.value!;
 
 	const headers: Record<string, string | string[]> = {
 		"x-opennext-cache-found": "true",
-		"Cache-Control": "no-store",
+		"Cache-Control": computeEntryCacheControl(value, result.lastModified, isStaleFromTagCache),
 	};
 
+	// The `Cache-Control` above lets an HTTP cache store this response, it can only be invalidated
+	// through a purge keyed on these tags. See `computeEntryCacheControl`.
+	if (tags.length > 0) {
+		headers["cache-tag"] = tags.join(",");
+	}
+
 	if (result.lastModified !== undefined) {
 		headers["x-opennext-cache-last-modified"] = String(result.lastModified);
 	}
@@ -415,24 +431,28 @@ function buildCacheGetResponse(result: WithLastModified<CacheValue<CacheEntryTyp
 	}
 
 	if ("kind" in value && value.kind === "FETCH") {
-		return buildFetchResponse(value as CachedFetchValue, headers);
+		return buildFetchResponse(value as CacheValue<"fetch">, headers);
 	}
 
 	if ("type" in value) {
-		return buildCachedFileResponse(value as CachedFile, headers);
+		return buildCachedFileResponse(value as CacheValue<"cache">, headers);
 	}
 
 	return buildComposableResponse(value as StoredComposableCacheEntry, headers);
 }
 
 function buildFetchResponse(
-	value: CachedFetchValue,
+	value: CacheValue<"fetch">,
 	headers: Record<string, string | string[]>
 ): InternalResult {
 	headers["x-opennext-cache-type"] = "fetch";
 	headers["x-opennext-cache-fetch-kind"] = "FETCH";
 	headers["x-opennext-cache-fetch-data-url"] = value.data.url;
 
+	if (value.revalidate !== undefined) {
+		headers["x-opennext-cache-revalidate"] = String(value.revalidate);
+	}
+
 	if (value.data.status !== undefined) {
 		headers["x-opennext-cache-fetch-data-status"] = String(value.data.status);
 	}
@@ -458,12 +478,16 @@ function buildFetchResponse(
 }
 
 function buildCachedFileResponse(
-	value: CachedFile,
+	value: CacheValue<"cache">,
 	headers: Record<string, string | string[]>
 ): InternalResult {
 	headers["x-opennext-cache-type"] = "cache";
 	headers["x-opennext-cache-sub-type"] = value.type;
 
+	if (value.revalidate !== undefined) {
+		headers["x-opennext-cache-revalidate"] = String(value.revalidate);
+	}
+
 	if (value.meta?.status !== undefined) {
 		headers["x-opennext-cache-meta-status"] = String(value.meta.status);
 	}

packages/core/src/core/routing/cacheInterceptor.ts

@@ -4,14 +4,14 @@ import { NextConfig, PrerenderManifest } from "@/config/index";
 import type { InternalEvent, InternalResult, MiddlewareEvent, PartialResult } from "@/types/open-next";
 import type { CacheValue } from "@/types/overrides";
 import { isBinaryContentType } from "@/utils/binary";
+import { CACHE_ONE_YEAR } from "@/utils/cache-control";
 import { emptyReadableStream, toReadableStream } from "@/utils/stream";
 
 import { debug, error } from "../../adapters/logger";
 
 import { localizePath } from "./i18n";
 import { generateMessageGroupId } from "./queue";
 
-const CACHE_ONE_YEAR = 60 * 60 * 24 * 365;
 const CACHE_ONE_MONTH = 60 * 60 * 24 * 30;
 
 /*

packages/core/src/overrides/cache/fetch.ts

@@ -20,8 +20,11 @@ const fetchCache: Cache = {
 		// oxlint-disable-next-line @typescript-eslint/no-explicit-any
 		return parseCacheGetResponse(headers, bodyText) as any;
 	},
-	set: async (key, value, _cacheType) => {
-		const url = `${CACHE_URL}/cache/${encodeURIComponent(key)}`;
+	set: async (key, value, cacheType) => {
+		// The cache type has to be forwarded: incremental caches may key entries on it,
+		// writing without it would store the entry where `get` does not look for it.
+		const queryString = cacheType ? `?type=${cacheType}` : "";
+		const url = `${CACHE_URL}/cache/${encodeURIComponent(key)}${queryString}`;
 		await fetch(url, {
 			method: "PUT",
 			headers: { "Content-Type": "application/json" },

packages/core/src/overrides/cache/local.ts

@@ -41,17 +41,21 @@ const localCache: Cache = {
 		// oxlint-disable-next-line @typescript-eslint/no-explicit-any
 		return parseCacheGetResponse(result.headers, bodyText) as any;
 	},
-	set: async (key, value, _cacheType) => {
+	set: async (key, value, cacheType) => {
 		const h = (await getHandler())!;
 		const encodedKey = encodeURIComponent(key);
 		const url = `https://on/cache/${encodedKey}`;
+		// The cache type has to be forwarded: incremental caches may key entries on it,
+		// writing without it would store the entry where `get` does not look for it.
+		const query: Record<string, string> = {};
+		if (cacheType) query.type = cacheType;
 		const event: InternalEvent = {
 			type: "core",
 			method: "PUT",
 			rawPath: `/cache/${encodedKey}`,
 			url,
 			headers: { "Content-Type": "application/json" },
-			query: {},
+			query,
 			cookies: {},
 			remoteAddress: "127.0.0.1",
 			body: Buffer.from(JSON.stringify({ value })),

packages/core/src/utils/cache-control.ts

@@ -0,0 +1,100 @@
+import type { StoredComposableCacheEntry } from "@/types/cache";
+import type { CacheEntryType, CacheValue } from "@/types/overrides";
+
+import { error } from "../adapters/logger";
+
+export const CACHE_ONE_YEAR = 60 * 60 * 24 * 365;
+
+const NO_STORE = "no-store";
+
+/**
+ * Composable cache entries may carry `Infinity` (i.e. `cacheLife("max")`), and an entry that was
+ * just written has a negative age when `Date.now()` drifts, so every duration is clamped.
+ */
+function clampSeconds(seconds: number): number {
+	if (!Number.isFinite(seconds)) {
+		return CACHE_ONE_YEAR;
+	}
+	return Math.max(0, Math.min(Math.floor(seconds), CACHE_ONE_YEAR));
+}
+
+function buildCacheControl(sMaxAge: number, staleWhileRevalidate: number): string {
+	return `s-maxage=${clampSeconds(sMaxAge)}, stale-while-revalidate=${clampSeconds(staleWhileRevalidate)}`;
+}
+
+/**
+ * Computes the `Cache-Control` of a cache handler `GET` hit, so that an HTTP cache sitting in front
+ * of the cache handler function can serve reads without hitting the underlying store.
+ *
+ * A stale or expired entry is never stored: the next read has to reach the cache handler function so
+ * that the staleness is signaled to the server (through `lastModified = 1`).
+ *
+ * **This is only correct when the cached responses can be purged**, either with a
+ * `cdnInvalidationHandler` or through another purge mechanism keyed on the `cache-tag` header that
+ * `buildCacheGetResponse` emits. Tag revalidation cannot invalidate an intermediate cache on its own,
+ * so without purging `revalidateTag`/`revalidatePath` would be masked for as long as the entry is
+ * stored - up to a year for SSG entries.
+ */
+export function computeEntryCacheControl(
+	value: CacheValue<CacheEntryType>,
+	lastModified: number | undefined,
+	isStaleFromTagCache: boolean
+): string {
+	if (isStaleFromTagCache) {
+		return NO_STORE;
+	}
+
+	// Same discrimination as `buildCacheGetResponse`: fetch entries have a `kind`, cached files have
+	// a `type`, composable entries have neither.
+	const isFetch = "kind" in value && value.kind === "FETCH";
+	const isCachedFile = "type" in value;
+
+	if (!isFetch && !isCachedFile) {
+		return computeComposableCacheControl(value as StoredComposableCacheEntry);
+	}
+
+	return computeRevalidateCacheControl(value.revalidate, lastModified);
+}
+
+function computeComposableCacheControl(value: StoredComposableCacheEntry): string {
+	const age = (Date.now() - value.timestamp) / 1000;
+
+	if (age >= value.expire || age >= value.revalidate) {
+		return NO_STORE;
+	}
+
+	// Composable entries are the only ones carrying an explicit `expire`, so they are also the only
+	// ones for which we can derive a real stale-while-revalidate window.
+	return buildCacheControl(value.revalidate - age, value.expire - value.revalidate);
+}
+
+function computeRevalidateCacheControl(
+	revalidate: number | false | undefined,
+	lastModified: number | undefined
+): string {
+	if (revalidate === 0) {
+		return NO_STORE;
+	}
+
+	if (revalidate === undefined) {
+		// `revalidate` is written by the cache handler for every entry, we should always have one here.
+		error("Missing `revalidate` on a cache entry, assuming it is a static (SSG) entry");
+	}
+
+	if (revalidate === undefined || revalidate === false) {
+		return buildCacheControl(CACHE_ONE_YEAR, 0);
+	}
+
+	const age = (Date.now() - (lastModified ?? Date.now())) / 1000;
+	const remainingTtl = revalidate - age;
+
+	if (remainingTtl <= 0) {
+		return NO_STORE;
+	}
+
+	// `stale-while-revalidate` is intentionally `0` for fetch and cached file entries: a response
+	// served during a stale-while-revalidate window still carries its original
+	// `x-opennext-cache-last-modified`, which would hide the `lastModified = 1` staleness signal that
+	// `cacheInterceptor` and the composable cache rely on to trigger a background revalidation.
+	return buildCacheControl(remainingTtl, 0);
+}

packages/core/src/utils/cache-get.ts

@@ -22,6 +22,17 @@ function getHeaderNumber(headers: HeadersMap, name: string): number | undefined
 	return Number.isNaN(n) ? undefined : n;
 }
 
+/**
+ * `revalidate` is either a number of seconds or `false` for entries that never revalidate (SSG).
+ */
+function getHeaderRevalidate(headers: HeadersMap): number | false | undefined {
+	const v = getHeaderValue(headers, "x-opennext-cache-revalidate");
+	if (v === undefined) return undefined;
+	if (v === "false") return false;
+	const n = Number(v);
+	return Number.isNaN(n) ? undefined : n;
+}
+
 function collectPrefixedHeaders(headers: HeadersMap, prefix: string): Record<string, string | string[]> {
 	const result: Record<string, string | string[]> = {};
 	for (const [key, value] of Object.entries(headers)) {
@@ -99,7 +110,7 @@ function reconstructFetch(headers: HeadersMap, bodyText: string, base: Base) {
 	const dataTags = dataTagsStr ? JSON.parse(dataTagsStr) : undefined;
 	const fetchTagsStr = getHeaderValue(headers, "x-opennext-cache-fetch-tags");
 	const fetchTags = fetchTagsStr ? JSON.parse(fetchTagsStr) : undefined;
-	const revalidate = getHeaderNumber(headers, "x-opennext-cache-revalidate");
+	const revalidate = getHeaderRevalidate(headers);
 
 	const dataHeaders = collectPrefixedHeaders(headers, "x-opennext-cache-header-") as Record<string, string>;
 
@@ -123,7 +134,7 @@ function reconstructCachedFile(headers: HeadersMap, bodyText: string, base: Base
 	const subType = getHeaderValue(headers, "x-opennext-cache-sub-type");
 	const metaStatus = getHeaderNumber(headers, "x-opennext-cache-meta-status");
 	const metaPostponed = getHeaderValue(headers, "x-opennext-cache-meta-postponed");
-	const revalidate = getHeaderNumber(headers, "x-opennext-cache-revalidate");
+	const revalidate = getHeaderRevalidate(headers);
 
 	const metaHeaders = collectPrefixedHeaders(headers, "x-opennext-cache-header-");
 	const hasMetaHeaders = Object.keys(metaHeaders).length > 0;