Handle difference between max-age and s-maxage

Author: ascorbic

CLAUDE.md

@@ -78,13 +78,3 @@ Uses strict TypeScript configuration with:
 - Module: preserve (for bundler compatibility)
 - Strict mode with additional safety checks (`noUncheckedIndexedAccess`, `noImplicitOverride`)
 - Library-focused settings (declaration files, declaration maps)
-
-## Use Specialized Agents for Complex Tasks
-
-ALWAYS use the appropriate specialized agents for complex work:
-
-- **technical-architect**: For designing system architecture, evaluating technical approaches, planning major features
-- **code-reviewer**: For comprehensive code review after implementing significant code changes
-- **test-engineer**: For analyzing test failures, creating new tests, and enhancing test coverage. Should NOT fix application code - only creates/updates test files
-- **docs-author**: For creating or updating documentation, READMEs, changesets, or PR descriptions
-- **package-installer**: For installing npm packages with proper dependency management

packages/cache-handlers/src/types.ts

@@ -271,6 +271,11 @@ export interface ParsedCacheHeaders {
 	 * Whether ETag should be generated if not present
 	 */
 	shouldGenerateETag?: boolean;
+
+	/**
+	 * Filtered cache-control header value after removing used directives
+	 */
+	filteredCacheControl?: string;
 }
 
 /**

packages/cache-handlers/src/utils.ts

@@ -125,32 +125,63 @@ export function parseResponseHeaders<TRequest, TResponse>(
 		? headers.get("cdn-cache-control")
 		: null;
 
-	const finalCacheControl = cdnCacheControlHeader || cacheControlHeader;
-
 	if (cdnCacheControlHeader) {
 		result.headersToRemove.push("cdn-cache-control");
 	}
 
-	if (finalCacheControl) {
-		const directives = parseCacheControl(finalCacheControl);
-		result.isPrivate = !!directives.private;
-		result.noCache = !!directives["no-cache"];
-		result.noStore = !!directives["no-store"];
+	// Parse cdn-cache-control first (if present)
+	if (cdnCacheControlHeader) {
+		const cdnDirectives = parseCacheControl(cdnCacheControlHeader);
+		result.isPrivate = !!cdnDirectives.private;
+		result.noCache = !!cdnDirectives["no-cache"];
+		result.noStore = !!cdnDirectives["no-store"];
+
+		// cdn-cache-control uses max-age
+		if (typeof cdnDirectives["max-age"] === "number") {
+			result.ttl = cdnDirectives["max-age"];
+		}
+
+		if (typeof cdnDirectives["stale-while-revalidate"] === "number") {
+			result.staleWhileRevalidate = cdnDirectives["stale-while-revalidate"];
+		}
+	}
 
-		if (typeof directives["max-age"] === "number") {
-			result.ttl = directives["max-age"];
+	// Parse regular cache-control (fallback for properties not set by cdn-cache-control)
+	if (cacheControlHeader) {
+		const directives = parseCacheControl(cacheControlHeader);
+		
+		// Only use cache-control for properties not already set by cdn-cache-control
+		if (!cdnCacheControlHeader) {
+			result.isPrivate = !!directives.private;
+			result.noCache = !!directives["no-cache"];
+			result.noStore = !!directives["no-store"];
 		}
 
-		if (typeof directives["stale-while-revalidate"] === "number") {
+		// cache-control only uses s-maxage for TTL (ignore max-age)
+		if (!result.ttl && typeof directives["s-maxage"] === "number") {
+			result.ttl = directives["s-maxage"];
+		}
+
+		if (!result.staleWhileRevalidate && typeof directives["stale-while-revalidate"] === "number") {
 			result.staleWhileRevalidate = directives["stale-while-revalidate"];
 		}
+
+		// Filter out used directives from cache-control
+		const filteredCacheControl = filterCacheControlDirectives(cacheControlHeader);
+		if (filteredCacheControl !== cacheControlHeader && filteredCacheControl.trim()) {
+			// Only modify cache-control if we have remaining directives
+			result.filteredCacheControl = filteredCacheControl;
+		} else if (filteredCacheControl !== cacheControlHeader) {
+			// If we filtered everything out, remove the header entirely
+			result.headersToRemove.push("cache-control");
+		}
 	}
 
 	if (features.cacheTags !== false) {
 		const cacheTag = headers.get("cache-tag");
 		if (cacheTag) {
 			result.tags = parseCacheTags(cacheTag);
-			result.headersToRemove.push("cache-tag");
+			// Cache tags should be preserved for clients, not removed
 		}
 	}
 
@@ -188,7 +219,7 @@ export function parseResponseHeaders<TRequest, TResponse>(
 	}
 
 	// Cache only when explicitly allowed by headers (no implicit caching)
-	const hasExplicitCacheHeaders = !!finalCacheControl ||
+	const hasExplicitCacheHeaders = !!cacheControlHeader || !!cdnCacheControlHeader ||
 		!!headers.get("cache-tag") ||
 		!!headers.get("expires");
 	result.shouldCache = hasExplicitCacheHeaders &&
@@ -317,11 +348,44 @@ function getCookieValue(
 	return null;
 }
 
+/**
+ * Remove cache-control directives that were processed by cache-handlers
+ */
+export function filterCacheControlDirectives(
+	cacheControlValue: string,
+): string {
+	const directives = parseCacheControl(cacheControlValue);
+	
+	// Remove directives that cache-handlers processes
+	const usedDirectives = [
+		"s-maxage", // CDN-specific, we've processed it
+		"stale-while-revalidate" // Our SWR implementation
+	];
+
+	// Remove used directives
+	for (const directive of usedDirectives) {
+		delete directives[directive];
+	}
+
+	// Rebuild cache-control header from remaining directives
+	const remaining = Object.entries(directives)
+		.map(([key, value]) => {
+			if (value === true) {
+				return key;
+			}
+			return `${key}=${value}`;
+		})
+		.filter(Boolean);
+
+	return remaining.join(", ");
+}
+
 export function removeHeaders(
 	response: Response,
 	headersToRemove: string[],
+	filteredCacheControl?: string,
 ): Response {
-	if (headersToRemove.length === 0) {
+	if (headersToRemove.length === 0 && !filteredCacheControl) {
 		return response;
 	}
 
@@ -330,6 +394,15 @@ export function removeHeaders(
 		newHeaders.delete(headerName);
 	}
 
+	// Apply filtered cache-control if provided
+	if (filteredCacheControl !== undefined) {
+		if (filteredCacheControl.trim()) {
+			newHeaders.set("cache-control", filteredCacheControl);
+		} else {
+			newHeaders.delete("cache-control");
+		}
+	}
+
 	return new Response(response.body, {
 		status: response.status,
 		statusText: response.statusText,

packages/cache-handlers/src/write.ts

@@ -36,7 +36,7 @@ export async function writeToCache(
 			noCache: cacheInfo.noCache,
 			noStore: cacheInfo.noStore,
 		});
-		return removeHeaders(response, cacheInfo.headersToRemove);
+		return removeHeaders(response, cacheInfo.headersToRemove, cacheInfo.filteredCacheControl);
 	}
 	const cacheKey = await getCacheKey(request, cacheInfo.vary);
 	debug.logCacheWrite(request.url, cacheInfo.ttl, cacheInfo.tags);
@@ -83,5 +83,5 @@ export async function writeToCache(
 			cacheInfo.vary,
 		);
 	}
-	return removeHeaders(response, cacheInfo.headersToRemove);
+	return removeHeaders(response, cacheInfo.headersToRemove, cacheInfo.filteredCacheControl);
 }

packages/cache-handlers/test/deno/conditional.test.ts

@@ -1,4 +1,4 @@
-import { assertEquals, assertExists } from "jsr:@std/assert";
+import { assert, assertEquals, assertExists } from "jsr:@std/assert";
 import {
 	compareETags,
 	create304Response,
@@ -20,8 +20,8 @@ Deno.test("Conditional Requests - ETag generation", async () => {
 
 	assertExists(etag);
 	assertEquals(typeof etag, "string");
-	assertEquals(etag.startsWith('"'), true);
-	assertEquals(etag.endsWith('"'), true);
+	assert(etag.startsWith('"'));
+	assert(etag.endsWith('"'));
 });
 
 Deno.test("Conditional Requests - ETag parsing", () => {
@@ -33,7 +33,7 @@ Deno.test("Conditional Requests - ETag parsing", () => {
 	// Weak ETag
 	const weakETag = parseETag('W/"abc123"');
 	assertEquals(weakETag.value, "abc123");
-	assertEquals(weakETag.weak, true);
+	assert(weakETag.weak);
 
 	// Empty ETag
 	const emptyETag = parseETag("");
@@ -61,13 +61,13 @@ Deno.test("Conditional Requests - ETag comparison", () => {
 Deno.test("Conditional Requests - If-None-Match parsing", () => {
 	// Single ETag
 	const single = parseIfNoneMatch('"abc123"');
-	assertEquals(Array.isArray(single), true);
+	assert(Array.isArray(single));
 	assertEquals((single as string[]).length, 1);
 	assertEquals((single as string[])[0], '"abc123"');
 
 	// Multiple ETags
 	const multiple = parseIfNoneMatch('"abc123", "def456", W/"ghi789"');
-	assertEquals(Array.isArray(multiple), true);
+	assert(Array.isArray(multiple));
 	assertEquals((multiple as string[]).length, 3);
 
 	// Wildcard
@@ -76,14 +76,14 @@ Deno.test("Conditional Requests - If-None-Match parsing", () => {
 
 	// Empty
 	const empty = parseIfNoneMatch("");
-	assertEquals(Array.isArray(empty), true);
+	assert(Array.isArray(empty));
 	assertEquals((empty as string[]).length, 0);
 });
 
 Deno.test("Conditional Requests - HTTP date parsing", () => {
 	const validDate = parseHttpDate("Wed, 21 Oct 2015 07:28:00 GMT");
 	assertExists(validDate);
-	assertEquals(validDate instanceof Date, true);
+	assert(validDate instanceof Date);
 
 	const invalidDate = parseHttpDate("invalid date");
 	assertEquals(invalidDate, null);
@@ -108,8 +108,8 @@ Deno.test("Conditional Requests - validateConditionalRequest with ETag", () => {
 
 	const result = validateConditionalRequest(request, cachedResponse);
 
-	assertEquals(result.matches, true);
-	assertEquals(result.shouldReturn304, true);
+	assert(result.matches);
+	assert(result.shouldReturn304);
 	assertEquals(result.matchedValidator, "etag");
 });
 
@@ -134,8 +134,8 @@ Deno.test(
 
 		const result = validateConditionalRequest(request, cachedResponse);
 
-		assertEquals(result.matches, true);
-		assertEquals(result.shouldReturn304, true);
+		assert(result.matches);
+		assert(result.shouldReturn304);
 		assertEquals(result.matchedValidator, "last-modified");
 	},
 );
@@ -250,7 +250,7 @@ Deno.test("Conditional Requests - unified handler ETag generation", async () =>
 			Promise.resolve(
 				new Response("etag-body", {
 					headers: {
-						"cache-control": "public, max-age=3600",
+						"cache-control": "public, s-maxage=3600",
 						"content-type": "application/json",
 					},
 				}),
@@ -267,9 +267,9 @@ Deno.test("Conditional Requests - unified handler ETag generation", async () =>
 Deno.test("Conditional Requests - Default configuration", () => {
 	const config = getDefaultConditionalConfig();
 
-	assertEquals(config.etag, true);
-	assertEquals(config.lastModified, true);
-	assertEquals(config.weakValidation, true);
+	assert(config.etag);
+	assert(config.lastModified);
+	assert(config.weakValidation);
 });
 
 Deno.test("Conditional Requests - disabled returns full response", async () => {