Opt-out caching for endpoints unlikely to be revisited

[Sootopolis]

Context

ChessComClient.getCacheable (and therefore get, which is a thin wrapper) unconditionally persists every 200 response to api_response_cache + api_response_body. For endpoints that are fetched once and never revisited, this is pure storage cost with no payoff.

Motivating example

Ancient finished matches from a sequential ID scan would each get a cache row. At ~1.93M match IDs and most of them cold, the cache bloat would be substantial and unrecoverable.

Options

• Explicit opt-out parameter on the client API — e.g. getCacheable[T](url, cache = false).
• URL-pattern opt-out list — configured regex/prefixes that skip the cache write.
• Automatic decision based on Cache-Control: max-age — Chess.com's values are binary 5s / 3600s. Only caching max-age >= 3600 would skip ephemeral payloads; could over-skip for one-shot contexts that also return 3600s.

Related

• ApiResponseCache.deleteBefore cleanup runs on startup; that's reactive. This is about preventing unneeded writes in the first place.
• Related to Classify Chess.com 404 bodies: split transient backend errors from permanent not-found #3 (404 body classification) insofar as both touch cache / persistence policy.

[Sootopolis]

Related: should failed requests create cache entries?

Current behaviour (verified 2026-04-18): no. Only the success path in handleSuccessBody writes to api_response_cache. Failures go to api_fetch_failure only; the body dedupes through api_response_body but there's no cache-key row for the URL, so conditional-GET revalidation never fires against a cached failure.

Considered and rejected as a feature:

• Permanent 404s ("X not found") are already cached at a higher semantic layer — ClubRefSkip / PlayerRefSkip / match skip lists make us not re-request. Adding an HTTP-level negative cache would be redundant with that.
• Transient failures (backend-error 404s per Classify Chess.com 404 bodies: split transient backend errors from permanent not-found #3, 5xx, connection errors, CF challenges) — we actively want to retry these. Caching would be incorrect.
• RFC heuristics — Chess.com's 404 responses almost certainly don't set Cache-Control, so any standards-aligned negative cache would mostly end up not caching.
• Within-run dedup across sibling code paths is arguably a weak pro, but HistoryProcessing already handles it via an in-memory matchCache — no DB layer needed.

Noted here because it sits squarely in the same design area as opt-out caching — if the scope of this issue grows to "rethink what we cache and why," the negative-cache question should be revisited alongside.

[Sootopolis]

Update: 404s carry cache-control: public, max-age=30

Header inspection on 2026-04-18 shows Chess.com explicitly sets cache-control: public, max-age=30 on 404 responses (verified on match / tournament / player 404s). Chess.com wants 404s cached for 30 seconds.

The earlier rejection of negative caching was based on DB-level / permanent caching — skip tables handle that fine. But a very short-lived in-memory negative cache (30s TTL, honouring the server's own max-age) is a different proposition: it could reduce thrashing within a run at basically zero cost, and doesn't conflict with skip tables (which are the long-term record).

Not urgent, but worth keeping on the menu when #3 lands and we've made peace with the classification approach.

[Sootopolis]

Closing — core ask delivered.

Mechanism (d53bd9e): ChessComClient.getUncached[T] skips both api_response_cache upserts and the 304 touch path. cacheWrites threads through getCacheableImpl → gatedRawGet → rawGet → handleResponse → handleSuccessBody / handleNotModified. Read path unchanged — cache hits from other callers still served.

Adopted at 4 volatile-body call sites in RecruitmentFilterDefs:

• /pub/player/{u}/games/current
• /pub/player/{u}/stats
• /pub/player/{u}/games/{y}/{m} (90-day archive fan-out)
• /pub/player/{u}/matches

These were generating orphan cache rows that retention had to sweep — PlayerRecruitmentCache already gates re-fetch rate at a higher layer.

Three options from issue:

• Explicit opt-out parameter ✓ (delivered as separate method, cleaner than cache: Boolean arg).
• URL-pattern opt-out list — not pursued, redundant with explicit method.
• Automatic max-age decision — not pursued, would over-skip Finished-match (3600s) endpoints that are profitable to cache.

Motivating sequential-scan case (#10): getUncached is ready when the scan lands.

Spinoff: the in-memory 30s negative cache for 404s (per the second comment) is filed as a follow-up issue.