Document cacheControl directive, identity-floor caching headers, and static plugin cache options - #578
Document cacheControl directive, identity-floor caching headers, and static plugin cache options#578kriszyp wants to merge 2 commits into
Conversation
…lugin cache options Covers two harper core PRs (#1746 and #1748): - schema.md: add `cacheControl` to the `@table` argument table and a dedicated `#### cacheControl` section explaining anonymous-only emission, the identity floor on authenticated responses, the explicit-opt-in requirement, and the `static cacheControl` JS class-property equivalent. - rest/headers.md: add a Cache-Control section documenting the three- tier policy (anonymous declared, authenticated identity floor, CORS Vary:Origin). - http/configuration.md: one-sentence note that CORS-enabled responses now emit `Vary: Origin` so shared caches key correctly by origin. - static-files/overview.md: add a "Cache Headers" subsection with `maxAge`, `immutable`, and `cacheControl` option docs, including the notFound fallback keeping max-age=0 and the public-by-construction note. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to cover the new caching features introduced in version 5.2.0. Specifically, it documents the new cacheControl argument for database tables, the tiered Cache-Control policy for REST responses, CORS-related Vary: Origin headers, and new cache configuration options (maxAge, immutable, cacheControl) for static files. Feedback was provided to format the <VersionBadge> component on its own line in the HTTP configuration documentation for consistency.
|
|
||
| Comma-separated list of headers allowed in the [`Access-Control-Allow-Headers`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) response header for OPTIONS (preflight) requests. | ||
|
|
||
| <VersionBadge version="v5.2.0" /> When CORS is enabled, Harper emits `Vary: Origin` on all responses (including no-origin requests whose `Access-Control-Allow-Origin`-less variant is also origin-dependent), so that shared caches key responses correctly by origin. |
There was a problem hiding this comment.
For consistency with other documentation pages in this repository, the <VersionBadge> component should be placed on its own line with surrounding blank lines rather than inline with the text.
| <VersionBadge version="v5.2.0" /> When CORS is enabled, Harper emits `Vary: Origin` on all responses (including no-origin requests whose `Access-Control-Allow-Origin`-less variant is also origin-dependent), so that shared caches key responses correctly by origin. | |
| <VersionBadge version="v5.2.0" /> | |
| When CORS is enabled, Harper emits `Vary: Origin` on all responses (including no-origin requests whose `Access-Control-Allow-Origin`-less variant is also origin-dependent), so that shared caches key responses correctly by origin. |
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-578 This preview will update automatically when you push new commits. |
- Add the cacheOverrides per-file override map (glob -> partial cache options, first-match-wins, basename+URL matching) as a follow-up to the top-level maxAge/immutable/cacheControl options. - Note the full set of maxAge duration suffixes incl. the new `y` (year) and the case-sensitive M(month)/m(minute) distinction. - Add CDN guidance for stale-while-revalidate (CloudFront/Cloudflare honor it, Azure CDN ignores it — safe to set either way). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-578 This preview will update automatically when you push new commits. |
DavidCockerill
left a comment
DavidCockerill
left a comment
There was a problem hiding this comment.
Approving. No findings.
Verified the scope claim against the code. Table.ts:586-587 carries the matching comment — "default Cache-Control for anonymous REST reads (from @table(cacheControl: "..."))" — so the page's "anonymous (unauthenticated) GET/HEAD 200/304" framing matches what actually happens, and cacheControl threads through as a table-level property (databases.ts:843, :982, :1038).
Restricting emission to anonymous reads is the security-relevant half, and the page leads with it rather than burying it — a Cache-Control header on an authenticated response is how private data ends up in a shared cache. Stating that the table's content must be public and safe for shared caches as a precondition rather than a footnote is the right emphasis.
— DAIvid (Claude Opus 5)
2 participants
Summary
Documents two harper core PRs:
Pages touched
reference/database/schema.md— addedcacheControlto the@tableargument table and a#### cacheControlsubsection covering anonymous-only emission, the identity floor on authenticated responses, the explicit-opt-in requirement (anonymous readability alone never emits shared-cache headers), and thestatic cacheControlJS class-property form.reference/rest/headers.md— new Cache-Control section documenting the three-tier policy: anonymous declared headers, authenticated identity floor (private, no-cache+Vary: Authorization/Cookie), and CORSVary: Origin.reference/http/configuration.md— one-sentence addition to the CORS section notingVary: Originis now emitted on CORS-enabled responses.reference/static-files/overview.md— new Cache Headers subsection withmaxAge,immutable, andcacheControloption docs; includes the notFound-keeps-max-age-0 note and the public-by-construction rationale.Generated by Claude (Opus 4.8).