The publisher's assets held through the loading cache

[jwrosewell]

Summary

• The publisher's assets held through the loading cache.
• Row 34 of the stack in Pluggable, competition-neutral modules with a technical permission model #777, on feature/33-geo-call. Mirrors the fork's pull request The publisher's assets held through the loading cache jwrosewell/trusted-server#29, where it was reviewed.

Changes

Area	Change
crates/trusted-server-core/src	10 files, 2440 lines added, 55 removed
docs/guide	1 file, 19 lines added, 0 removed
CHANGELOG.md	1 file, 1 line added, 0 removed
crates/trusted-server-adapter-axum/tests	1 file, 1 line added, 1 removed

Closes

Closes #1324

Test plan

CI: 19 of 19 checks green, the fork's CI on f6e598f (jwrosewell#29).

• cargo test-fastly && cargo test-axum
• cargo clippy-fastly && cargo clippy-axum
• cargo fmt --all -- --check
• JS tests: cd crates/trusted-server-js/lib && npx vitest run
• JS format: cd crates/trusted-server-js/lib && npm run format
• Docs format: cd docs && npm run format
• WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
• Manual testing via fastly compute serve
• Other: the full workflow set of this repository, run on the pull request named above

Checklist

• Changes follow AGENTS.md conventions
• No unwrap() in production code (clippy denies unwrap_used in CI)
• Uses log macros as AGENTS.md asks (not println!)
• New code has tests
• No secrets or credentials committed

---

On top of the geo module called with the request (#28). Issue: #1324.

What this adds

What changes.

Every response the publisher's origin sends that is not a page, and every answer of an asset route under [[proxy.asset_routes]], is held through the loading cache (#19), so an asset is fetched once however many readers and instances ask for it at the same moment, and the copy in the host's shared store answers every instance until the origin's own lifetime ends.

[cache.assets]
module = "51degrees"
memory_seconds = 5
store_seconds = 3600

A deployment that names no module in [cache.assets] takes the one loading cache module the build links, as [cache.robots-txt] does, and a build that links none holds nothing and fetches every asset from the origin, which is what happens today.

How it works.

pub mod source_cache;   // records of what an address varies on, and the copies under each request's values
pub mod asset_cache;    // what a kept asset holds, and the address it is held under
pub const ASSETS_CACHE: &str = "assets";
pub const ASSETS_VARY_CACHE: &str = "assets-vary";

• A copy is kept under what the origin says it varies on. The first response for an address records the request headers its Vary names, and that record is held in the loading cache like any other value. A later request for the address reads the record and is served the copy kept under its own values for those headers, as RFC 9111 section 4.1 describes. Requests for an address no record covers share one load.
• Two caches, one table. The records and the copies are two caches, assets-vary and assets, so the loading cache module keeps a memory layer for each, and both are selected by the one [cache.assets] table. Core declares both as its own, beside robots-txt, so a module cannot declare either.
• The asset routes hold their answers the same way. The route handler looks for a copy before it asks the route's origin and keeps the answer by the same rules, under a key that carries the route's origin and prefix, so two routes to one address keep their own copies. An answer the platform's image optimizer makes is not kept, because the platform holds it.
• What is never kept, whatever the settings say: anything but a GET, anything but a 200, HTML (a page is a template or nothing), a response carrying Set-Cookie, a response whose cache policy says private, no-store or no-cache or gives no lifetime, a response that varies on * or on Cookie, a response larger than a copy holds (1 MiB), and the answer to a request carrying Authorization, a conditional header, a range, or a Cache-Control that asks for the origin (no-cache, no-store, min-fresh or a nonzero max-age).
• A response that may not be shared is handed back to the request whose load fetched it, so that request is served from one fetch, not two, and the requests that follow fetch their own for a minute rather than wait on a load.
• A copy is served as the origin's response would be, with the headers that describe the bytes, an Age that counts from the origin's, and the fetch and serve entries of the configuration run on it as they run on a fetched response.
• Each publisher's copies are its own. Every key starts with the publisher's prefix, so two publishers sharing a store never share a copy.

Why

A deployment with the platform's cache in front of it already has its assets held there. A deployment with nothing in front of it, and one whose fetch phase rewrites an asset before a reader sees it, fetches every asset on every page from the publisher's origin every time, and every instance does. The loading cache was declared so that each feature that holds answers selects the cache that holds them, and assets are the feature it was declared for after robots.txt.

What breaks

Nothing for a deployment that names no [cache.assets] table in a build that links no loading cache module. A deployment whose build links one starts holding shareable assets for the lifetime the origin gives them, so a change at the origin shows after that lifetime, as it does behind any shared cache.

The commits

Commit	What it does
7031828	The source cache and the asset cache, in core, selected by [cache.assets]
4e0bb71	The publisher path holds the origin's assets through the loading cache
87a55aa	An asset route's answer is held the same way, and the guide documents the table
6d587fd	The merges of the chain below
f6e598f	Review fixes: a dropped response is handed back, the asset route honours the request's Cache-Control, shared test and hashing helpers

CI being read on f6e598f.

What is not in this pull request

• A body the fetch phase rewrites is kept as the origin sent it, and the fetch phase runs on each reader's copy. Keeping the rewritten body once, as the sibling deployment did, is a later commit.
• The publisher's declared rule for inputs the origin varies on without saying so ([publisher.origin_personalization]), which separates copies the origin's own Vary does not. Later, with its tests.
• The /proxy first-party route, which rehosts third party assets named in a page. It streams, and on Fastly the platform's cache holds it.
• Pages stay on the template cache, as Remove hard coded Fastly service id #19 said.