Skip to content

fix(gateway): clarify cache-control of generated html on /ipfs and TTL on /ipns#480

Open
lidel wants to merge 6 commits into
mainfrom
fix/cache-control-of-generated-html
Open

fix(gateway): clarify cache-control of generated html on /ipfs and TTL on /ipns#480
lidel wants to merge 6 commits into
mainfrom
fix/cache-control-of-generated-html

Conversation

@lidel

@lidel lidel commented Jul 29, 2024

Copy link
Copy Markdown
Member

This PR clarifies and recommends Cache-Control value to be returned on generated HTML responses such as UnixFS Directory listings, raised by @acejam in ipfs/boxo#639 & ipfs/gateway-conformance#219.

No IPIP since this is a gap is specs surface, not a change to existing spec.

@lidel lidel changed the title fix: clarify cache-control of generated html fix(gateway): clarify cache-control of generated html Jul 29, 2024
@lidel lidel requested a review from 2color July 29, 2024 19:07
@lidel lidel force-pushed the fix/cache-control-of-generated-html branch from a9ab757 to d3cdb71 Compare July 29, 2024 19:37
@lidel lidel marked this pull request as ready for review July 29, 2024 19:44
@lidel lidel changed the title fix(gateway): clarify cache-control of generated html fix(gateway): clarify cache-control of generated html on /ipfs Jul 29, 2024
Comment thread src/http-gateways/path-gateway.md Outdated
lidel added 2 commits June 15, 2026 18:43
A fixed stale-while-revalidate window let caches reuse an IPNS record
past its Validity (EOL). After EOL the signature is expired, so
validating clients reject the record, which surfaced as sporadic 500s
in the service-worker gateway. Mirror the bound applied in
ipfs/boxo#1166: max-age plus the stale window must end before the EOL,
and an already-expired record must not be cached.

- path-gateway: keep a fixed stale window for generated /ipfs/ HTML
  (content-addressed, no EOL), but cap the mutable /ipns/ window to the
  record's remaining validity; no-store past EOL
- http-routing-v1: size the ipns record stale window as remaining
  validity minus max-age so it ends at the EOL; no-store when the
  record is expired or its ValidityType is unrecognized
@github-actions

github-actions Bot commented Jun 15, 2026

Copy link
Copy Markdown

🚀 Build Preview on IPFS ready

A directory listing reached through /ipns/ is a mutable response even
though its body is generated markup. State that it follows the /ipns/
TTL and EOL rules, not the fixed window used for generated /ipfs/
responses, so a cache cannot serve it past the record's EOL.
@lidel lidel changed the title fix(gateway): clarify cache-control of generated html on /ipfs fix(gateway): clarify cache-control of generated html on /ipfs and TTL on /ipns Jun 15, 2026
@lidel

lidel commented Jun 15, 2026

Copy link
Copy Markdown
Member Author

Pushed a couple more commits. Working through ipfs/boxo#1166 made the nuance here clearer: a fixed stale-while-revalidate can keep a cached IPNS record alive past its EOL, where the signature has already expired and clients reject it (those sporadic 500s in the service worker gateway).

So the /ipns/ guidance now says max-age plus any stale window has to stay within the record's validity, with no-store once it's expired. I also kept the fixed generated-HTML window scoped to /ipfs/, since a directory listing reached through /ipns/ should follow the IPNS TTL/EOL rules rather than the 4-week immutable one.

Same fix applied to GET /routing/v1/ipns/{name}, which overshot the same way.

@lidel lidel requested review from achingbrain and removed request for 2color June 15, 2026 17:15
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.

2 participants