feat: purge the CDN when the registry evicts its own caches

[netomi]

Second step towards #1889. Stacked on #2214 — review that first; this PR's diff against it is the purge machinery alone.

What sends the purge

CacheService already knows every point at which a cached answer stopped being true: a version published, an extension deprecated or deleted, a namespace changed, a review posted. A CDN is one more cache, so the purge goes out from there, in the terms the responses are already tagged with (ext/<namespace>/<extension>, ns/<namespace>).

Two things CdnPurgeService takes care of

After the commit, never inside it. Those eviction points run inside @Transactional methods. A purge sent there races the commit: the CDN refetches, gets the row as it was, and caches that — leaving it staler than if nothing had been purged at all. The keys are collected on the transaction and sent from afterCompletion, and a transaction that rolled back purges nothing, because whatever it was going to change did not happen.

One purge per transaction. Publishing a version evicts the extension JSONs, the latest version and the namespace details separately — three calls naming two keys. They are collected into a set and sent once.

Delivery

The purge is a JobRunr job, following the pattern already used for mail and migrations:

• a CDN that is briefly unreachable is retried rather than losing the purge;
• a slow purge API never holds up a publish;
• a purge that fails for good is counted (openvsx_cdn_purge_failed_keys_total), because it is invisible from the outside — the registry answers correctly while the CDN keeps serving what it had, and the only symptom is a reader seeing an old version until the cached response expires.

Fastly's bulk purge takes at most 256 keys, so larger sets are split. Soft purge is on by default: it marks the cached responses stale instead of dropping them, so the CDN keeps serving while it refetches and publishing a popular extension does not send everyone asking for it to the origin at once.

Configuration

Everything is off unless a provider is named, so a registry with no CDN in front of it does no extra work and needs no configuration. A half-configured provider is treated as no provider rather than as a startup failure — the registry serves fine without purging, and failing to boot over a CDN credential would be a poor trade.

property	default
ovsx.cdn.purge.provider	(empty — purges nothing)
ovsx.cdn.purge.fastly.service-id
ovsx.cdn.purge.fastly.api-token	(needs the purge_select scope)
ovsx.cdn.purge.fastly.soft	true
ovsx.cdn.purge.fastly.api-url	https://api.fastly.com

All five documented in doc/configuration.md, under a new CDN Cache Purging section.

Testing

• CdnPurgeServiceTest — one purge for everything a transaction changed, nothing before the commit, nothing at all for a rollback, straight through outside a transaction, nothing without a configured provider, and no leakage of one transaction's keys into the next.
• FastlyCdnPurgeClientTest — the request Fastly actually receives (URL, Fastly-Key, Fastly-Soft-Purge, body), soft purge off, batching past 256 keys, and a failure surfacing rather than being swallowed.
• CdnPurgeJobRequestHandlerTest — counters on success and failure, the rethrow that lets JobRunr retry, and the case where the provider was unconfigured between a job being enqueued and it running.

Full server suite green (1443 tests); pre-commit hooks pass, including the configuration-documentation check.

Next

The TTLs this makes safe to raise — Surrogate-Control for the CDN kept separate from the short Cache-Control browsers get, since a browser cache cannot be purged. Files stay out of it: they are served by redirect to storage, so their cached response carries no key and is not purgeable yet.

🤖 Generated with Claude Code