Skip to content

docs: show what each Cache-Control directive actually does - #145

Merged
allen0099 merged 1 commit into
masterfrom
docs/cache-control-table
Sep 25, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/cache-control-table

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Closes #143

Changes

  • docs/HTTP_CACHING.md: the Cache-Control table now has these columns: directive, how to set it, whether it is sent in the header, and its effect on the server-side cache.
    • public, immutable, must-revalidate, stale-while-revalidate and stale-if-error are marked header-only.
    • The directives that @cache cannot emit are listed with no setting.
    • A short paragraph explains that no_cache/no_store replace the rest of the header, and links to Cache flow.
  • New subsection, "The request's Cache-Control is ignored": it documents that client request directives such as no-cache and max-age=0 do not bypass the cache. This is by design, because otherwise any client could send every request to the handler. If-None-Match is still honoured.
  • docs/README.zh-TW.md: the same table and note, in Traditional Chinese. The claim that the directives are completely implemented ("完整實現 Cache-Control 指令") is replaced.
  • README.md: "comprehensive HTTP caching support" becomes a concrete description.
  • CHANGELOG: entry under Fixed.

Adding the directives that @cache cannot emit yet is tracked in #144.

Verification

  • zensical build --strict passes, and the table renders with all 13 directives.
  • I checked the documented behaviour against a running app:
    • Cache-Control: no-cache and max-age=0 request headers still get the cached response.
    • no_store=True responses carry no ETag.

The directive table marked header-only directives as simply supported and
described them with the spec's wording. Show how each one is set, whether it
is sent, and its effect on the server-side cache, and document that the
request's own Cache-Control is ignored by design. Tone down the README
claims of comprehensive / complete directive support.

Closes #143
@allen0099
allen0099 merged commit 7f5b49f into master Sep 25, 2026
2 checks passed
@allen0099
allen0099 deleted the docs/cache-control-table branch September 26, 2026 11:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cache-Control docs overstate what @cache supports

1 participant