Skip to content

Mark only fingerprinted static files as immutable - #3127

Merged
david-a-wheeler merged 3 commits into
mainfrom
fingerprint-cache-headers-2
Nov 13, 2026
Merged

david-a-wheeler merged 3 commits into
mainfrom
fingerprint-cache-headers-2

Conversation

@david-a-wheeler

Copy link
Copy Markdown
Collaborator

We previously served every file in public/ with a 1-year "immutable" Cache-Control. That's correct for fingerprinted assets, whose URL changes whenever their content does. However, it is not correct for files with fixed URLs such as 404.html, 422.html, 500.html, and the Google verifier. Once cached, fixes to those can't reach browsers or the CDN.

It also hid a bug: public/favicon.ico was an empty file left over from the 2015 Rails scaffold, so anything requesting /favicon.ico directly got zero bytes, cached as immutable for a year.

To fix this and make the mistake hard to repeat:

  • public/ files now get a 1-day default (FingerprintedAssetCacheMiddleware::DEFAULT_HEADERS), shared by the production and test configs.
  • New middleware wrapping ActionDispatch::Static upgrades a response to immutable only if its URL has a Sprockets SHA-256 fingerprint. A new file can't get the long lifetime unless its URL changes with its content.
  • /favicon.ico now 301-redirects to the fingerprinted icon from app/assets/images/favicon.ico. The redirect is cached for 1 day, the icon for a year. We removed the empty public/favicon.ico.
  • StaticPagesController lists its locale-free actions once.

Tests cover the fingerprint pattern (including near misses), the middleware, real static responses, and the favicon redirect.

After deploying, purge Fastly; it's caching the empty /favicon.ico and the error pages with a 1-year lifetime.

Assisted-by: Claude:claude-opus-5-5

We previously served every file in public/ with a 1-year "immutable"
Cache-Control. That's correct for fingerprinted assets, whose URL changes
whenever their content does. However, it is *not* correct
for files with fixed URLs such as 404.html, 422.html, 500.html, and the
Google verifier. Once cached, fixes to those can't reach browsers or
the CDN.

It also hid a bug: public/favicon.ico was an empty file left over from
the 2015 Rails scaffold, so anything requesting /favicon.ico directly
got zero bytes, cached as immutable for a year.

To fix this and make the mistake hard to repeat:

* public/ files now get a 1-day default
  (FingerprintedAssetCacheMiddleware::DEFAULT_HEADERS), shared by the
  production and test configs.
* New middleware wrapping ActionDispatch::Static upgrades a response to
  immutable only if its URL has a Sprockets SHA-256 fingerprint. A new
  file can't get the long lifetime unless its URL changes with its
  content.
* /favicon.ico now 301-redirects to the fingerprinted icon from
  app/assets/images/favicon.ico. The redirect is cached for 1 day,
  the icon for a year. We removed the empty public/favicon.ico.
* StaticPagesController lists its locale-free actions once.

Tests cover the fingerprint pattern (including near misses), the
middleware, real static responses, and the favicon redirect.

After deploying, purge Fastly; it's caching the empty /favicon.ico and
the error pages with a 1-year lifetime.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
CI failed the test
CdnCachingTest#test_static_files_are_immutable_only_when_fingerprinted:
the fingerprinted favicon got Sprockets'
"public, max-age=31536000, immutable" instead of our IMMUTABLE value.

CI runs the tests without precompiled assets, so Sprockets' server,
mounted at /assets, serves them. That mount strips "/assets" from
env['PATH_INFO'], and FingerprintedAssetCacheMiddleware read
PATH_INFO *after* calling the app, so the path no longer matched the
fingerprint pattern. Locally the test passed only because
public/assets existed, so ActionDispatch::Static served the file
without touching PATH_INFO.

We now check the path before calling the app. A new unit test uses an
app that rewrites PATH_INFO, so this fails regardless of whether
assets are precompiled. I also ran the full suite both with and
without public/assets. That should prevent future similar problems.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Add comments to clarify when we use *Rack* env vs.
*process* env. We're using standard conventions, but those
standard conventions can be a little confusing; better to
make it clear what we're doing.

Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8f1e60d) to head (0bcd0b8).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff            @@
##              main     #3127   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           89        90    +1     
  Lines         4797      4817   +20     
=========================================
+ Hits          4797      4817   +20     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@david-a-wheeler
david-a-wheeler merged commit 8c90526 into main Nov 13, 2026
14 checks passed
@david-a-wheeler
david-a-wheeler deleted the fingerprint-cache-headers-2 branch November 13, 2026 18:41
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.

1 participant