Load Spin startup config from a key-value store

The Spin adapter compiled the example config in at build time
(`include_str!`), so it ignored `ts config push --adapter spin` and could
never serve real operator config. Load Settings at startup from a Spin
key-value store instead, matching the Fastly/Axum config-store path.

- Add `SpinKvConfigStore`, a Spin key-value-backed `PlatformConfigStore`
  (async `spin_sdk::key_value`, wasm+spin gated). This is distinct from the
  variable-backed `ConfigStoreHandleAdapter`: a multi-kilobyte app-config
  blob does not fit Spin's flat variable namespace.
- `build_state` now loads via `get_settings_from_config_store` on the Spin
  runtime (store id and blob key both `app_config`); native test builds keep
  the embedded example config since Spin host KV is unavailable there.
- Grant the component the `app_config` KV label in spin.toml and declare its
  backend in a new runtime-config.toml; `serve` passes `--runtime-config-file`.
- Unseeded/unreadable store fails closed (503) via the startup error router.
- Ignore `.spin/` local runtime state; update the architecture doc.

Verified: wasm build, native tests, clippy (wasm + native), and a live
`spin up` unseeded run (503). The seeded read is verified on every local
layer (the pushed blob is a valid envelope at store/key `app_config`) but
not live end-to-end: the installed Spin CLI (4.0) is newer than the Spin 2-3
SQLite KV schema that `ts config push --local` writes, so a Spin-2/3 runtime
(or an edgezero-cli update) is needed to confirm seeded -> 200.

Author: prk-Jr

.gitignore

@@ -16,6 +16,9 @@
 /spin
 /spin.sig
 
+# Spin runtime state (local KV/SQLite created by `spin up`)
+.spin/
+
 # EdgeZero local KV store (created by edgezero-adapter-axum framework)
 .edgezero/
 

crates/trusted-server-adapter-spin/runtime-config.toml

@@ -0,0 +1,15 @@
+# Spin runtime configuration for the Trusted Server adapter.
+#
+# Declares the `app_config` key-value store that holds the Trusted Server
+# app-config blob loaded at startup and seeded by `ts config push --adapter
+# spin`. Spin auto-provides only the `default` label; any other label (here
+# `app_config`) must be declared here or `spin up` fails with
+# `unknown key_value_stores label app_config`.
+#
+# `type = "spin"` uses Spin's built-in SQLite key-value backend (a local
+# `.spin/sqlite_key_value.db` file), matching what `ts config push --adapter
+# spin --local` writes to. Point it at redis/azure/etc. for a shared backend.
+#
+# Load it explicitly: `spin up --runtime-config-file runtime-config.toml`.
+[key_value_store.app_config]
+type = "spin"

crates/trusted-server-adapter-spin/spin.toml

@@ -38,7 +38,11 @@ source = "../../target/wasm32-wasip1/release/trusted_server_adapter_spin.wasm"
 # origins are still served over plaintext http. Follow-up: scope this to the
 # configured origins once they can be enumerated from settings.
 allowed_outbound_hosts = ["https://*:*", "http://*:*"]
-key_value_stores = ["default"]
+# `app_config` holds the Trusted Server app-config blob loaded at startup and
+# seeded by `ts config push --adapter spin`. Spin auto-provides only `default`;
+# `app_config` must be granted here and backed by a `[key_value_store.app_config]`
+# stanza in runtime-config.toml (passed via `spin up --runtime-config-file`).
+key_value_stores = ["default", "app_config"]
 
 [component.trusted-server.variables]
 v_current_x2dkid = "{{ v_current_x2dkid }}"

crates/trusted-server-adapter-spin/src/app.rs

@@ -26,6 +26,10 @@ use trusted_server_core::request_signing::{
     handle_verify_signature,
 };
 use trusted_server_core::settings::Settings;
+#[cfg(all(feature = "spin", target_arch = "wasm32"))]
+use trusted_server_core::settings_data::{
+    default_config_key, default_config_store_name, get_settings_from_config_store,
+};
 
 use crate::middleware::{AuthMiddleware, FinalizeResponseMiddleware, NormalizeMiddleware};
 use crate::platform::build_runtime_services;
@@ -48,8 +52,34 @@ pub struct AppState {
 /// Returns an error when settings, the auction orchestrator, or the integration
 /// registry fail to initialise.
 fn build_state() -> Result<Arc<AppState>, Report<TrustedServerError>> {
-    let settings = Settings::from_toml(include_str!("../../../trusted-server.example.toml"))?;
-    build_state_with_settings(settings)
+    build_state_with_settings(load_startup_settings()?)
+}
+
+/// Loads startup [`Settings`] on the Spin runtime from the app-config blob in
+/// the Spin key-value store seeded by `ts config push --adapter spin` (store id
+/// and blob key both resolve to `app_config`).
+///
+/// # Errors
+///
+/// Returns [`TrustedServerError::ConfigStoreUnavailable`] (HTTP 503) when the
+/// store is unseeded or unreadable, and [`TrustedServerError::Configuration`]
+/// (HTTP 500) when the blob fails envelope/settings verification.
+#[cfg(all(feature = "spin", target_arch = "wasm32"))]
+fn load_startup_settings() -> Result<Settings, Report<TrustedServerError>> {
+    let store_name = default_config_store_name();
+    let config_key = default_config_key();
+    get_settings_from_config_store(
+        &crate::platform::SpinKvConfigStore,
+        &store_name,
+        &config_key,
+    )
+}
+
+/// Loads startup [`Settings`] from the embedded example config on non-Spin
+/// (native test) builds, where Spin host key-value functions are unavailable.
+#[cfg(not(all(feature = "spin", target_arch = "wasm32")))]
+fn load_startup_settings() -> Result<Settings, Report<TrustedServerError>> {
+    Settings::from_toml(include_str!("../../../trusted-server.example.toml"))
 }
 
 /// Build the application state from explicit settings.

crates/trusted-server-adapter-spin/src/platform.rs

@@ -61,6 +61,57 @@ impl PlatformConfigStore for NoopConfigStore {
     }
 }
 
+/// Spin key-value-backed [`PlatformConfigStore`] used to load the app-config
+/// blob at startup.
+///
+/// `ts config push --adapter spin` writes the app-config blob into a Spin
+/// key-value store (label = the config store id, key = the blob key), so
+/// startup opens that store by name and reads the blob. This is deliberately
+/// distinct from [`ConfigStoreHandleAdapter`], which reads per-request
+/// request-signing config from Spin component *variables*: a multi-kilobyte
+/// blob does not fit Spin's flat variable namespace.
+#[cfg(all(feature = "spin", target_arch = "wasm32"))]
+pub(crate) struct SpinKvConfigStore;
+
+#[cfg(all(feature = "spin", target_arch = "wasm32"))]
+impl PlatformConfigStore for SpinKvConfigStore {
+    fn get(&self, store_name: &StoreName, key: &str) -> Result<String, Report<PlatformError>> {
+        let label = store_name.as_ref();
+        let store =
+            futures::executor::block_on(spin_sdk::key_value::Store::open(label)).map_err(|e| {
+                Report::new(PlatformError::ConfigStore).attach(format!(
+                    "failed to open Spin key-value store `{label}`: {e}"
+                ))
+            })?;
+        let bytes = futures::executor::block_on(store.get(key))
+            .map_err(|e| {
+                Report::new(PlatformError::ConfigStore).attach(format!(
+                    "Spin key-value lookup for `{key}` in `{label}` failed: {e}"
+                ))
+            })?
+            .ok_or_else(|| {
+                Report::new(PlatformError::ConfigStore).attach(format!(
+                    "key `{key}` not found in Spin key-value store `{label}`"
+                ))
+            })?;
+        String::from_utf8(bytes).map_err(|e| {
+            Report::new(PlatformError::ConfigStore).attach(format!(
+                "Spin key-value value for `{key}` is not valid UTF-8: {e}"
+            ))
+        })
+    }
+
+    fn put(&self, _: &StoreId, _: &str, _: &str) -> Result<(), Report<PlatformError>> {
+        Err(Report::new(PlatformError::ConfigStore)
+            .attach("config store writes are not supported on Spin"))
+    }
+
+    fn delete(&self, _: &StoreId, _: &str) -> Result<(), Report<PlatformError>> {
+        Err(Report::new(PlatformError::ConfigStore)
+            .attach("config store writes are not supported on Spin"))
+    }
+}
+
 #[cfg(not(all(feature = "spin", target_arch = "wasm32")))]
 struct NoopSecretStore;
 

docs/guide/architecture.md

@@ -66,7 +66,7 @@ Native Axum dev/test adapter (native binary):
 Fermyon Spin adapter (`wasm32-wasip1` component):
 
 - Production-capable deployment target for the Spin runtime
-- Platform services (config store, secret store, KV) backed by Spin component variables and the EdgeZero KV handle
+- Startup app-config blob loaded from a Spin key-value store (`app_config`, seeded by `ts config push --adapter spin`); per-request request-signing config and secrets read from Spin component variables; KV via the EdgeZero KV handle
 - Outbound HTTP via `spin_sdk::http::send` — no configurable per-request timeout (see rustdoc)
 - Single auction provider only; multi-provider fan-out requires the Fastly adapter
 

edgezero.toml

@@ -101,5 +101,5 @@ features = ["spin"]
 
 [adapters.spin.commands]
 build = "cargo build --package trusted-server-adapter-spin --target wasm32-wasip1 --features spin --release"
-serve = "spin up --from crates/trusted-server-adapter-spin"
+serve = "spin up --from crates/trusted-server-adapter-spin --runtime-config-file crates/trusted-server-adapter-spin/runtime-config.toml"
 deploy = "spin deploy --from crates/trusted-server-adapter-spin"