add(performance): a page on the Vary header - #204
Draft
jdevalk wants to merge 1 commit into
Draft
Conversation
Vary was referenced in passing on six pages but had no page of its own, despite this site depending on Vary: Accept for every spec URL. Covers the misconception (Vary extends the cache key; it is not a freshness control), both failure modes — negotiating on an unlisted header, and over-varying until nothing matches — and the RFC 9111 4.1 matching rules that make header normalisation matter. Sources: RFC 9110 12.5.5, RFC 9111 4.1, MDN, plus Nottingham's 2026 Common Crawl deployment figures for the over-varying case. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Deploying specification-website with
|
| Latest commit: |
3a411ff
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://e5fa4140.specification-website.pages.dev |
| Branch Preview URL: | https://add-vary-header-2026-09-07.specification-website.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
New spec page:
/spec/performance/vary/—Vary — the cache key contract, status recommended,order: 51(immediately aftercache-control).Also:
relatedSlugswired oncache-control,compression,conditional-requests,no-vary-search(performance) andmarkdown-source-endpoints(agent-readiness).Varybullets oncache-controlandcompressionnow link to the new page.2026-09-07-vary-header.md(added).SKILL.mdpage count +agent-skills/index.jsondigest re-signed vianpm run sign:skill.npm run buildpasses; lint andformat:checkclean; pre-commit hook green.Why now
Varywas referenced in passing on six existing pages and had no page of its own — a gap that stands out because this site's own middleware depends onVary: Acceptfor every canonical spec URL (functions/_middleware.ts, and CLAUDE.md lists removing it under "things you should not break"). Speccing what we already ship.The second prompt was the deployment data in Mark Nottingham's HTTP Workshop analysis (7 August 2026): ~26% of responses in the Tranco top 100,000 vary on more than one axis, roughly 3,000 sites list four or more fields, with outliers at 47. That is the over-varying failure, which nothing on the site currently warns about, and it pairs directly with the normative "SHOULD NOT include an excessive number of fields" in RFC 9110 §12.5.5.
Primary sources
*value, and the excessive-fields guidance.Status justification
recommended, notrequired. A missingVaryis only a contract breach when the server actually negotiated on a request header — RFC 9110 says MUST in that case. A site that serves one representation per URL and lets its CDN handle encoding needs nothing, sorequiredwould overstate the bar. The failure mode when it is needed is severe (a shared cache handing one client's representation to another), which is why it is notoptional.Notes
Linkheader change.🤖 Generated with Claude Code