Let a module declare the caches it loads through

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- A module declares the caches it loads through, by name, and a deployment selects a loading cache for each in its own `[cache.<name>]` table, the way `[cache.robots-txt]` selects one for robots.txt. A `[cache.<name>]` table naming a cache no linked module declares is refused by `ts config validate` and when the deployment starts, naming the ones it does, and a module declaring `robots-txt` or a name another module declares is refused. `IntegrationBuilder::with_cache_features` declares them, `CacheSettings` has a new public field `declared`, `CacheSettings::loading_caches` returns a `Vec` in place of an array, listing core's own and the declared ones, and `LoadingCaches::insert` takes any name.
 - **Breaking for crates outside core:** the cookie constants `COOKIE_TS_EC`, `COOKIE_TS_EC_RESOLVED`, `COOKIE_TS_EC_PULL_COMPLETE`, `COOKIE_TS_EIDS` and `COOKIE_TS_TESTER` are `COOKIE_EC`, `COOKIE_EC_RESOLVED`, `COOKIE_EC_PULL_COMPLETE`, `COOKIE_EIDS` and `COOKIE_TESTER`, holding the entry's name alone, and a cookie is named through the request's public prefix with `services.public_prefix().cookie_name(COOKIE_EC)`. A module's response header naming a cookie under the public prefix is refused as one under `ts-` was.
 - A robots.txt module's answer is held by the loading cache of the one loading cache module the build links, or of the module `[cache.robots-txt] module` names, briefly in memory and in the host's shared store outside it, so a module is asked again only when no copy young enough is held, rather than by every request. With no loading cache module linked, or several and none named, nothing is held and every request for the file asks each module, as every request did when no adapter gave the file a key-value store. The last answer is kept apart for 30 days and served when the module cannot answer, in the value cache on Fastly and in the key-value store on Cloudflare and Spin, and Axum, which has no key-value store, keeps none.
 - **Breaking:** the Cloudflare and Spin adapters declare their key-value store, the Workers KV binding `TRUSTED_SERVER_KV` and Spin's `default` store, so EdgeZero opens it for every request, where every request was given a store whose every call failed, and a loading cache module that a deployment links keeps its copies there between requests. A declared store is required, so a Worker without the binding, or a Spin component that cannot open `default`, fails every request before any route runs.

crates/testing/seam-probe/Cargo.toml

@@ -12,6 +12,7 @@ workspace = true
 
 [dependencies]
 async-trait = { workspace = true }
+bytes = { workspace = true }
 edgezero-core = { workspace = true }
 error-stack = { workspace = true }
 http = { workspace = true }

crates/testing/seam-probe/src/lib.rs

@@ -702,6 +702,9 @@ impl SeamProbeProxy {
             "request_preparer_runs": prepared.map_or(0, |marker| marker.runs),
             "public_prefix": services.public_prefix().as_str(),
             "server_key_prefix": services.server_key_prefix().as_str(),
+            "answers_cache_keeps_values": services
+                .loading_cache_for(SEAM_PROBE_ANSWERS_CACHE)
+                .keeps_values(),
         })
         .to_string();
 
@@ -886,6 +889,66 @@ pub fn builder() -> IntegrationBuilder {
         .with_request_preparer(prepare_request)
         .with_demand(&SEAM_PROBE_DEMAND)
         .with_adserver(&SEAM_PROBE_ADSERVER)
+        .with_cache_features(&[SEAM_PROBE_ANSWERS_CACHE])
+}
+
+/// The cache the probe declares and loads its answers through, selected in
+/// `[cache.seam-probe-answers]`. The report route says whether the cache
+/// that table selected keeps values.
+pub const SEAM_PROBE_ANSWERS_CACHE: &str = "seam-probe-answers";
+
+/// The id of the loading cache module the probe offers, selected in a
+/// `[cache.<name>]` table as `module = "seam-probe"`.
+pub const SEAM_PROBE_LOADING_CACHE_ID: &str = "loading-cache.seam-probe";
+
+/// A loading cache that keeps every value in this process's memory for as
+/// long as the process runs, enough to prove from outside core that a table
+/// selected it.
+#[derive(Default)]
+struct MemoryLoadingCache {
+    held: Mutex<BTreeMap<String, bytes::Bytes>>,
+}
+
+#[async_trait(?Send)]
+impl trusted_server_core::platform::PlatformLoadingCache for MemoryLoadingCache {
+    async fn get_or_load(
+        &self,
+        _services: &RuntimeServices,
+        _spec: &trusted_server_core::platform::CacheSpec,
+        key: &trusted_server_core::platform::StoreKey,
+        load: trusted_server_core::platform::Loader,
+    ) -> Result<bytes::Bytes, trusted_server_core::platform::LoadError> {
+        if let Some(held) = self.held.lock().expect("lock").get(&key.to_string()) {
+            return Ok(held.clone());
+        }
+        let loaded = load().await?.bytes;
+        self.held
+            .lock()
+            .expect("lock")
+            .insert(key.to_string(), loaded.clone());
+        Ok(loaded)
+    }
+
+    async fn remove(
+        &self,
+        _services: &RuntimeServices,
+        _spec: &trusted_server_core::platform::CacheSpec,
+        key: &trusted_server_core::platform::StoreKey,
+    ) {
+        self.held.lock().expect("lock").remove(&key.to_string());
+    }
+}
+
+fn memory_loading_cache() -> Arc<dyn trusted_server_core::platform::PlatformLoadingCache> {
+    Arc::new(MemoryLoadingCache::default())
+}
+
+/// The builder offering the probe's loading cache, for a test that proves a
+/// declared cache's table selects a module from outside core.
+#[must_use]
+pub fn loading_cache_builder() -> IntegrationBuilder {
+    IntegrationBuilder::implementations(SEAM_PROBE_LOADING_CACHE_ID, SEAM_PROBE_SOURCE)
+        .with_loading_cache(memory_loading_cache)
 }
 
 /// The vendor's name, which names the table `[shared.seam-probe]` that runs

crates/trusted-server-adapter-axum/tests/seam_probe.rs

@@ -546,6 +546,123 @@ fn deploy_validation_rejects_a_violation_of_the_modules_own_rule() {
     );
 }
 
+// ---------------------------------------------------------------------------
+// 3b. A cache the probe declares is selected in its own table
+// ---------------------------------------------------------------------------
+
+/// Reads the probe's report through the router, as a page would.
+async fn report_with(settings: Settings, integrations: &[IntegrationBuilder]) -> serde_json::Value {
+    let mut service = service_with(settings, integrations);
+    let response = get(&mut service, seam_probe::SEAM_PROBE_REPORT_PATH).await;
+    assert_eq!(
+        response.status().as_u16(),
+        200,
+        "the report route should answer"
+    );
+    let body = body_text(response).await;
+    serde_json::from_str(&body).expect("the report route should return JSON")
+}
+
+/// The id of a loading cache module these tests link beside the probe's.
+const SECOND_LOADING_CACHE_ID: &str = "loading-cache.memory";
+
+/// Core's `MemoryLoadingCache`, which keeps what it loads.
+fn memory_loading_cache() -> Arc<dyn trusted_server_core::platform::PlatformLoadingCache> {
+    Arc::new(trusted_server_core::platform::test_support::MemoryLoadingCache::default())
+}
+
+/// A loading cache module other than the probe's, so a build can link two.
+fn second_loading_cache_builder() -> IntegrationBuilder {
+    IntegrationBuilder::implementations(SECOND_LOADING_CACHE_ID, env!("CARGO_PKG_NAME"))
+        .with_loading_cache(memory_loading_cache)
+}
+
+/// `[cache.seam-probe-answers]` selects the loading cache the probe's answers
+/// are held in, the way `[cache.robots-txt]` selects core's. Left out, the
+/// cache takes the one loading cache module the build links, and keeps
+/// nothing when the build links none or several. A stock build links none,
+/// so the first two cases link a second module beside the probe's, and only
+/// the one whose table is read keeps values.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn a_cache_the_probe_declares_is_selected_in_its_own_table() {
+    let named = settings_with(&format!(
+        r#"
+            [cache.seam-probe-answers]
+            module = "seam-probe"
+            {PROBE_BLOCK}
+        "#
+    ));
+    let two = [
+        seam_probe::builder(),
+        seam_probe::loading_cache_builder(),
+        second_loading_cache_builder(),
+    ];
+
+    let report = report_with(named, &two).await;
+    assert_eq!(
+        report["answers_cache_keeps_values"], true,
+        "the table should select the module it names: {report}"
+    );
+
+    let report = report_with(settings_with(PROBE_BLOCK), &two).await;
+    assert_eq!(
+        report["answers_cache_keeps_values"], false,
+        "with two loading cache modules linked and no table the cache should keep nothing: {report}"
+    );
+
+    let both = [seam_probe::builder(), seam_probe::loading_cache_builder()];
+    let report = report_with(settings_with(PROBE_BLOCK), &both).await;
+    assert_eq!(
+        report["answers_cache_keeps_values"], true,
+        "a declared cache with no table should take the one loading cache module linked: {report}"
+    );
+
+    let report = report_with(settings_with(PROBE_BLOCK), &[seam_probe::builder()]).await;
+    assert_eq!(
+        report["answers_cache_keeps_values"], false,
+        "with no loading cache module linked the cache should keep nothing: {report}"
+    );
+}
+
+/// A `[cache.<name>]` table naming a cache no linked module declares is
+/// refused by the deploy check and at startup with one message, naming the
+/// caches that could be written, so a misspelt name fails `ts config
+/// validate` and not the deployment.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn a_cache_table_no_module_declares_is_refused_by_the_deploy_check_and_at_startup() {
+    let settings = settings_with(&format!(
+        r#"
+            [cache.seam-probe-answres]
+            module = "seam-probe"
+            {PROBE_BLOCK}
+        "#
+    ));
+    let both = [seam_probe::builder(), seam_probe::loading_cache_builder()];
+
+    let deploy = validate_settings_for_deploy_with(&settings, &both)
+        .expect_err("the deploy check should refuse the misspelt table");
+    let startup = TrustedServerApp::routes_with_registrations(settings, &both)
+        .err()
+        .expect("startup should refuse the misspelt table");
+
+    // The message alone: the debug form carries a backtrace where the
+    // runner asks for one, and the two are raised on different stacks.
+    let message = format!("{deploy}");
+    assert!(
+        message.contains("[cache.seam-probe-answres]"),
+        "should name the table: {message}"
+    );
+    assert!(
+        message.contains("robots-txt, seam-probe-answers"),
+        "should list the caches this build declares: {message}"
+    );
+    assert_eq!(
+        message,
+        format!("{startup}"),
+        "the deploy check should refuse what startup refuses"
+    );
+}
+
 // ---------------------------------------------------------------------------
 // 4. A geo selector naming a module that supplies no module fails at startup
 // ---------------------------------------------------------------------------

crates/trusted-server-core/src/config.rs

@@ -359,11 +359,15 @@ pub fn validate_settings_for_deploy_with(
     let mut structural_settings = settings.clone();
     structural_settings.prepare_runtime()?;
 
+    // A `[cache.<name>]` table is refused here as the cache build refuses it,
+    // so a misspelt name fails `ts config validate` and not the deployment's
+    // first request.
+    let builders: Vec<IntegrationBuilder> =
+        crate::integrations::all_builders(extra_integrations).collect();
+    crate::integrations::check_cache_tables(settings, &builders)?;
     // A `[cache.<name>]` module no linked crate offers a cache from is refused
     // here as making the caches refuses it, so a misspelt module fails
     // `ts config validate` rather than the service.
-    let builders: Vec<IntegrationBuilder> =
-        crate::integrations::all_builders(extra_integrations).collect();
     crate::integrations::check_loading_cache_modules(settings, &builders)?;
 
     // The plan is compiled with the builders the blocks are validated