Design TS dynamic response caching for origin templates and RSC/API

[ChristianPavilonis]

Summary

Design TS-owned dynamic response caching for origin HTML templates, transformed templates, and optional RSC/API responses.

The initial cache-header work focuses on TS-owned/static/fingerprinted assets. Dynamic HTML/RSC/API caching is intentionally deferred because it requires cache-key design, cookie/header normalization, purge semantics, and runtime cache API support.

Problem

SSAT-assembled HTML is private and must not be shared-cached, but there are upstream objects that may be shareable:

• the un-injected origin HTML template;
• a transformed, auction-independent HTML template;
• selected JSON/RSC/API responses with bounded cache keys.

Today there is no explicit origin-template cache layer, no purgeable surrogate-key model, and no generic dynamic cache-key policy. Publisher origin requests may forward cookies/headers that make readthrough caching ineffective or unsafe.

Proposed scope

Design and implement dynamic caching as a separate feature/epic:

• Origin-template cache for eligible HTML routes.
• Safe cookie/header stripping and bypass rules.
• Generic configurable cache-key rules for dynamic response families.
• Request collapsing and TTL/SWR policy.
• Surrogate-Key emission and purge hooks.
• Optional transformed, auction-independent HTML template cache.
• Optional dynamic RSC/API caching after cardinality/body-impact measurement.
• Optional framework presets, but no hard-coded Next.js router-header behavior.

Design questions

• Which HTML routes are eligible for template caching?
• Which cookies/headers are payload-affecting and must bypass or vary the cache?
• What is the cache key format for host/path/query/variant dimensions?
• How are personalized, logged-in, preview, paywall, consent, geo, and experiment variants handled?
• How are cached templates invalidated when CMS content changes?
• Which runtimes need cache API support vs fallback behavior?

Suggested phased plan

Phase 1: design and safety model

• Define cache key and bypass policy.
• Define cookie/header allowlist and denylist behavior.
• Define Surrogate-Key format and purge hooks.
• Decide runtime API abstractions.

Phase 2: origin-template cache

• Implement eligible HTML template caching with request collapsing and TTL/SWR.
• Keep SSAT assembled output private, max-age=0.
• Add tests for personalization safety.

Phase 3: transformed-template cache

• Cache auction-independent rewritten/head-injected HTML.
• Late-bind only per-user bid/slot data.
• Measure rewrite CPU savings.

Phase 4: optional RSC/API dynamic caching

• Measure Vary/header cardinality and body impact.
• Add generic configurable cache-key rules.
• Add framework presets only where proven safe.

Acceptance criteria

• Design document covers cache key, bypass rules, cookie/header policy, purge, runtime support, and privacy invariants.
• Personalized SSAT-assembled HTML remains private and never enters shared cache.
• Origin-template cache only stores responses proven safe by route/policy.
• Template cache emits purgeable keys and has a CMS purge strategy.
• Dynamic Vary/cache-key normalization is generic/configurable, not hard-coded for Next.js.
• RSC/API caching, if implemented, is gated by cardinality/body-impact measurement.
• Tests cover logged-in/preview/paywall/personalized bypass cases.

Out of scope

• Initial TSJS/static cache-header work.
• SSAT compression offload.
• Parser-safe streaming implementation.
• Akamai support until it is on the roadmap.

Reference

See docs/superpowers/specs/2026-07-06-cache-control-header-design.md for the scope split and deferred dynamic caching notes.