fix(cache): one versioned cache model with ETags and stored gzip

[jplacht]

Summary

Replaces the five cache invalidation schemes with a single versioned-namespace model, and makes HTTP caching honest.

• One mechanism. CacheManager.respond(request, NS, endpoint, *parts, build=…, scope=…) stores rendered responses under {ns}[:{scope}]:v{version}:{endpoint}:{digest}. To invalidate, CacheManager.invalidate(NS, scope) bumps a version counter that has no TTL. delete_pattern/SCAN is gone.
• Correctness fixes:
  • Planet retrieve and planets/multiple no longer collide, because the endpoint name is in the key.
  • Search terms no longer collide.
  • CX webhook updates now invalidate the exchange list; before, it could stay stale for up to a day.
  • Request input is hashed, never put in a key raw.
• HTTP caching:
  • Every response gets an ETag, and If-None-Match gets a 304.
  • Public responses send public, max-age=60; they used to send up to 86400. Private responses send private, no-cache.
  • A response that sets no Cache-Control defaults to private, no-cache.
• Efficiency: entries are gzipped once at build time (level 9) and sent as is to gzip clients.
• Dropped caches: planets/multiple, planets/search, planets/<term> and planet_insights are no longer cached. They were cheap cold and had low hit rates.
• Observability: cache_ns and cache_hit are added to the request_finished log line. The dashboard label now reads "Keyspace hit rate (all Redis)".

Spec: specs/2026-09-27-cache-structure.md (workspace repo).

Response bodies and the OpenAPI schema are unchanged; the schema is byte-identical to main. Only headers change, so this is backward compatible.

Deploy order

Deploy this PR first. The paired frontend PR PRUNplanner/frontend#505 must only ship once this is live.

After deploy (optional):

• Remove the orphaned old counters: redis-cli --scan --pattern ':1:PLANNING:*:version' | xargs redis-cli del
• Compare used_memory against the ~50 MB baseline.

Old cache keys expire within their TTL (at most 1 d), so no flush is needed.

Perf

Run with perf/run.sh --mode quick at small scale, both sides using a gzip-accepting bench client.

Memory (MEMORY USAGE in Redis):

entry	main	this PR	smaller by
planets list	6,291,528 B	786,528 B	8.0x
exchanges	786,504 B	131,168 B	6.0x

Warm latency (median, main → this PR):

endpoint	main	this PR
planets	81 ms	7.6 ms
exchanges	15.5 ms	2.3 ms
materials	2.5 ms	1.6 ms
recipes	2.9 ms	1.7 ms
planning	equal	equal
data.planet	1.13 ms	1.60 ms

data.planet is the one regression: the extra version read costs ~0.5 ms, and its 724 B body is too small for gzip to win that back.

Cold builds are slower because of gzip level 9: exchanges +13 ms, planets +235 ms.

Not changed: Redis maxmemory flags in docker-compose.yml. Production sets its own.

Test plan

• uv run ruff check, ruff format --check, ty check
• uv run pytest (316 passed). New tests:
  • a parametrized invalidation table over every namespace, including private A/B isolation;
  • the retrieve/multiple collision regression;
  • webhook json+csv refresh;
  • 304s for a cached and an uncached endpoint;
  • gzip vs plain bodies are byte-identical;
  • key length stays bounded;
  • the request log carries cache_ns/cache_hit.
• After deploy: curl exchanges twice with If-None-Match and check for a 304.

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics -53 complexity · 0 duplication

Metric	Results
Complexity	-53
Duplication	0

View in Codacy

🟢 Coverage 100.00% diff coverage · -0.01% coverage variation

Metric	Results
Coverage variation	✅ -0.01% coverage variation (-1.00%)
Diff coverage	✅ 100.00% diff coverage

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (156ba09)	3855	3623	93.98%
Head commit (5282b92)	3746 (-109)	3520 (-103)	93.97% (-0.01%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#50)	164	164	100.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}