fix(server): honor static freshness validators

Author: Boyeep

packages/vinext/src/server/http-conditional.ts

@@ -14,6 +14,42 @@ export function matchesIfNoneMatch(ifNoneMatch: string | undefined, etag: string
   });
 }
 
+type StaticConditionalHeaders = {
+  cacheControl?: string | string[];
+  ifNoneMatch?: string | string[];
+  ifModifiedSince?: string | string[];
+};
+
+/**
+ * Determine whether a static representation is fresh for a GET/HEAD request.
+ *
+ * If-None-Match takes precedence over If-Modified-Since, and Cache-Control:
+ * no-cache forces the representation to be transferred even when a validator
+ * matches. Modification times are compared at HTTP-date (whole-second)
+ * precision.
+ */
+export function isFreshStaticRequest(
+  headers: StaticConditionalHeaders,
+  etag: string,
+  mtimeMs: number,
+): boolean {
+  const cacheControl = joinHeader(headers.cacheControl);
+  if (cacheControl && /(?:^|,)\s*no-cache\s*(?:,|$)/i.test(cacheControl)) return false;
+
+  const ifNoneMatch = joinHeader(headers.ifNoneMatch);
+  if (ifNoneMatch !== undefined) return matchesIfNoneMatch(ifNoneMatch, etag);
+
+  const ifModifiedSince = joinHeader(headers.ifModifiedSince);
+  if (!ifModifiedSince) return false;
+  const modifiedSinceMs = Date.parse(ifModifiedSince);
+  if (Number.isNaN(modifiedSinceMs)) return false;
+  return Math.floor(mtimeMs / 1000) <= Math.floor(modifiedSinceMs / 1000);
+}
+
+function joinHeader(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value.join(", ") : value;
+}
+
 function stripWeakPrefix(value: string): string {
   return value.startsWith("W/") ? value.slice(2) : value;
 }

packages/vinext/src/server/prod-server.ts

@@ -93,7 +93,7 @@ import {
   selectContentEncoding,
 } from "./accept-encoding.js";
 import { ifRangeAllowsRange, parseByteRange, type ByteRange } from "./http-range.js";
-import { matchesIfNoneMatch } from "./http-conditional.js";
+import { isFreshStaticRequest } from "./http-conditional.js";
 import type { NextI18nConfig } from "../config/next-config.js";
 import { readTrustedRevalidationHostname } from "./revalidation-host.js";
 
@@ -636,11 +636,17 @@ async function tryServeStatic(
             ? entry.gz!
             : entry.original;
 
-    const ifNoneMatch = req.headers["if-none-match"];
     if (
       responseStatus === 200 &&
-      typeof ifNoneMatch === "string" &&
-      matchesIfNoneMatch(ifNoneMatch, entry.etag)
+      isFreshStaticRequest(
+        {
+          cacheControl: req.headers["cache-control"],
+          ifNoneMatch: req.headers["if-none-match"],
+          ifModifiedSince: req.headers["if-modified-since"],
+        },
+        entry.etag,
+        entry.mtimeMs,
+      )
     ) {
       const notModifiedHeaders = variesByEncoding
         ? mergeVaryHeader({ ...entry.notModifiedHeaders, ...extraHeaders }, "Accept-Encoding")
@@ -766,11 +772,17 @@ async function tryServeStatic(
   );
 
   const encoding = isCompressible ? negotiateEncoding(req) : "identity";
-  const ifNoneMatch = req.headers["if-none-match"];
   if (
     responseStatus === 200 &&
-    typeof ifNoneMatch === "string" &&
-    matchesIfNoneMatch(ifNoneMatch, etag)
+    isFreshStaticRequest(
+      {
+        cacheControl: req.headers["cache-control"],
+        ifNoneMatch: req.headers["if-none-match"],
+        ifModifiedSince: req.headers["if-modified-since"],
+      },
+      etag,
+      resolved.mtimeMs,
+    )
   ) {
     const notModifiedHeaders = isCompressible
       ? mergeVaryHeader(baseHeaders, "Accept-Encoding")

tests/http-conditional.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
-import { matchesIfNoneMatch } from "../packages/vinext/src/server/http-conditional.js";
+import {
+  isFreshStaticRequest,
+  matchesIfNoneMatch,
+} from "../packages/vinext/src/server/http-conditional.js";
 
 describe("matchesIfNoneMatch", () => {
   it("matches an identical entity tag", () => {
@@ -33,3 +36,55 @@ describe("matchesIfNoneMatch", () => {
     expect(matchesIfNoneMatch("", '"asset"')).toBe(false);
   });
 });
+
+describe("isFreshStaticRequest", () => {
+  const mtimeMs = Date.parse("2026-07-26T12:34:56.789Z");
+
+  it("uses If-None-Match before If-Modified-Since", () => {
+    expect(
+      isFreshStaticRequest(
+        {
+          ifNoneMatch: '"different"',
+          ifModifiedSince: "Mon, 27 Jul 2026 12:34:56 GMT",
+        },
+        '"asset"',
+        mtimeMs,
+      ),
+    ).toBe(false);
+  });
+
+  it("matches If-Modified-Since at whole-second precision", () => {
+    expect(
+      isFreshStaticRequest(
+        { ifModifiedSince: "Sun, 26 Jul 2026 12:34:56 GMT" },
+        '"asset"',
+        mtimeMs,
+      ),
+    ).toBe(true);
+    expect(
+      isFreshStaticRequest(
+        { ifModifiedSince: "Sun, 26 Jul 2026 12:34:55 GMT" },
+        '"asset"',
+        mtimeMs,
+      ),
+    ).toBe(false);
+  });
+
+  it("ignores invalid If-Modified-Since values", () => {
+    expect(isFreshStaticRequest({ ifModifiedSince: "not a date" }, '"asset"', mtimeMs)).toBe(false);
+  });
+
+  it("honors Cache-Control: no-cache despite matching validators", () => {
+    expect(
+      isFreshStaticRequest(
+        {
+          cacheControl: "max-age=0, No-Cache",
+          ifNoneMatch: 'W/"asset"',
+          ifModifiedSince: "Mon, 27 Jul 2026 12:34:56 GMT",
+        },
+        '"asset"',
+        mtimeMs,
+      ),
+    ).toBe(false);
+  });
+});

tests/serve-static.test.ts

@@ -424,6 +424,39 @@ describe("tryServeStatic (with StaticFileCache)", () => {
     expect(captured.status).toBe(200);
   });
 
+  it("returns 304 when a cached asset has not changed since If-Modified-Since", async () => {
+    await writeFile(clientDir, "conditional.txt", "cached content");
+    const cache = await StaticFileCache.create(clientDir);
+    const entry = cache.lookup("/conditional.txt")!;
+    const req = mockReq(undefined, {
+      "if-modified-since": entry.original.headers["Last-Modified"],
+    });
+    const { res, captured } = mockRes();
+
+    await tryServeStatic(req, res, clientDir, "/conditional.txt", true, cache);
+    await captured.ended;
+
+    expect(captured.status).toBe(304);
+    expect(captured.headers["Last-Modified"]).toBe(entry.original.headers["Last-Modified"]);
+  });
+
+  it("honors Cache-Control: no-cache when a cached asset ETag matches", async () => {
+    await writeFile(clientDir, "forced-revalidation.txt", "cached content");
+    const cache = await StaticFileCache.create(clientDir);
+    const entry = cache.lookup("/forced-revalidation.txt")!;
+    const req = mockReq(undefined, {
+      "cache-control": "no-cache",
+      "if-none-match": entry.etag,
+    });
+    const { res, captured } = mockRes();
+
+    await tryServeStatic(req, res, clientDir, "/forced-revalidation.txt", true, cache);
+    await captured.ended;
+
+    expect(captured.status).toBe(200);
+    expect(captured.body.toString()).toBe("cached content");
+  });
+
   it("304 response excludes Content-Type per RFC 9110", async () => {
     await writeFile(clientDir, "_next/static/rfc-aaa111.js", "rfc content");
 
@@ -1026,6 +1059,36 @@ describe("tryServeStatic (with StaticFileCache)", () => {
     expect(captured.headers.Vary).toBe("Accept-Encoding");
   });
 
+  it("supports If-Modified-Since on the slow path", async () => {
+    await writeFile(clientDir, "conditional-slow.txt", "slow content");
+    const stat = await fsp.stat(path.join(clientDir, "conditional-slow.txt"));
+    const req = mockReq(undefined, {
+      "if-modified-since": new Date(stat.mtimeMs).toUTCString(),
+    });
+    const { res, captured } = mockRes();
+
+    await tryServeStatic(req, res, clientDir, "/conditional-slow.txt", true);
+    await captured.ended;
+
+    expect(captured.status).toBe(304);
+    expect(captured.headers["Last-Modified"]).toBe(new Date(stat.mtimeMs).toUTCString());
+  });
+
+  it("honors Cache-Control: no-cache on the slow path", async () => {
+    await writeFile(clientDir, "_next/static/no-cache-slow-abc123.js", "slow content");
+    const req = mockReq(undefined, {
+      "cache-control": "no-cache",
+      "if-none-match": 'W/"abc123"',
+    });
+    const { res, captured } = mockRes();
+
+    await tryServeStatic(req, res, clientDir, "/_next/static/no-cache-slow-abc123.js", true);
+    await captured.ended;
+
+    expect(captured.status).toBe(200);
+    expect(captured.body.toString()).toBe("slow content");
+  });
+
   it("slow path 304 omits Vary for non-compressible content (compress=false)", async () => {
     await writeFile(clientDir, "photo.jpg", Buffer.alloc(100, 0xff));