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/