Skip to content

Keep the ETags of cached pages and frames stable across renders - #382

Open
namespaceMarcello wants to merge 2 commits into
basecamp:mainfrom
namespaceMarcello:keep-page-validators-stable
Open

namespaceMarcello wants to merge 2 commits into
basecamp:mainfrom
namespaceMarcello:keep-page-validators-stable

Conversation

@namespaceMarcello

Copy link
Copy Markdown
Contributor

Summary

A browser revalidates every Campfire page it has already seen: clicking a room in the sidebar, reloading, going back, opening a room again from the address bar. Two things make many of those revalidations download the whole page or frame again instead of getting a 304:

  • The page cache tags a compressed page with a hash of its gzip bytes. A revalidation skips the page cache and renders, and Rack::ETag hashes the HTML, so the browser's tag doesn't match. Gzip output also records the time it was made, so the same HTML cached again a second later gets a different tag as well.
  • turbo-rails renders frame requests in its own minimal layout, which calls csrf_meta_tags. Forgery protection here is header-only and keeps secrets out of HTML (token_tag returns ""), but the sidebar frame carries a token masked afresh on every render, so its ETag changes every time.

This PR hashes the HTML instead of the gzip bytes, as the comment on that line already intends, and supplies the frame layout without the token.

Impact, in headless Chrome against the production image (Docker on a laptop, upstream's benchmark seed), over one session that moves between two rooms from the sidebar, reloads, goes back and opens a room again from the address bar:

  • Revalidations of room pages and of the sidebar frame that got the whole response back: 9 on main, 1 here. Answered 304: 4 on main, 12 here. The one left is the sidebar right after a room was marked read, which did change.
  • Each one saved is a transfer: 20.8 KB gzipped (415 KB of HTML) for the busiest room of the seed, 2.4 KB gzipped (10.4 KB) for the sidebar frame, which a browser fetches twice on every full page load. The server renders a revalidation as it does today.

Affects main since 0f5d0b2 and bbee420 (October 8), which brought compressed page reuse, its ETag and header-only forgery protection; no release has them.

Tested with two controller tests that fail on main and pass here, each failing again when only its own change is removed, plus the unit suite (651 tests), rubocop, herb, brakeman and the 30 system tests, all locally. Risk: compressed cached pages get a different ETag, so a browser holding an old one downloads that page once more; frame responses lose a <meta name="csrf-token"> that no check uses, since forgery protection is header-only in the app and in Active Storage. Reverting the two commits restores today's behavior.

Why the page's ETag didn't match

cache_completed_response compresses the HTML, then hashes body, which by then holds the gzip bytes. On a revalidation, cacheable_read_request? leaves the request out of the page cache because it carries If-None-Match, the page renders, Rack::ETag hashes the HTML and Rack::ConditionalGet compares that with the tag the browser sent: they differ, and the whole page goes back with the new tag. Gzip's header holds a timestamp (Zlib.gzip of the same string a second apart gives different bytes), so each time the page cache fills again it hands out a tag no render can produce.

Without Accept-Encoding the two hashes were already the same, and the test client sends none, so the existing tests didn't see it.

Why the sidebar frame's ETag changed on every render

Turbo::Frames::FrameRequest renders a request with a Turbo-Frame header in turbo_rails/frame, and that layout calls csrf_meta_tags, which masks the token with a new pad on every call. Saved from Chrome, two renders of the same sidebar differ only in that line. Campfire's application layout has no csrf_meta_tags, and with :header_only protection, in the controllers and in Active Storage, no request is checked against a token: the frame's token serves no check.

Changes

  • app/controllers/concerns/cached_responses.rb: hash the HTML rather than the compressed body, and skip the ETag when the HTML is empty, as Rack::ETag does.
  • app/views/layouts/turbo_rails/frame.html.erb: turbo-rails' frame layout without csrf_meta_tags, overridden the way the gem documents.

Checks

  • test/controllers/cached_responses_test.rb:
    • "a compressed page answers a browser's revalidation" asks for a room with gzip, checks the page came compressed from the page cache, then asks again with its If-None-Match. On main: Expected response to be a <304: not_modified>, but was a <200: OK>.
    • "a frame answers a browser's revalidation" does the same for the sidebar with a Turbo-Frame header. On main: the same failure.
    • Hashing the gzip bytes again fails only the first; removing only the layout fails only the second; keeping the page out of the page cache fails the first on its compression check.
  • The Chrome session above, on images built from main and from this branch, recording each request's If-None-Match, its status on the wire and Rails' log line for it. No new console errors (the seed's external avatar 404s on both).
  • Unit suite (651 tests), rubocop, herb, brakeman, and the 30 system tests, locally (Docker, headless Chrome).

Left as is

A revalidation still renders, because cacheable_read_request? keeps conditional requests out of the page cache. Letting them in was measured on the same Chrome session: 0 of 13 revalidations found their page cached. Moving to a room subscribes to PresenceChannel, which writes the membership, and every commit retires the cached pages. So this PR doesn't touch that line.

#350 also changes cached_responses.rb; it leaves both changed lines as they are, and the two merge without conflicts in that file.

Written by Claude Code (AI assistant) on behalf of @namespaceMarcello, who directs this work.

namespaceMarcello and others added 2 commits October 23, 2026 23:28
The page cache hashed the bytes it stores, gzip included, while a render
gets its ETag from Rack::ETag over the HTML. A browser revalidates every
page it has seen, revalidations skip the cache and render, so the first
one after a page came from the cache never matched and got the whole page
back instead of a 304. Gzip output also records when it was made, so the
same HTML cached again a second later got a different ETag as well.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
turbo-rails renders frame requests in its own minimal layout, which calls
csrf_meta_tags. Forgery protection here is header-only and keeps secrets
out of cached HTML, yet the sidebar frame carried a token masked afresh on
every render: its ETag changed each time, so a browser revalidating the
sidebar, twice on every full page load, always got the whole frame back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings October 23, 2026 21:47

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

The focused fixes match the existing caching and forgery-protection design, with regression coverage for both reported failures and no unresolved findings.

No open issues 🎉

What changed in this PR

This PR stabilizes ETags for cached pages and Turbo frames so browsers can receive 304 Not Modified responses when the HTML has not changed.

Changes:

  • Hash uncompressed HTML rather than gzip bytes when generating cached-page ETags.
  • Override the Turbo frame layout to omit CSRF tokens, consistent with the app’s header-only forgery protection.
  • Add regression tests for compressed-page and sidebar-frame revalidation.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

File Description
test/​controllers/​cached_responses_test.rb Tests successful revalidation of compressed pages and sidebar frames.
app/​views/​layouts/​turbo_rails/​frame.html.erb Removes changing CSRF tokens from frame HTML.
app/​controllers/​concerns/​cached_responses.rb Generates ETags from HTML and skips empty HTML bodies.

Review effort: Balanced

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