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,9 +130,9 @@ async function handleGet(
 			};
 		}
 
-		// `getTagsFromValue` also strips the internal `x-next-cache-tags` header from the entry, so
-		// the tags are derived for every hit - including the ones bypassing the tag cache - or that
-		// header would be handed back to Next.js and echoed to the client.
+		// The tags are also used to make the response purgeable, so they are derived for every hit,
+		// including the ones bypassing the tag cache. `getTagsFromValue` additionally strips the
+		// internal `x-next-cache-tags` header, which would otherwise be echoed to the client.
 		let tags: string[] = [...additionalTags];
 
 		if (cacheType === "cache") {
@@ -145,6 +145,8 @@ async function handleGet(
 			tags = [...tags, ...(composableValue.tags ?? [])];
 		}
 
+		let isEntryStale = false;
+
 		if (!result.shouldBypassTagCache) {
 			const lastModified = result.lastModified ?? Date.now();
 
@@ -166,13 +168,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);
@@ -409,14 +413,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);
 	}
@@ -425,11 +439,11 @@ 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);

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/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;