HTTP deployment contracts

HTTP headers: cache policy, duplicate fields and download filenames

A pasted header or generated template is a configuration aid. Verify the actual response and receiving client before relying on its behavior.

Content updated: · Maintained by Hung Chi-Hsueh · corrections

Conditional requests: explain 304 and prevent lost updates

If-None-Match compares opaque tags weakly: W/"rev-7" can match "rev-7" for cache revalidation. A match leads to 304 for GET or HEAD, but 412 for other modeled methods. If-Match uses strong comparison to protect an update; a weak tag cannot satisfy it. ETags are supplied identifiers, not a tool's proof of content identity or authorization.

After ordinary request checks succeed, evaluate If-Match first; only without it evaluate If-Unmodified-Since. Then evaluate If-None-Match; only without it may GET/HEAD evaluate If-Modified-Since. Show why a date was ignored rather than treating every header as an independent AND condition. Proceed means normal handling continues, not a guaranteed 200.

The offline tester accepts IMF-fixdate dates only, stops on unsupported obsolete dates or leap seconds, and explains ignored invalid date conditions. It does not model Range, CDN age, authorization, or the exception for an operation already known to have succeeded. Verify actual server behavior independently.

Keep context, ordering and secrets separate

Request and response fields have different meanings. Preserve duplicate fields and their order while inspecting a block; Set-Cookie cannot be safely flattened into an arbitrary comma-separated value. Text copied from DevTools is not necessarily an exact HTTP/1.1 wire message.

Authorization, cookies, custom keys and even URLs or filenames can contain secrets. Leave values masked and share only the masked report. Revealing a value for local inspection does not authorize sharing it. Parsing reports syntax and context, not authenticity or transport security.

Storage, freshness and validation are different decisions

Unqualified no-cache permits storage but requires successful validation before reuse. no-store instructs caches not to store; it is not encryption or a reliable privacy guarantee. private prevents shared-cache storage, not all browser storage.

For shared caches, s-maxage takes precedence over max-age and Expires. An actual reuse decision also depends on response age, validators, status, method, Vary, request directives and implementation. A lifetime scenario is not proof of a real cache hit. Inspect live headers and CDN settings separately, especially for personalized responses.

A filename is a suggestion, never a trusted path

Use filename for an explicit ASCII fallback and filename* for a UTF-8 percent-encoded name. Quoting, backslash escaping and extended-parameter encoding are different operations. Reject CR, LF and other controls rather than trying to repair header injection.

Receiving software may sanitize or replace a filename. It must not trust path separators, device names or a file extension as permission to write anywhere or execute content. Test the header with the actual content type and receiving browser; generated text alone cannot establish safe download behavior.

Example
Cache-Control: private, no-cache
→ A browser may store; validation is required before reuse.

Content-Disposition: attachment; filename="report.csv"; filename*=UTF-8''%E5%A0%B1%E8%A1%A8.csv

Data provenance

Sources