Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 31 additions & 19 deletions docs/cdn-cache-not-logged-in.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
56 changes: 55 additions & 1 deletion docs/implementation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
9 changes: 4 additions & 5 deletions docs/warning_failures.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion lib/tasks/default.rake
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down
Loading