From b65c459f3d21e9706b000c8d35eccdee0e1baa80 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 13 Nov 2026 13:59:24 -0500 Subject: [PATCH] Summarize CDN caching; record decision against purge callback docs/implementation.md now has a short "CDN caching" section: what the CDN caches (badges and JSON, anonymous project pages, "unchanging" pages), the kill switches, how we purge, and how static files are cached (immutable only for fingerprinted URLs). It points to cdn-cache-not-logged-in.md for the design details. Section 11 of cdn-cache-not-logged-in.md read as pending future work, but we've decided not to purge from a model callback: the callback wouldn't fire for the callback-skipping writes it was meant to catch, and those writes change only BOOKKEEPING_FIELDS, which no cached page shows. Section 11 now leads with that decision; the original analysis stays below it. We updated the references to it. Also fix the documented purge command: the task is fastly:purge_all, not fastly:purge. Assisted-by: Claude:claude-opus-5-5 --- docs/cdn-cache-not-logged-in.md | 50 ++++++++++++++++++----------- docs/implementation.md | 56 ++++++++++++++++++++++++++++++++- docs/warning_failures.md | 9 +++--- lib/tasks/default.rake | 2 +- 4 files changed, 91 insertions(+), 26 deletions(-) diff --git a/docs/cdn-cache-not-logged-in.md b/docs/cdn-cache-not-logged-in.md index 2694697a3..ce969710f 100644 --- a/docs/cdn-cache-not-logged-in.md +++ b/docs/cdn-cache-not-logged-in.md @@ -16,9 +16,11 @@ session cookie) on anonymous read-only pages that do not need one. > **Status, as of 2026-08-03.** Sections 1 to 10 are **implemented and in > production** (#2858, #2859, #2860, #2862). Read them as a record of the > design and the reasoning behind it, not as a plan: several are written -> in the future tense from when they were proposals. Only -> [section 11](#11-potential-future-work-purge-the-cdn-from-a-model-callback) -> remains unimplemented, and it is the only part where a new note belongs. +> in the future tense from when they were proposals. +> [Section 11](#11-considered-and-rejected-purge-the-cdn-from-a-model-callback) +> records a design we considered and decided *not* to build. +> For a short summary of current caching behavior, see +> [implementation.md](implementation.md#cdn-caching). > > Sections 7 and 8, the rollout order and the staging verification steps, > describe a rollout that has already happened; they are kept because the @@ -1012,9 +1014,9 @@ that exact key. *other* path that changes a displayed project field via `save` / `update_column` without purging would leave the cached show page stale until `Surrogate-Control`'s `max-age` expires (10 days). No such path is known - today, but the safety net is fragile. Moving the purge into an `after_commit` - model callback would make purging robust against *any* write path; the design, - with its pros and cons, is in **Section 11**. + today. We considered moving the purge into an `after_commit` model + callback to cover *any* write path, and decided against it; + **Section 11** explains why. ### 9.4 Page variance between users @@ -1326,20 +1328,30 @@ instantly. --- -## 11. Potential future work: purge the CDN from a model callback +## 11. Considered and rejected: purge the CDN from a model callback -> **Status: not implemented; a proposal.** Today CDN purging is triggered -> explicitly from the controller `update`/`destroy` actions and from the bulk -> recalculation (`Project.update_all_badge_percentages`). This section records -> the design for making purging a model-level `after_commit` callback — a more -> robust "single source of truth" — together with its pros, cons, and the -> pitfalls that make a *naive* callback worse than the status quo. It is written -> down so the decision can be made deliberately later; it is **not** required -> for the project-show caching to be correct as shipped. - -**Read [11.0](#110-two-objections-raised-2026-08-03) before implementing -this.** Two objections were raised against the design below after it was -written, and one of them undercuts its main claim. +> **Decision: we will not do this.** We purge the CDN explicitly where +> visible data changes: the controller `update`/`destroy` actions and the +> bulk recalculation (`Project.update_all_badge_percentages`). This section +> records the alternative we considered, a model-level `after_commit` +> callback, and why we rejected it. In short (details in +> [11.0](#110-two-objections-raised-2026-08-03)): +> +> * **It wouldn't catch the writes it was meant to catch.** Today's +> non-controller writes deliberately skip callbacks (`update_columns`, +> `update_column`, parameterized SQL), so the callback would mostly fire +> on paths that already purge. That looks like coverage but isn't. +> * **Those writes don't need a purge anyway.** They change only +> `Project::BOOKKEEPING_FIELDS`, which no cached page shows, so nothing +> can go stale. The question to ask of a write isn't "does it purge?" +> but "does it change anything a reader can see?" +> +> We accept one gap that a `Project` callback wouldn't close either: if an +> owner changes their display name, cached project pages show the old name +> until the next project edit or cache expiry (see 11.4). +> +> The rest of this section is the original proposal and analysis, kept so +> you can see the reasoning if the question comes up again. ### 11.0 Two objections raised 2026-08-03 diff --git a/docs/implementation.md b/docs/implementation.md index a05d63f0e..50e9e8514 100644 --- a/docs/implementation.md +++ b/docs/implementation.md @@ -957,6 +957,60 @@ ActiveSupport::Cache should probably be changed, e.g., to MemCached or Redis. Otherwise the caches won't be shared between the instances. +## CDN caching + +We use the Fastly CDN so that it, or the requester, can answer most +requests without reaching our application. In summary: + +* **Badge images and project JSON** are cached by the CDN for up to + 10 days (`BADGE_CACHE_MAX_AGE`), tagged with surrogate keys such as + the project's `projects/ID` so we can purge them selectively. +* **Project pages for anonymous users** are cached too. The presence of + the session cookie (`_BadgeApp_session`) is the "don't cache" signal, + so we avoid setting it for anonymous read-only pages (e.g., we omit the + CSRF token there). Kill switch: `BADGEAPP_CACHE_SHOW_PROJECT=false`. +* **"Unchanging" pages** (home, cookies, and criteria pages), whose + output changes only on deploy, share the surrogate key `unchanging`, + which `config/puma.rb` purges after each boot. Kill switch: + `BADGEAPP_CACHE_UNCHANGING=false`. +* **Purging is explicit.** Project `update`/`destroy` and the bulk badge + recalculation purge the affected project's key, then purge again after + a short delay (`PurgeCdnProjectJob`) to catch a stale copy + re-cached during a rolling deploy. Writes that change only + `Project::BOOKKEEPING_FIELDS` don't purge, since no cached page shows + those columns. + +The design, its safety arguments, and the staging verification steps +(`script/verify_cdn_caching.sh`) are in +[cdn-cache-not-logged-in.md](cdn-cache-not-logged-in.md). Its +section 11 explains why we decided *not* to purge from a model callback. + +### Caching static files + +Files we serve from `public/` get one of two cache lifetimes: + +* A URL that includes a fingerprint (a SHA-256 hash derived from the + file's content), such as `/assets/favicon-f098...588f.ico`, is + cached as `immutable` for a year. That's safe because any content + change produces a new URL. Sprockets generates these URLs for + everything under `/assets/`. +* Everything else, such as `/404.html`, gets a 1-day lifetime, since + its content can change while its URL stays the same. + +`FingerprintedAssetCacheMiddleware` +(`lib/fingerprinted_asset_cache_middleware.rb`) enforces this: +`config.public_file_server.headers` sets the short default, and the +middleware upgrades a response to `immutable` only if its URL is +fingerprinted. So a file you add to `public/` gets the short lifetime +automatically. Never put `immutable` in `public_file_server.headers`; +it would apply to every file in `public/`, and caches couldn't pick up +later changes to unfingerprinted files for up to a year. + +If you want a file cached longer, serve it through the asset pipeline +so its URL is fingerprinted. For example, `/favicon.ico` is a 1-day +redirect to the fingerprinted icon, because browsers and bots request +that fixed URL directly. + ## Purging Fastly CDN cache If a change in the application causes any badge level(s) to change or @@ -969,7 +1023,7 @@ You can purge the Fastly CDN cache this way (assuming you're allowed to log in to the relevant Heroku app): ~~~~sh -script/heroku_run HEROKU_APP_HERE rake fastly:purge +script/heroku_run HEROKU_APP_HERE rake fastly:purge_all ~~~~ This command will use the value of the FASTLY_API_KEY diff --git a/docs/warning_failures.md b/docs/warning_failures.md index 684763c29..f2e1bc6d8 100644 --- a/docs/warning_failures.md +++ b/docs/warning_failures.md @@ -1823,11 +1823,10 @@ lately" belongs on the list. A model test asserts every name in it is a real column, since a typo would silently publish the field it was meant to withhold. -It is also the seed for -[section 11](cdn-cache-not-logged-in.md#11-potential-future-work-purge-the-cdn-from-a-model-callback) of the CDN document: -these are exactly the columns whose change cannot make any cached page -stale, so a future purge callback can skip a write that touched only -them. +These are also exactly the columns whose change cannot make any cached +page stale, so a write that touches only them needs no CDN purge. That's +part of why we decided against a purge callback; see +[section 11](cdn-cache-not-logged-in.md#11-considered-and-rejected-purge-the-cdn-from-a-model-callback) of the CDN document. ### Separable, any time diff --git a/lib/tasks/default.rake b/lib/tasks/default.rake index 979f2801e..d8b2b5dfa 100644 --- a/lib/tasks/default.rake +++ b/lib/tasks/default.rake @@ -1067,7 +1067,7 @@ end # Tasks for Fastly including purging and testing the cache. namespace :fastly do # Implement purge_all (full purge) of Fastly CDN cache. Invoke using: - # script/heroku_run HEROKU_APP_HERE rake fastly:purge + # script/heroku_run HEROKU_APP_HERE rake fastly:purge_all # Run this if code changes will cause a change in badge level, since otherwise # the old badge levels will keep being displayed until the cache times out. # See: https://robots.thoughtbot.com/