A module declares the caches it loads through

[jwrosewell]

Summary

• A module declares the caches it loads through.
• Row 32 of the stack in Pluggable, competition-neutral modules with a technical permission model #777, on feature/31-caching-release. Mirrors the fork's pull request A module declares the caches it loads through jwrosewell/trusted-server#27. James Rogers reviewed and approved it on the fork's pull request A module declares the caches it loads through jwrosewell/trusted-server#27, closed now that the review continues here.

Changes

Area	Change
crates/trusted-server-core/src	4 files, 298 lines added, 10 removed
crates/trusted-server-adapter-axum/tests	1 file, 92 lines added, 0 removed
crates/testing/seam-probe	2 files, 64 lines added, 0 removed
docs/guide	1 file, 11 lines added, 0 removed
CHANGELOG.md	1 file, 1 line added, 0 removed
Cargo.lock	1 file, 1 line added, 0 removed

Closes

Closes #1320

Test plan

CI: 19 of 19 checks green, the fork's CI on 169d709 (jwrosewell#27).

• 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 fork's fiftyone-caching pin at the released 4.5.8 (#26). Issue: #1320.

What this adds

A module declares the caches it loads through, by name, on its builder, IntegrationBuilder::with_cache_features(&["example-answers"]). Core reads a [cache.<name>] table for each declared name as it reads its own [cache.robots-txt], and refuses a table whose name no linked module declares, naming the ones it could be, both in ts config validate and when the service starts. A name is the module's own: a builder declaring core's robots-txt, or a name another builder declares, is refused when the caches are resolved, so two vendors never share one cache and its keys without a word. LoadingCaches keys its selections by name rather than by a fixed list, and CacheSettings::loading_caches returns core's own table first and the declared ones after it, in name order. A declared cache with no table, like a table naming no module (#19), takes the one loading cache module the build links, so a stock build holds a module's answers without a line in the document, and keeps nothing when the build links none or several.

[cache.example-answers]
module = "51degrees"

The seam probe declares seam-probe-answers and offers a loading cache of its own, and the Axum adapter's seam tests prove from outside core that the table selects it, that a declared cache with no table takes the one module linked, and that a misspelt table is refused by the deploy check with the message startup gives.

Why

A module that holds its own answers, one service answer that every page of a deployment asks for, asked core for the cache of the name it chose, found no table for it, and got the cache that holds nothing, so every request loaded the answer again. Measured on one deployment at six service calls per page request where one is needed, with a loading cache linked and nothing in the document able to say the module's cache existed, because core read a fixed list of names.

What breaks

Nothing in a deployment's documents. CacheSettings no longer rejects an unknown [cache.<name>] table when the document is parsed. ts config validate refuses it instead, as the service does when it starts, if no linked module declares the name.

The commits

Commit	What it does
d37d283	A module declares the caches it loads through
7d0f70e	The chain below merged in, carrying the loading cache default
d9656fd	A declared cache with no table takes the one loading cache module the build links
1133273	Review: the deploy check refuses what the cache build refuses, a duplicate or robots-txt declaration is refused, the seam probe declares and offers a cache, and the guide names a fictional module

CI passed on d9656fd, 19 of 19, and runs on 1133273.

What is not in this pull request

• A way to hold nothing in a build that links one loading cache module. A table names a module that offers a cache, and one naming anything else, none included, is refused when the service starts.