Local file endpoint: send cache validators and answer conditional requests

[woerndl]

Description

The local file endpoint (packages/payload/src/uploads/endpoints/getFile.ts) streams files without cache validators. It sets Content-Type, Content-Length, and Accept-Ranges, but no ETag and no Last-Modified, and it never reads If-None-Match or If-Modified-Since.

If you serve uploads from local disk and set a Cache-Control max-age through upload.modifyResponseHeaders:

• On a browser reload, the browser wants to revalidate its cached responses. There's nothing to revalidate with, so every image is downloaded again in full.
• Once the max-age runs out, the same happens on normal navigation.

Each of those requests could be a 304 Not Modified. The handler already calls fsPromises.stat on every request, so everything needed for a Last-Modified header (or a weak ETag from size and mtime) is already read, then thrown away.

Why the config options can't fix this

• upload.modifyResponseHeaders only gets { headers }. No document, no filename, no file stats, so it can't compute a per-file validator. It also can't answer with a 304, because the conditional check needs the request.
• upload.handlers get the request and the document and can return a full Response. But a handler that returns nothing falls through to the default path, which builds a fresh Headers object, so any headers the handler set are dropped. To attach a validator to the 200 you have to serve the whole response yourself: content type detection, Content-Length, range requests, the SVG Content-Security-Policy, and the CORS headers that headersWithCors normally adds. And then keep that copy in sync with getFileHandler across Payload upgrades.

Proposal

Either of these would work:

1. Default validators in getFileHandler. Set Last-Modified from the existing stat result, maybe a weak ETag from size and mtime, answer If-None-Match and If-Modified-Since with 304 Not Modified, and send the same cache headers on the 304 as on the 200. If-None-Match wins when both are present.
2. A response hook that gets the request, the document, the filename, and the file stats, and can return a Response directly. Then users can add validators without copying the streaming path.

Option 1 seems like the better fit for local disk. Cloud storage handlers return their own Response before this code runs, so they're not affected.

Versions

• Checked against current main (2026-07-14): still no validators, no conditional handling, and modifyResponseHeaders still only gets { headers }.
• We run v3 (payload 3.85.0, local disk via staticDir, no storage adapter), where the behavior is the same. Posting as a v4 feature request since v3 only takes bug fixes.