From 3341650822a92fae388f5bc8eac7fad26e526863 Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Wed, 18 Nov 2026 17:43:03 +0530 Subject: [PATCH 1/4] Add authenticated Spin geo and verify Cloudflare context --- .../tests/contract.rs | 166 ++++++-- crates/edgezero-adapter-spin/src/geo.rs | 379 ++++++++++++++++++ crates/edgezero-adapter-spin/src/lib.rs | 1 + .../src/outbound/test_support.rs | 2 +- crates/edgezero-adapter-spin/src/request.rs | 53 ++- .../src/request/test_support.rs | 69 +++- .../edgezero-adapter-spin/tests/contract.rs | 154 ++++++- crates/edgezero-core/src/geo.rs | 42 +- docs/guide/adapters/cloudflare.md | 21 + docs/guide/adapters/spin.md | 71 ++++ docs/guide/native-geo.md | 7 +- .../plans/2026-11-18-cloudflare-spin-geo.md | 92 +++++ .../2026-11-18-cloudflare-spin-geo-design.md | 50 +++ 13 files changed, 1050 insertions(+), 57 deletions(-) create mode 100644 crates/edgezero-adapter-spin/src/geo.rs create mode 100644 docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md create mode 100644 docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md diff --git a/crates/edgezero-adapter-cloudflare/tests/contract.rs b/crates/edgezero-adapter-cloudflare/tests/contract.rs index b41d76a3..6c926376 100644 --- a/crates/edgezero-adapter-cloudflare/tests/contract.rs +++ b/crates/edgezero-adapter-cloudflare/tests/contract.rs @@ -59,7 +59,10 @@ mod tests { }; use edgezero_core::context::RequestContext; use edgezero_core::error::EdgeError; - use edgezero_core::geo::{GeoError, GeoOutcome, GeoProviderId, GeoSource, GeoStatus}; + use edgezero_core::geo::{ + GeoError, GeoOutcome, GeoProviderId, GeoSource, GeoStatus, GeoTrustBasis, + GeoUnavailableReason, SubdivisionCode, + }; use edgezero_core::http::{Method, Response, StatusCode, response_builder}; use edgezero_core::outbound::{ HttpClient, OutboundCollectedSlot, OutboundRequest, OutboundSlotResult, OutboundTime, @@ -415,43 +418,138 @@ mod tests { } #[wasm_bindgen_test] - async fn dispatch_exposes_cf_metadata_through_ctx_geo() { - async fn geo(ctx: RequestContext) -> Result { - let body = Body::text(format!("{:?}", ctx.geo())); - response_builder() - .status(StatusCode::OK) - .body(body) - .map_err(EdgeError::internal) - } - let app = App::new(RouterService::builder().get("/geo", geo).build()); - let inner = Clone::clone(cf_request(CfMethod::Get, "/geo", None).inner()); - let cf = Object::new(); - for (key, value) in [("country", "US"), ("regionCode", "CA")] { - Reflect::set(&cf, &JsValue::from_str(key), &JsValue::from_str(value)) - .expect("cf field"); + #[expect( + clippy::too_many_lines, + reason = "one matrix compares all three managed entrypoints across the same ordered requests" + )] + async fn managed_entrypoints_keep_platform_geo_per_request() { + struct GeoApp; + + #[expect( + clippy::missing_trait_methods, + reason = "store-free fixture deliberately uses default application configuration" + )] + impl Hooks for GeoApp { + fn owns_logging() -> bool { + true + } + + fn routes() -> Result { + Ok(RouterService::builder().get("/geo", geo).build()) + } } - Reflect::set(&inner, &JsValue::from_str("cf"), &cf).expect("cf"); - let (env, ctx, _timers) = test_env_ctx(); - let mut response = CloudflareService::new(&app) - .dispatch(CfRequest::from(inner), env, ctx) - .await - .expect("cf response"); + #[edgezero_core::action] + async fn geo(ctx: RequestContext) -> String { + let GeoOutcome::Selected { provider, status } = ctx.geo() else { + return serde_json::json!({"status": "no-selection"}).to_string(); + }; + assert_eq!(provider.as_str(), "cloudflare"); + match status { + GeoStatus::Located { + location, + source, + trust_basis, + } => { + assert_eq!(*source, GeoSource::Cloudflare); + assert_eq!(*trust_basis, GeoTrustBasis::PlatformMetadata); + serde_json::json!({ + "status": "located", + "country": location.country().as_str(), + "subdivision": location.subdivision().map(SubdivisionCode::as_str), + }) + .to_string() + } + GeoStatus::Unavailable(reason) => { + assert_eq!(*reason, GeoUnavailableReason::MissingMetadata); + serde_json::json!({"status": "missing"}).to_string() + } + GeoStatus::Error(error) => { + serde_json::json!({"unexpected_error": error.to_string()}).to_string() + } + } + } - assert_eq!(response.status_code(), StatusCode::OK.as_u16()); - let expected = GeoOutcome::platform(GeoSource::Cloudflare, Some("US"), Some("CA")); - assert!(matches!( - &expected, - GeoOutcome::Selected { - status: GeoStatus::Located { .. }, - .. + let app = App::build::(edgezero_adapter_cloudflare::CLOUDFLARE_PLATFORM) + .expect("store-free application"); + let cases: &[(&[(&str, &str)], serde_json::Value)] = &[ + ( + &[ + ("country", "US"), + ("region", "California"), + ("regionCode", "CA"), + ], + serde_json::json!({"status": "located", "country": "US", "subdivision": "CA"}), + ), + (&[], serde_json::json!({"status": "missing"})), + ( + &[("country", "gb")], + serde_json::json!({"status": "located", "country": "GB", "subdivision": null}), + ), + ( + &[("country", "us"), ("regionCode", "01")], + serde_json::json!({"status": "located", "country": "US", "subdivision": "01"}), + ), + ( + &[("country", "US"), ("regionCode", "US-CA")], + serde_json::json!({"status": "located", "country": "US", "subdivision": null}), + ), + ( + &[("country", "XX")], + serde_json::json!({"status": "missing"}), + ), + ( + &[("country", "T1")], + serde_json::json!({"status": "missing"}), + ), + ( + &[("regionCode", "CA")], + serde_json::json!({"status": "missing"}), + ), + ]; + + for entrypoint in ["service", "run_app", "dispatch_app"] { + for (fields, expected) in cases { + let inner = Clone::clone(cf_request(CfMethod::Get, "/geo", None).inner()); + if !fields.is_empty() { + let cf = Object::new(); + for (key, value) in *fields { + Reflect::set(&cf, &JsValue::from_str(key), &JsValue::from_str(value)) + .expect("platform metadata field"); + } + Reflect::set(&inner, &JsValue::from_str("cf"), &cf).expect("cf metadata"); + } + for (name, value) in [ + ("cf-ipcountry", "DE"), + ("cloudfront-viewer-country", "DE"), + ("cloudfront-viewer-country-region", "BE"), + ] { + inner.headers().set(name, value).expect("spoofed header"); + } + let request = CfRequest::from(inner); + let (env, ctx, _timers) = test_env_ctx(); + let mut response = match entrypoint { + "service" => { + CloudflareService::new(&app) + .dispatch(request, env, ctx) + .await + } + "run_app" => { + edgezero_adapter_cloudflare::run_app::(request, env, ctx).await + } + _ => { + edgezero_adapter_cloudflare::dispatch_app::(&app, request, env, ctx) + .await + } + } + .expect("managed geo response"); + assert_eq!(response.status_code(), StatusCode::OK.as_u16()); + let actual: serde_json::Value = + serde_json::from_str(&response.text().await.expect("geo response body")) + .expect("geo response JSON"); + assert_eq!(&actual, expected, "{entrypoint}, metadata {fields:?}"); } - )); - assert_eq!( - response.text().await.expect("text"), - format!("{expected:?}"), - "cf metadata wins over the request's CloudFront headers" - ); + } } #[wasm_bindgen_test] diff --git a/crates/edgezero-adapter-spin/src/geo.rs b/crates/edgezero-adapter-spin/src/geo.rs new file mode 100644 index 00000000..cb53008a --- /dev/null +++ b/crates/edgezero-adapter-spin/src/geo.rs @@ -0,0 +1,379 @@ +//! Authenticated ingress geography for Spin deployments. + +#![expect( + clippy::arbitrary_source_item_ordering, + reason = "group public configuration, platform-gated resolution and colocated tests" +)] + +use edgezero_core::error::EdgeError; +#[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] +use edgezero_core::geo::GeoProviderId; + +/// Enables trusted ingress assertions on managed Spin dispatch. +/// +/// Insert this non-secret selection in App state from `Hooks::configure`. +/// The variable must contain a 32–128 byte ASCII credential (bytes 0x21–0x7e). The proxy +/// must replace viewer assertions and protect its transport to Spin. No geography +/// is selected when this configuration is absent. +#[derive(Clone, Debug)] +pub struct SpinGeoIngress { + credential_variable: String, + #[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] + provider: GeoProviderId, +} + +impl SpinGeoIngress { + /// Select the Spin variable containing the expected ingress credential. + /// + /// # Errors + /// Rejects names outside `[a-z][a-z0-9_]{0,63}`. The credential itself is + /// loaded per admitted request and is never retained in application state. + #[inline] + pub fn new(credential_variable: &str) -> Result { + if credential_variable.is_empty() + || credential_variable.len() > 64 + || !credential_variable + .as_bytes() + .first() + .is_some_and(u8::is_ascii_lowercase) + || !credential_variable + .bytes() + .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_') + { + return Err(EdgeError::validation( + "invalid Spin geo credential variable", + )); + } + Ok(Self { + credential_variable: credential_variable.to_owned(), + #[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] + provider: GeoProviderId::new("spin-ingress").map_err(EdgeError::internal)?, + }) + } + + /// Name of the variable, never its value. + #[inline] + #[must_use] + pub fn credential_variable(&self) -> &str { + &self.credential_variable + } +} + +#[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] +pub(crate) mod ingress { + use super::SpinGeoIngress; + use bytes::Bytes; + use edgezero_core::geo::{ + CountryCode, GeoAssertion, GeoError, GeoLocation, GeoOutcome, GeoSource, GeoStatus, + GeoTrustBasis, GeoUnavailableReason, SubdivisionCode, + }; + use edgezero_core::http::HeaderMap; + use edgezero_core::secret_store::SecretError; + #[cfg(all(feature = "spin", target_arch = "wasm32"))] + use edgezero_core::secret_store::SecretStore; + #[cfg(all(feature = "spin", target_arch = "wasm32"))] + use edgezero_core::time::{Deadline, MonotonicClock}; + use std::future::Future; + use std::str; + use subtle::ConstantTimeEq as _; + + pub(crate) const COUNTRY_HEADER: &str = "x-edgezero-geo-country"; + pub(crate) const REGION_HEADER: &str = "x-edgezero-geo-region"; + pub(crate) const TOKEN_HEADER: &str = "x-edgezero-geo-token"; + + pub(crate) fn capture_token(headers: &mut HeaderMap) -> Option { + let mut values = headers.get_all(TOKEN_HEADER).iter(); + let token = values + .next() + .filter(|value| valid_token(value.as_bytes())) + .filter(|_value| values.next().is_none()) + .map(|value| Bytes::copy_from_slice(value.as_bytes())); + headers.remove(TOKEN_HEADER); + token + } + + fn valid_token(token: &[u8]) -> bool { + (32..=128).contains(&token.len()) && token.iter().all(u8::is_ascii_graphic) + } + + fn assertion(headers: &HeaderMap, name: &str) -> GeoAssertion { + let mut values = headers.get_all(name).iter(); + match (values.next(), values.next()) { + (None, _) => GeoAssertion::absent(), + (Some(value), None) => GeoAssertion::from_bytes(value.as_bytes()), + _ => GeoAssertion::invalid(), + } + } + + fn location(headers: &HeaderMap) -> Result, GeoError> { + let country_assertion = assertion::<2>(headers, COUNTRY_HEADER); + let region_assertion = assertion::<3>(headers, REGION_HEADER); + let country_bytes = country_assertion.as_bytes()?; + let region_bytes = region_assertion.as_bytes()?; + let Some(country_value) = country_bytes else { + return if region_bytes.is_none() { + Ok(None) + } else { + Err(GeoError::InvalidAssertion) + }; + }; + let code = |bytes| str::from_utf8(bytes).map_err(|_error| GeoError::InvalidAssertion); + let country = + CountryCode::new(code(country_value)?).map_err(|_error| GeoError::InvalidAssertion)?; + let region = region_bytes + .map(|bytes| { + SubdivisionCode::new(code(bytes)?).map_err(|_error| GeoError::InvalidAssertion) + }) + .transpose()?; + Ok(Some(GeoLocation::new(country, region))) + } + + #[expect( + clippy::multiple_inherent_impl, + reason = "keep platform-only resolution separate from host-compilable configuration" + )] + impl SpinGeoIngress { + pub(crate) fn outcome(&self, status: GeoStatus) -> GeoOutcome { + GeoOutcome::Selected { + provider: self.provider.clone(), + status, + } + } + + pub(crate) fn resolve_value( + &self, + supplied: &[u8], + expected: Option<&[u8]>, + headers: &HeaderMap, + ) -> GeoOutcome { + let Some(expected_value) = expected.filter(|value| valid_token(value)) else { + return self.outcome(GeoStatus::Error(GeoError::ProviderFailure)); + }; + if !bool::from(supplied.ct_eq(expected_value)) { + return self.outcome(GeoStatus::Unavailable( + GeoUnavailableReason::UntrustedIngress, + )); + } + self.outcome(match location(headers) { + Ok(Some(location)) => GeoStatus::Located { + location, + source: GeoSource::SpinIngress, + trust_basis: GeoTrustBasis::AuthenticatedIngressHeader, + }, + Ok(None) => GeoStatus::Unavailable(GeoUnavailableReason::MissingMetadata), + Err(error) => GeoStatus::Error(error), + }) + } + + pub(crate) async fn resolve_with( + &self, + supplied: Option, + headers: &HeaderMap, + lookup: F, + ) -> GeoOutcome + where + F: FnOnce() -> R, + R: Future, SecretError>>, + { + let Some(supplied_value) = supplied else { + return self.outcome(GeoStatus::Unavailable( + GeoUnavailableReason::UntrustedIngress, + )); + }; + match lookup().await { + Ok(expected) => self.resolve_value(&supplied_value, expected.as_deref(), headers), + Err(_error) => self.outcome(GeoStatus::Error(GeoError::ProviderFailure)), + } + } + + #[cfg(all(feature = "spin", target_arch = "wasm32"))] + pub(crate) async fn resolve( + &self, + supplied: Option, + headers: &HeaderMap, + clock: &MonotonicClock, + deadline: Deadline, + secrets: &dyn SecretStore, + ) -> GeoOutcome { + self.resolve_with(supplied, headers, || async { + secrets + .get_bytes_bounded("", &self.credential_variable, clock, deadline, 128, 128) + .await + .map(|read| read.value) + }) + .await + } + } +} + +#[cfg(test)] +mod tests { + use super::ingress::*; + use super::*; + use edgezero_core::geo::{ + GeoError, GeoOutcome, GeoSource, GeoStatus, GeoTrustBasis, GeoUnavailableReason, + }; + use edgezero_core::http::{HeaderMap, HeaderValue}; + + const TOKEN: &[u8] = b"0123456789abcdef0123456789abcdef"; + + #[test] + fn invalid_token_skips_lookup_and_backend_failure_is_bounded() { + use edgezero_core::secret_store::SecretError; + use futures::executor::block_on; + use std::cell::Cell; + let selection = SpinGeoIngress::new("geo_token").unwrap(); + let headers = HeaderMap::new(); + let calls = Cell::new(0_u32); + let lookup = || async { + calls.set(calls.get() + 1); + Err(SecretError::DeadlineExceeded) + }; + let result = block_on(selection.resolve_with(None, &headers, lookup)); + assert!(matches!( + result, + GeoOutcome::Selected { + status: GeoStatus::Unavailable(GeoUnavailableReason::UntrustedIngress), + .. + } + )); + assert_eq!(calls.get(), 0); + let failed_lookup = block_on(selection.resolve_with( + Some(bytes::Bytes::from_static(TOKEN)), + &headers, + lookup, + )); + assert!(matches!( + failed_lookup, + GeoOutcome::Selected { + status: GeoStatus::Error(GeoError::ProviderFailure), + .. + } + )); + assert_eq!(calls.get(), 1); + } + + #[test] + fn selection_rejects_invalid_variable_names() { + assert_eq!( + SpinGeoIngress::new("geo_token") + .unwrap() + .credential_variable(), + "geo_token" + ); + for name in ["", "GEO_TOKEN", "a-b", "1token", "a token", &"a".repeat(65)] { + assert!(SpinGeoIngress::new(name).is_err(), "{name}"); + } + } + + #[test] + fn credential_capture_strips_all_values_and_rejects_ambiguity() { + let mut headers = HeaderMap::new(); + headers.insert(TOKEN_HEADER, HeaderValue::from_bytes(TOKEN).unwrap()); + assert_eq!(capture_token(&mut headers).as_deref(), Some(TOKEN)); + assert!(!headers.contains_key(TOKEN_HEADER)); + for values in [ + vec![TOKEN, TOKEN], + vec![b"short".as_slice()], + vec![b"".as_slice()], + ] { + for value in values { + headers.append(TOKEN_HEADER, HeaderValue::from_bytes(value).unwrap()); + } + assert!(capture_token(&mut headers).is_none()); + assert!(!headers.contains_key(TOKEN_HEADER)); + } + headers.insert( + TOKEN_HEADER, + HeaderValue::from_str(&"a".repeat(129)).unwrap(), + ); + assert!(capture_token(&mut headers).is_none()); + assert!(!headers.contains_key(TOKEN_HEADER)); + } + + #[test] + fn authentication_precedes_geography_and_retains_provenance() { + let selection = SpinGeoIngress::new("geo_token").unwrap(); + let mut headers = HeaderMap::new(); + headers.insert(COUNTRY_HEADER, HeaderValue::from_static("us")); + headers.insert(REGION_HEADER, HeaderValue::from_static("ca")); + let outcome = selection.resolve_value(TOKEN, Some(TOKEN), &headers); + let GeoOutcome::Selected { + provider, + status: + GeoStatus::Located { + location, + source, + trust_basis, + }, + } = outcome + else { + panic!("authenticated country and region must be located"); + }; + assert_eq!(provider.as_str(), "spin-ingress"); + assert_eq!(location.country().as_str(), "US"); + assert_eq!(location.subdivision().unwrap().as_str(), "CA"); + assert_eq!(source, GeoSource::SpinIngress); + assert_eq!(trust_basis, GeoTrustBasis::AuthenticatedIngressHeader); + assert!(matches!( + selection.resolve_value(TOKEN, Some(b"different-different-different-1234"), &headers), + GeoOutcome::Selected { + status: GeoStatus::Unavailable(GeoUnavailableReason::UntrustedIngress), + .. + } + )); + assert!(matches!( + selection.resolve_value(TOKEN, None, &headers), + GeoOutcome::Selected { + status: GeoStatus::Error(GeoError::ProviderFailure), + .. + } + )); + } + + #[test] + fn authenticated_assertions_preserve_absence_and_reject_invalid_or_duplicate_fields() { + let selection = SpinGeoIngress::new("geo_token").unwrap(); + let mut headers = HeaderMap::new(); + assert!(matches!( + selection.resolve_value(TOKEN, Some(TOKEN), &headers), + GeoOutcome::Selected { + status: GeoStatus::Unavailable(GeoUnavailableReason::MissingMetadata), + .. + } + )); + headers.insert(COUNTRY_HEADER, HeaderValue::from_static("US")); + let outcome = selection.resolve_value(TOKEN, Some(TOKEN), &headers); + assert!( + matches!(outcome, GeoOutcome::Selected { status: GeoStatus::Located { location, .. }, .. } if location.subdivision().is_none()) + ); + for country in ["XX", "USA", " US", "", "T1"] { + headers.insert(COUNTRY_HEADER, HeaderValue::from_str(country).unwrap()); + assert!(matches!( + selection.resolve_value(TOKEN, Some(TOKEN), &headers), + GeoOutcome::Selected { + status: GeoStatus::Error(GeoError::InvalidAssertion), + .. + } + )); + } + headers.insert(COUNTRY_HEADER, HeaderValue::from_static("US")); + headers.append(COUNTRY_HEADER, HeaderValue::from_static("US")); + assert!(matches!( + selection.resolve_value(TOKEN, Some(TOKEN), &headers), + GeoOutcome::Selected { + status: GeoStatus::Error(GeoError::InvalidAssertion), + .. + } + )); + headers.remove(COUNTRY_HEADER); + headers.insert(REGION_HEADER, HeaderValue::from_static("CA")); + assert!(matches!( + selection.resolve_value(TOKEN, Some(TOKEN), &headers), + GeoOutcome::Selected { + status: GeoStatus::Error(GeoError::InvalidAssertion), + .. + } + )); + } +} diff --git a/crates/edgezero-adapter-spin/src/lib.rs b/crates/edgezero-adapter-spin/src/lib.rs index ab5bc12b..ec07ba3e 100644 --- a/crates/edgezero-adapter-spin/src/lib.rs +++ b/crates/edgezero-adapter-spin/src/lib.rs @@ -6,6 +6,7 @@ pub mod cli; #[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] pub mod config_store; pub mod context; +pub mod geo; #[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] mod ingress; #[cfg(all(feature = "spin", target_arch = "wasm32"))] diff --git a/crates/edgezero-adapter-spin/src/outbound/test_support.rs b/crates/edgezero-adapter-spin/src/outbound/test_support.rs index f1a39865..eec506e0 100644 --- a/crates/edgezero-adapter-spin/src/outbound/test_support.rs +++ b/crates/edgezero-adapter-spin/src/outbound/test_support.rs @@ -18,7 +18,7 @@ pub use super::spin_impl::test_support::{ #[cfg(all(feature = "spin", target_arch = "wasm32"))] pub use crate::request::test_support::{ deadline_body, dispatch_ingress_stream, dispatch_ingress_stream_with_timer, - dispatch_ingress_with, dispatch_request, + dispatch_ingress_with, dispatch_request, dispatch_request_with_geo_secret, }; #[cfg(all(feature = "spin", target_arch = "wasm32"))] pub use crate::response::test_support::next_response_body; diff --git a/crates/edgezero-adapter-spin/src/request.rs b/crates/edgezero-adapter-spin/src/request.rs index 96a4ca61..fff2e0f6 100644 --- a/crates/edgezero-adapter-spin/src/request.rs +++ b/crates/edgezero-adapter-spin/src/request.rs @@ -12,15 +12,17 @@ pub(crate) mod test_support; use crate::SpinResponse; use crate::config_store::SpinConfigStore; use crate::context::{SpinRequestContext, parse_client_addr}; +use crate::geo::{SpinGeoIngress, ingress::capture_token}; use crate::ingress::capture_request_ingress; use crate::key_value_store::{DEFAULT_MAX_LIST_KEYS, SpinKvStore}; use crate::response::from_egress_response; use crate::secret_store::SpinSecretStore; -use edgezero_core::app::{App, StoreMetadata}; +use edgezero_core::app::{App, FrameworkErrorDetail, StoreMetadata}; use edgezero_core::body::Body; use edgezero_core::config_store::ConfigStoreHandle; use edgezero_core::env_config::EnvConfig; use edgezero_core::error::EdgeError; +use edgezero_core::geo::GeoOutcome; #[cfg(test)] use edgezero_core::http::request_builder; use edgezero_core::http::{HeaderMap, Method, Request, RequestParts}; @@ -31,7 +33,7 @@ use edgezero_core::ingress::{ use edgezero_core::key_value_store::KvHandle; use edgezero_core::outbound::HttpClient; use edgezero_core::response_egress::ResponseEgressEnvelope; -use edgezero_core::secret_store::SecretHandle; +use edgezero_core::secret_store::{SecretHandle, SecretStore}; use edgezero_core::store_registry::{ BoundSecretStore, ConfigRegistry, ConfigStoreBinding, KvRegistry, SecretRegistry, StoreRegistry, }; @@ -354,10 +356,15 @@ where make_source, sleep, deliver, + &SpinSecretStore::new(), ) .await } +#[expect( + clippy::too_many_arguments, + reason = "inject the credential backend independently of source construction, timing and delivery" +)] async fn dispatch_ingress_stream_with_timer_and< Source, SourceError, @@ -374,6 +381,7 @@ async fn dispatch_ingress_stream_with_timer_and< make_source: MakeSource, make_timer: MakeTimer, deliver: Deliver, + geo_secrets: &dyn SecretStore, ) -> anyhow::Result where Source: futures_util::Stream> + 'static, @@ -388,15 +396,24 @@ where .extensions_mut() .insert(outbound_client(app.monotonic_clock())); let request_method = head_request.method().clone(); - let head_parts = IngressHeadParts::from_request( + // Account the original credential bytes, but never retain them in the + // cloned head that admission callbacks inspect. + let head_validation = IngressHeadParts::from_request( &head_request, IngressHeadAccounting::HostManaged, IngressFraming::HostManaged, - ); - if let Err(error) = head_parts.validate_normalized(app.ingress_head_limits()) { + ) + .validate_normalized(app.ingress_head_limits()); + let token = capture_token(head_request.headers_mut()); + if let Err(error) = head_validation { let egress = detached_error_envelope(app, error, request_method, request_start)?; return Ok(deliver(egress)?); } + let head_parts = IngressHeadParts::from_request( + &head_request, + IngressHeadAccounting::HostManaged, + IngressFraming::HostManaged, + ); let prepared = match app.begin_ingress(head_parts, request_start) { Ok(outcome) => match outcome { IngressBeginOutcome::Admitted(prepared) => prepared, @@ -423,6 +440,20 @@ where return Ok(deliver(egress)?); } }; + let geo = match app.state::() { + Some(selection) => { + selection + .resolve( + token, + head_request.headers(), + &prepared.monotonic_clock(), + prepared.read_deadline(), + geo_secrets, + ) + .await + } + None => GeoOutcome::NoSelection, + }; if !explicit_empty_body(head_request.headers()) { let source = match make_source() { Ok(source) => source, @@ -435,7 +466,7 @@ where make_timer, ); } - dispatch_core_request(app, head_request, stores, prepared, deliver).await + dispatch_core_request(app, head_request, stores, prepared, geo, deliver).await }) .await } @@ -445,6 +476,7 @@ async fn dispatch_core_request( mut core_request: Request, stores: Stores, prepared: PreparedIngress, + geo: GeoOutcome, deliver: Deliver, ) -> anyhow::Result where @@ -464,7 +496,13 @@ where if let Some(registry) = secret_registry { core_request.extensions_mut().insert(registry); } - let response = Box::pin(app.dispatch_admitted(prepared, core_request)).await; + let response = Box::pin(app.dispatch_admitted_with_geo( + prepared, + core_request, + FrameworkErrorDetail::Default, + geo, + )) + .await; Ok(deliver(response)?) } @@ -760,6 +798,7 @@ mod synthesis_tests { }, |_| -> Pending<()> { panic!("expired read must not construct a timer") }, Ok, + &test_support::GeoSecret::missing(), )) .expect("response"); assert_eq!(envelope.response_mut().status().as_u16(), status); diff --git a/crates/edgezero-adapter-spin/src/request/test_support.rs b/crates/edgezero-adapter-spin/src/request/test_support.rs index e4856358..2a00416f 100644 --- a/crates/edgezero-adapter-spin/src/request/test_support.rs +++ b/crates/edgezero-adapter-spin/src/request/test_support.rs @@ -1,10 +1,46 @@ //! Narrow request-conversion and timer bridges. use super::*; use bytes::Bytes; +use edgezero_core::config_store::BoundedStoreRead; use edgezero_core::http::Uri; use edgezero_core::http::request_builder; +use edgezero_core::secret_store::{SecretError, SecretStore, finish_bounded_secret_read}; use std::future::pending; +pub(super) struct GeoSecret(Option); + +#[cfg(test)] +impl GeoSecret { + pub(super) fn missing() -> Self { + Self(None) + } +} + +#[async_trait::async_trait(?Send)] +impl SecretStore for GeoSecret { + async fn get_bytes(&self, _store: &str, _key: &str) -> Result, SecretError> { + Ok(self.0.clone()) + } + + async fn get_bytes_bounded( + &self, + store_name: &str, + key: &str, + clock: &MonotonicClock, + deadline: Deadline, + max_backend_bytes: u64, + max_value_bytes: u64, + ) -> Result, SecretError> { + finish_bounded_secret_read( + self.get_bytes(store_name, key).await, + clock, + deadline, + max_backend_bytes, + max_value_bytes, + ) + } +} + #[doc(hidden)] #[inline] pub fn deadline_body( @@ -51,6 +87,7 @@ where move || Ok(source), |_| pending::<()>(), Ok, + &GeoSecret(None), ) .await } @@ -85,6 +122,7 @@ where make_source, |_| pending::<()>(), deliver, + &GeoSecret(None), ) .await } @@ -119,6 +157,7 @@ where move || Ok(source), make_timer, Ok, + &GeoSecret(None), ) .await } @@ -133,5 +172,33 @@ pub async fn dispatch_request( app: &App, req: SpinRequest, ) -> anyhow::Result { - dispatch_with_handles_and(app, req, Stores::default(), app.monotonic_now(), Ok).await + dispatch_request_with_geo_secret(app, req, None).await +} + +/// Uses the production converter and managed ingress with an in-memory credential backend. +/// The actual Spin variable provider is qualified by the Spin runtime fixture. +/// +/// # Errors +/// Returns the managed request's admission, dispatch, or delivery error. +#[doc(hidden)] +#[inline] +pub async fn dispatch_request_with_geo_secret( + app: &App, + req: SpinRequest, + secret: Option, +) -> anyhow::Result { + let request_start = app.monotonic_now(); + let (parts, native_body) = req.into_parts(); + let core_request = into_core_request_head_for_app(parts, app); + dispatch_ingress_stream_with_timer_and( + app, + core_request, + Stores::default(), + request_start, + move || Ok(native_body.stream()), + sleep, + Ok, + &GeoSecret(secret), + ) + .await } diff --git a/crates/edgezero-adapter-spin/tests/contract.rs b/crates/edgezero-adapter-spin/tests/contract.rs index 5b268be4..e1eae0cb 100644 --- a/crates/edgezero-adapter-spin/tests/contract.rs +++ b/crates/edgezero-adapter-spin/tests/contract.rs @@ -583,7 +583,7 @@ mod tests { use edgezero_adapter_spin::outbound::SpinOutboundClient; use edgezero_adapter_spin::outbound::test_support::{ dispatch_ingress_stream, dispatch_ingress_stream_with_timer, dispatch_ingress_with, - dispatch_request, + dispatch_request, dispatch_request_with_geo_secret, }; use edgezero_core::http::{HeaderMap, HeaderValue, Method}; use edgezero_core::ingress::{ @@ -966,6 +966,158 @@ mod tests { assert!(observations.load(Ordering::SeqCst) >= 3); } + #[test] + #[expect( + clippy::too_many_lines, + reason = "one ordered matrix compares configured and disabled dispatch with credential and header-budget controls" + )] + fn managed_geo_strips_credentials_and_preserves_selected_outcome() { + use edgezero_adapter_spin::geo::SpinGeoIngress; + use edgezero_core::geo::{GeoSource, GeoTrustBasis, GeoUnavailableReason}; + + #[edgezero_core::action] + async fn observe(mut ctx: RequestContext) -> String { + assert!(!ctx.headers().contains_key("x-edgezero-geo-token")); + ctx.extensions_mut().insert(GeoOutcome::NoSelection); + if *ctx + .extensions() + .get::() + .expect("selection expectation") + { + let GeoOutcome::Selected { provider, status } = ctx.geo() else { + panic!("configured managed dispatch must retain its selection"); + }; + assert_eq!(provider.as_str(), "spin-ingress"); + if ctx.headers().contains_key("x-test-located") { + let GeoStatus::Located { + location, + source, + trust_basis, + } = status + else { + panic!("authenticated managed request must be located"); + }; + assert_eq!(location.country().as_str(), "US"); + assert_eq!(location.subdivision().expect("region").as_str(), "CA"); + assert_eq!(*source, GeoSource::SpinIngress); + assert_eq!(*trust_basis, GeoTrustBasis::AuthenticatedIngressHeader); + } else { + assert_eq!( + *status, + GeoStatus::Unavailable(GeoUnavailableReason::UntrustedIngress) + ); + } + } else { + assert_eq!(ctx.geo(), &GeoOutcome::NoSelection); + } + "observed".to_owned() + } + + struct Sanitized; + #[async_trait::async_trait(?Send)] + impl Middleware for Sanitized { + async fn handle( + &self, + ctx: RequestContext, + next: Next<'_>, + ) -> Result { + assert!(!ctx.headers().contains_key("x-edgezero-geo-token")); + next.run(ctx).await + } + } + + sdk_block_on(async { + for enabled in [false, true] { + let admissions = Arc::new(AtomicUsize::new(0)); + let observed_admissions = Arc::clone(&admissions); + let mut app = App::new( + RouterService::builder() + .middleware(Sanitized) + .get("/geo", observe) + .build(), + ); + app.insert_state(enabled); + if enabled { + app.insert_state( + SpinGeoIngress::new("unavailable_variable").expect("selection"), + ); + } + app.set_ingress_admission_policy(move |head| { + assert!(!head.headers().contains_key("x-edgezero-geo-token")); + observed_admissions.fetch_add(1, Ordering::SeqCst); + AdmissionDecision::Admit { + completion: ResponseEgressCompletion::empty(), + grant: IngressGrant::new(()), + read_deadline: head.read_deadline_after(Duration::from_secs(1)), + } + }); + let duplicate = "0123456789abcdef0123456789abcdef"; + for tokens in [ + &[][..], + &["short"][..], + &[duplicate, duplicate][..], + &[duplicate][..], + ] { + let mut outgoing = SpinRequest::builder() + .method("GET") + .uri("http://example.test/geo") + .header("content-length", "0") + .header("x-edgezero-geo-country", "US") + .header("x-edgezero-geo-region", "CA"); + if tokens == [duplicate] { + outgoing = outgoing.header("x-test-located", "yes"); + } + for token in tokens { + outgoing = outgoing.header("x-edgezero-geo-token", *token); + } + let request = outgoing + .body(http_body_util::Full::new(Bytes::new())) + .expect("native request"); + let incoming = SpinRequest::from_request( + request.into_request().expect("WASI request"), + ) + .expect("incoming request"); + let response = dispatch_request_with_geo_secret( + &app, + incoming, + Some(Bytes::from_static(b"0123456789abcdef0123456789abcdef")), + ) + .await + .expect("managed response"); + assert_eq!(captured_body(response).as_ref(), b"observed"); + } + assert_eq!(admissions.load(Ordering::SeqCst), 4); + app.set_ingress_head_limits( + IngressHeadLimits::default() + .with_max_request_header_bytes(1024) + .expect("header budget"), + ); + let request = SpinRequest::builder() + .method("GET") + .uri("http://example.test/geo") + .header("content-length", "0") + .header("x-edgezero-geo-token", "a".repeat(1500)) + .body(http_body_util::Full::new(Bytes::new())) + .expect("oversized native request"); + let incoming = + SpinRequest::from_request(request.into_request().expect("WASI request")) + .expect("incoming request"); + let response = dispatch_request(&app, incoming) + .await + .expect("bounded response"); + assert_eq!( + capture_response(response).status(), + StatusCode::REQUEST_HEADER_FIELDS_TOO_LARGE + ); + assert_eq!( + admissions.load(Ordering::SeqCst), + 4, + "stripping must not evade original header budget" + ); + } + }); + } + #[test] fn standard_native_request_refuses_before_body_read() { sdk_block_on(async { diff --git a/crates/edgezero-core/src/geo.rs b/crates/edgezero-core/src/geo.rs index e1cd5726..8f06d2e5 100644 --- a/crates/edgezero-core/src/geo.rs +++ b/crates/edgezero-core/src/geo.rs @@ -319,12 +319,17 @@ pub enum GeoSource { CloudFront, Cloudflare, Fastly, + /// Geographic assertions supplied by an authenticated Spin ingress proxy. + SpinIngress, } /// The declared infrastructure protection used for source admission. #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[non_exhaustive] pub enum GeoTrustBasis { + /// A dedicated ingress credential matched a deployment-selected secret. + /// The operator remains responsible for proxy metadata and protected transport. + AuthenticatedIngressHeader, /// Operator-declared credential-gated, network-isolated ALB path. /// This does not prove the external listener or network configuration. DeclaredProtectedAlb, @@ -365,6 +370,7 @@ impl GeoOutcome { /// Cloudflare's `XX` (unknown) or `T1` (Tor), means the platform has no usable /// geography rather than a forged assertion: an absent or unusable country is /// missing metadata, and an unusable subdivision leaves a country-only result. + /// `SpinIngress` is not platform metadata and returns `ProviderFailure` here. #[inline] #[must_use] pub fn platform(source: GeoSource, country: Option<&str>, subdivision: Option<&str>) -> Self { @@ -373,19 +379,24 @@ impl GeoOutcome { GeoSource::CloudFront => "cloudfront", GeoSource::Cloudflare => "cloudflare", GeoSource::Fastly => "fastly", + GeoSource::SpinIngress => "spin-ingress", } .to_owned(), ); - let status = match country.and_then(|raw| CountryCode::new(raw).ok()) { - None => GeoStatus::Unavailable(GeoUnavailableReason::MissingMetadata), - Some(country_code) => GeoStatus::Located { - location: GeoLocation::new( - country_code, - subdivision.and_then(|raw| SubdivisionCode::new(raw).ok()), - ), - source, - trust_basis: GeoTrustBasis::PlatformMetadata, - }, + let status = if source == GeoSource::SpinIngress { + GeoStatus::Error(GeoError::ProviderFailure) + } else { + match country.and_then(|raw| CountryCode::new(raw).ok()) { + None => GeoStatus::Unavailable(GeoUnavailableReason::MissingMetadata), + Some(country_code) => GeoStatus::Located { + location: GeoLocation::new( + country_code, + subdivision.and_then(|raw| SubdivisionCode::new(raw).ok()), + ), + source, + trust_basis: GeoTrustBasis::PlatformMetadata, + }, + } }; Self::Selected { provider, status } } @@ -399,6 +410,17 @@ mod tests { use std::rc::Rc; use std::str; + #[test] + fn ingress_source_cannot_be_labeled_as_platform_metadata() { + assert!(matches!( + GeoOutcome::platform(GeoSource::SpinIngress, Some("US"), Some("CA")), + GeoOutcome::Selected { + status: GeoStatus::Error(GeoError::ProviderFailure), + .. + } + )); + } + #[test] fn geo_country_codes_normalize_and_reject_unsupported() { assert_eq!(CountryCode::new("us").unwrap().as_str(), "US"); diff --git a/docs/guide/adapters/cloudflare.md b/docs/guide/adapters/cloudflare.md index d8ebb9c6..e9131988 100644 --- a/docs/guide/adapters/cloudflare.md +++ b/docs/guide/adapters/cloudflare.md @@ -107,6 +107,27 @@ selectors, so prefer `run_app` unless you are mocking a backend. Use [application retention](#retaining-an-application) with that function when the caller owns a prebuilt app and wants fresh per-request store bindings. +## Geographic context + +Managed dispatch (`run_app`, `dispatch_app`, and `CloudflareService`) automatically exposes +Cloudflare's request geography through `ctx.geo()`. No geo setting or store is required. +For `GeoOutcome::Selected` with `GeoStatus::Located`, read `location.country().as_str()` and +`location.subdivision().map(|code| code.as_str())` using the types in `edgezero_core::geo`. +The provider is `cloudflare`, source is `GeoSource::Cloudflare`, and trust basis is +`GeoTrustBasis::PlatformMetadata`. + +Country comes from `cf.country`; subdivision comes from `cf.regionCode` (for example `CA`), +not the descriptive `cf.region` (`California`). A valid country with absent or unusable +subdivision stays country-only. Missing or unusable country, including Cloudflare's `XX` +and `T1` placeholders, yields selected `GeoUnavailableReason::MissingMetadata`. +Neither `CF-IPCountry` nor CloudFront geographic headers provide a fallback. Public request +extensions cannot replace the framework-owned outcome, and a retained application receives +fresh geography on every dispatch. + +Geography is an estimate, not proof of residence, identity, or consent. Local Worker tests +with host-controlled metadata verify adapter wiring; they do not qualify Cloudflare's live +IP geolocation accuracy or an application's permission policy. + ## Ingress Body Conversion The converter preserves a genuine native Fetch request's null `body` as buffered empty, without diff --git a/docs/guide/adapters/spin.md b/docs/guide/adapters/spin.md index 87ed403c..2fb34633 100644 --- a/docs/guide/adapters/spin.md +++ b/docs/guide/adapters/spin.md @@ -325,6 +325,77 @@ manifest I/O or parsing. It does not initialize a logger, configure filters, rea runtime overrides or change `owns_logging`. Existing runner and application-owned logging responsibilities remain unchanged. +## Geographic context from trusted ingress + +Spin does not supply native country/region metadata. An application can enable +authenticated ingress assertions by inserting a `SpinGeoIngress` selection in its existing +`Hooks::configure` implementation: + +```rust +fn configure(app: &mut edgezero_core::app::App) -> Result<(), edgezero_core::EdgeError> { + app.insert_state(edgezero_adapter_spin::geo::SpinGeoIngress::new( + "geo_ingress_token", + )?); + Ok(()) +} +``` + +The constructor accepts a lowercase Spin variable name, not a credential. Bind the secret +in `spin.toml` (replace `my-app` with your component id): + +```toml +[variables] +geo_ingress_token = { required = true, secret = true } + +[component.my-app.variables] +geo_ingress_token = "{{ geo_ingress_token }}" +``` + +Supply the variable through your deployment's secret provider. Its value must be a +high-entropy credential of 32–128 ASCII bytes in the range `0x21`–`0x7e`; do not put it in source, logs, +application state, or command-line arguments. The adapter loads it for each admitted +request under the existing read deadline. There is one active credential; rotation requires +coordinating the proxy and variable update. + +The fronting proxy must remove all viewer-supplied instances of these fields and replace +them with its own geographic metadata and credential: + +| Header | Value | +| ------------------------ | ----------------------------------------------------------- | +| `x-edgezero-geo-country` | ISO country, such as `US` | +| `x-edgezero-geo-region` | Optional subdivision component, such as `CA`, without `US-` | +| `x-edgezero-geo-token` | The secret credential shared with Spin | + +For example, a fronting Cloudflare Worker can take assertions from `request.cf.country` and +`request.cf.regionCode`, rather than viewer headers. Build a new header set after deleting +the three fields above; set only known geographic values and inject the credential from a +Worker secret binding. Forward to a fixed HTTPS Spin origin with redirects disabled so the +credential cannot follow an origin redirect. Protect proxy-to-origin transport with TLS or +an isolated private network, redact the token in proxy logs, and restrict direct origin +access. Matching a bearer credential authenticates its holder; it does not verify the +proxy's geography or network configuration. Spin's `spin-client-addr` is not used as geo +authentication because its availability and duplicate handling vary by runtime. + +Managed `run_app`, `run_app_with_platform`, `dispatch_app`, and manual managed dispatch +consume the selection automatically. Successful authentication produces provider +`spin-ingress`, source `GeoSource::SpinIngress`, and trust basis +`GeoTrustBasis::AuthenticatedIngressHeader`. Read country and optional subdivision from +`GeoStatus::Located` through the same `ctx.geo()` interface as the other adapters. + +Missing, invalid, duplicated, or incorrect credentials yield selected `UntrustedIngress`. +Secret lookup failure or invalid secret configuration yields `GeoError::ProviderFailure`. +Authenticated missing geography yields `MissingMetadata`; malformed or duplicated geographic +fields yield `GeoError::InvalidAssertion`. A country without region remains country-only. +There is no fallback to `CF-IPCountry`, CloudFront headers, or a prior request's result. +These outcomes do not themselves choose an HTTP status or application permission policy. + +The adapter strips every token header before admission, middleware, and handler callbacks, +including when the selection is off. Its bytes still count toward original header limits. +Applications without the selection remain `NoSelection`. The unmanaged request converter +does not authenticate ingress. Local proxy/Spin fixtures prove the configured mechanism; +hosted metadata accuracy, transport protection, and downstream consent policy require +separate deployment qualification. + ## Context Access Access Spin-specific request metadata via the request context extensions: diff --git a/docs/guide/native-geo.md b/docs/guide/native-geo.md index aaec8b00..d4521771 100644 --- a/docs/guide/native-geo.md +++ b/docs/guide/native-geo.md @@ -230,9 +230,10 @@ extensions, and caller-supplied `ConnectInfo` cannot create Geo source admission callbacks run before Geo exists. Header changes or extension insertion/removal by application code cannot replace the managed outcome. Response finalization never resolves it again. -The unmanaged request converter, legacy dispatch, Fastly, Cloudflare, and Spin expose -`NoSelection`. Returning a context to an ordinary request and constructing a new unmanaged -context does not preserve its private Geo result. +The unmanaged request converter, legacy dispatch, and unconfigured Spin applications expose +`NoSelection`. Fastly and Cloudflare managed dispatch select their own platform geography +automatically; absent platform geography yields `MissingMetadata`. Returning a context to an +ordinary request and constructing a new unmanaged context does not preserve its private Geo result. ## CloudFront assertion rules diff --git a/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md b/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md new file mode 100644 index 00000000..22fa7fe5 --- /dev/null +++ b/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md @@ -0,0 +1,92 @@ +# Cloudflare and Spin geo implementation plan + +**Goal:** Satisfy #480 through existing Cloudflare/Axum integration and a configured authenticated ingress source on Spin. + +**Architecture:** Reuse #502 platform geo and Axum binding. Add one non-secret Spin App configuration, private credential capture/removal, deadline-bounded secret lookup after admission, and the existing immutable Geo outcome handoff. Use fixed geographic/token headers and a Spin variable reference. + +**Technology:** Pinned Rust 1.98.1, Node 24.20.0, worker/worker-build 0.8.5, wasm-bindgen 0.2.128, Spin SDK8 and runtime4.1.0, existing subtle comparison and bounded secret lookup. + +## 1. Scope, review and isolation + +- [x] Independently review the combined spec and this plan; resolve blocking and optional actionable findings. Obtain approval for the revised Spin design before production edits. +- [x] Preserve the owned `/private/tmp/edgezero-480` worktree on `feature/480-cloudflare-spin-geo`, based on #502 `8cd7af96`. Recheck parent head before publication and reassess relevant changes. +- [x] Replace the provisional Cloudflare-only docs with these approved documents under `docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md` and `docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md`. Keep private evidence outside the repository. + +## 2. Cloudflare contracts and guides + +**Files:** `crates/edgezero-adapter-cloudflare/tests/contract.rs`, `docs/guide/adapters/cloudflare.md`, `docs/guide/native-geo.md`. + +- [x] Retain/finish the already implemented managed matrix: service/run_app/dispatch_app, independent provider/source/trust/status assertions, US/CA vs DE/BE forged headers, region display name, lowercase/leading-zero subdivision, country-only, invalid region, XX/T1, no country and no metadata, sequential isolation. +- [x] Run scoped cargo test after every code edit. Execute WASM lib/contracts with `--features "cloudflare test-utils"` using the lock-matched runner and pinned Node. +- [x] Correct stale NoSelection claims. Explain country/subdivision outcomes, platform-only source, header rejection and local-versus-hosted limits. + +## 3. Spin geo selection and bounded assertion logic + +**Create:** `crates/edgezero-adapter-spin/src/geo.rs`. +**Modify:** `crates/edgezero-adapter-spin/src/lib.rs`, `crates/edgezero-core/src/geo.rs`. + +- [x] Write failing host tests for validated variable-name configuration; exact fixed-header capture; absent/duplicate/oversized/non-ASCII credentials; credential removal; normalized original limits; constant-time match/mismatch; no-selection/untrusted/error/country-only/Located outcomes; duplicate/invalid geographic assertions. +- [x] Export `geo` configuration on native as well as WASM, with runtime-only secret resolution gated appropriately. Constructor accepts a valid Spin variable name only, retaining no credential bytes. No new runtime dependencies. +- [x] Add truthful non-exhaustive provenance variants for authenticated Spin ingress. Resolve provider label through existing validated ID APIs. Keep `GeoOutcome::platform`'s existing signature; for unsupported `SpinIngress`, return selected `spin-ingress` with `ProviderFailure`, document it and test it cannot yield Located/PlatformMetadata. The authenticated ingress resolver constructs outcomes directly. Ensure unavailable/error results retain the selected identity. +- [x] Implement minimal pure capture/validation/resolution helpers and independently typed outcome tests. Use GeoAssertion/CountryCode/SubdivisionCode, do not clone all request headers for the source input. Secret comparison uses existing subtle dependency. +- [x] Run `cargo +1.98.1 test --locked -p edgezero-core -p edgezero-adapter-spin` after each logical code edit. Confirm source-established failing cases then passing behavior before integrating dispatch. + +## 4. Spin production dispatch and preservation tests + +**Modify:** `crates/edgezero-adapter-spin/src/request.rs`; extend colocated WASM tests and/or `tests/contract.rs` using existing test-support machinery. + +- [x] At the shared managed ingress function, obtain a clone of non-secret selection from App state; capture/strip every fixed token header privately. Validate original normalized head before removal can reduce budgets, drop original cloned head, and construct sanitized head for admission. +- [x] Ensure source construction, variable fetch and provider work happen only after Admitted. Preserve existing refused/aborted, body-laziness and response-egress paths. No credentials enter callbacks, App state or public extensions. +- [x] Resolve configured variable using existing `secret_store::bounded_secret_read` or bounded SecretStore consumer under `PreparedIngress::read_deadline`, with max expected credential128 bytes and validation min32 ASCII bytes. Missing/error/invalid config becomes a category-only Geo provider error; no raw SDK error propagation/logging. +- [x] Produce NoSelection when no configuration; UntrustedIngress for invalid/missing/mismatching token; authenticated assertions resolved once; pass geo to dispatch_admitted_with_geo with existing framework-error detail. +- [x] Regression tests cover no secret fetch on rejected/aborted admission or absent/structurally invalid/duplicate tokens; well-formed mismatches perform one bounded lookup. Also cover original header budget failure, sanitized admission views, private immutability, unchanged body handling and sequence isolation. Use test-only injection seam only for secret backend failures/deadlines; normal Spin runtime must also exercise the actual variable provider. +- [x] Run scoped cargo tests after each edit, then native strict Clippy and WASM compilation to catch cfg-only errors. + +## 5. Normal runtime qualification + +- [x] Retain executed Cloudflare runtime evidence if production inputs remain identical; otherwise rerun affected cases. Actual built fetch -> run_app -> action, Miniflare host-controlled cf (explicit empty base cf to avoid fallback), typed assertions and source/artifact hashes. Runtime-only dependencies stay task-owned. +- [x] Build an isolated Spin SDK8 fixture with real HTTP handler -> run_app::; configure SpinGeoIngress from Hooks, actual declared Spin secret variable, ordinary/body/geo routes and admission/middleware token-absence observations. Use installed verified Spin4.1.0 binary, not default4.0. +- [x] Start owned loopback Spin and fronting proxy processes. Proxy must remove all viewer assertions/token, inject metadata from a controlled host fixture and its credential, and forward to Spin. Do not expose a header switch that enables authentication inside the Rust app. +- [x] Prove US/CA, country-only, missing/malformed/duplicate assertions, direct/wrong/missing/duplicate credentials, viewer spoof replacement, repeated requests, off-mode and body/routes, credential removal at callback boundaries and original header-size enforcement. Correlate typed source/trust/provider output and artifact identity. Stop owned resources after preserving sanitized evidence. +- [x] Run existing Axum production-hosting geo manifest/settings acceptance test; establish country/region without TS profile. Do not claim deployed CloudFront/ALB configuration. +- [x] Report independent runtime verdicts for CF, Spin and Axum, separating real SDK/runtime execution with fixtures from hosted metadata accuracy and transport qualification. Failed or blocked required scope cannot be relabeled VERIFIED. + +## 6. Documentation, full gates and fresh review + +**Modify:** `docs/guide/adapters/spin.md`, current native/Cloudflare guides and approved spec/plan. + +- [x] Document exact Hooks configuration, fixed headers, `[variables]`/component variable binding, credential entropy/size, missing/failure semantics, proxy replacement/HTTPS/isolation requirements, rotation limitation and default-off behavior. Explain that stock Spin does not perform geolocation. +- [x] Execute `cargo +1.98.1 fmt --all -- --check`; `cargo +1.98.1 clippy --workspace --all-targets --all-features -- -D warnings`; `cargo +1.98.1 test --workspace --all-targets`; `cargo +1.98.1 check --workspace --all-targets --features "fastly cloudflare spin"`; `cargo +1.98.1 check -p edgezero-adapter-spin --target wasm32-wasip2 --features spin`. +- [x] Execute affected Cloudflare WASM suites, Spin WASM contracts/runtime tests, docs lint/format/build and git diff --check; run `cargo +1.98.1 test --offline --locked --manifest-path crates/edgezero-test-harness/Cargo.toml` plus its acceptance manifest/coverage checks. Inspect `scripts/run_tests.sh` and execute its applicable equivalent checks (dependency/forwarding checks, native feature matrices, adapter contracts, app-demo workspace and WASM compilation, generated-consumer and documentation contracts), recording any missing tools/existing failures separately. Pin versions, revision/tree and exact outcomes. +- [x] Fresh independent implementation review against full requirements and affected unchanged consumers. Resolve all blocking and optional actionable findings and rerun affected checks. + +## 7. Draft PR and fresh local self-review + +- [ ] Before committing explain implemented behavior, tradeoffs and verification limits. Explicitly sign commits, verify locally, push new branch normally, and confirm GitHub Verified per new SHA. +- [ ] Create draft PR assigned to current user using repository template/pr-creator instructions, base #502. Explain stacking and combined acceptance accurately; use Closes #480 only if all required scoped acceptance is demonstrated. Follow authorized project-board handling while preserving advanced statuses. +- [ ] Perform fresh independent local self-review of full PR against merge base and relevant unchanged paths; recheck live head/base and required gates. Resolve findings under user's implementation authorization, repeat affected verification and update draft. +- [ ] Final report: understandable behavior/corrections, exact revision, runtime/control results and limits, local checks vs hosted CI, signatures/publication URL, findings state and owned-resource cleanup. Preserve implementation worktree/unpublished work; remove only clean disposable review resources. + +## Local qualification checkpoint + +The implementation reuses #502's Cloudflare/Fastly metadata and Axum manifest binding. +The additional Spin source is enabled explicitly by `SpinGeoIngress` configuration. + +| Boundary | Executed evidence | Scope | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Cloudflare platform input | 141 WASM library tests, 31 managed contracts, 15 built Worker runtime cases | Local workerd with host-controlled metadata; normal fetch-to-run_app path | +| Spin ingress source | Five pure helper tests, 37 WASM contracts, 25 SDK resource contracts, 47 built component runtime cases | Actual Spin variable provider in the normal run_app runtime fixture; contracts inject an in-memory secret store through the same managed dispatch pipeline | +| Regression discrimination | Managed contract fails when token stripping is removed or the private outcome is dropped; restored source passes | Owned disposable source copy; production worktree unmodified by controls | +| Axum manifest selection | Existing production-hosting manifest/settings test returns US/CA without a Trusted Server boot profile | Local real listener; external CloudFront/ALB configuration not qualified | + +The generic Wasmtime contract runner cannot execute the entire Spin library test binary: +that binary imports Spin-specific KV host interfaces. The maintained CI path executes +`contract` and `sdk_resources`; those suites pass. Changed pure helper tests also execute +natively, and the real Spin fixture covers the actual secret backend. No generic-runner +result is represented as live Spin service evidence. + +Runtime checks do not establish hosted IP geolocation accuracy, deployed proxy header +replacement, transport isolation, or Trusted Server consent behavior. Those remain deployment +qualification obligations rather than changes to application policy. + +The required root gates, 32 native feature combinations, generated-project checks, app-demo tests and WASM builds, 178 tooling tests, and dependency checks passed. The isolated harness passed all 672 cases with four existing ignored cases under serial scheduling and unchanged deadlines. Its initial concurrent run encountered an uncached fixture dependency and process observation timeouts; locked fixture fetch plus the serial run resolved local qualification without source or timeout changes. diff --git a/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md b/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md new file mode 100644 index 00000000..9cb70a80 --- /dev/null +++ b/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md @@ -0,0 +1,50 @@ +# Cloudflare and Spin geographic context + +## Requirements and existing implementation + +Issue #480 requires country and first-level region through `ctx.geo()` on Cloudflare and Spin, with Axum's CloudFront selection driven by EdgeZero's manifest rather than Trusted Server configuration. Fastly preserves its existing geo. This supersedes the earlier Cloudflare-only proposal following scope clarification. + +Stack on PR #502 (`spec/482-axum-geo-manifest-binding`, initial head `8cd7af96e94778df359e7ffed05be595fbfd901f`). It already implements Cloudflare platform metadata, Fastly geo, and Axum manifest binding. Reuse that code and test the combined acceptance. Do not import unrelated later #439 changes or implement a second copy on main. + +## Cloudflare + +Keep automatic platform selection. Read `cf.country` and `cf.regionCode`, never a client header or descriptive `region`. Preserve normalization, country-only results when subdivision is absent/unusable, and selected `MissingMetadata` for absent/unusable country including XX/T1. Strengthen managed contracts with independent field expectations, conflicting header values, and sequences through `run_app` and retained-app `dispatch_app`. + +## Spin source and configuration + +Spin has no native geographic object. Choose the issue's trusted-ingress option: a deployment-controlled fronting proxy supplies geographic assertions and authenticates them with a dedicated shared credential. This avoids adding asynchronous IP lookup, a dataset, or a provider vendor. + +Introduce `edgezero_adapter_spin::geo::SpinGeoIngress`, a validated non-secret configuration value enabled by inserting it into App state from `Hooks::configure`. Its constructor takes the Spin variable name containing the credential. The dedicated headers are fixed: `x-edgezero-geo-country`, `x-edgezero-geo-region`, `x-edgezero-geo-token`. Configuration stores only the variable name; credential bytes never enter App state, extensions, diagnostics or normal callback views. An app without this configuration remains `NoSelection`. This requires no change to Axum's manifest schema or existing provider trait. + +The normal Spin `run_app`, `run_app_with_platform`, and `dispatch_app` paths consume this state automatically through their shared request dispatch. Manual managed dispatcher paths with the configured App also receive the same treatment. Unmanaged request conversion retains its established contract and is not an authentication entry point. + +Spin client-address headers are not a portable authentication source: pinned Spin runtime code retains user fields alongside generated metadata, and some runtimes omit client address entirely. Do not use the existing `.get("spin-client-addr")` as proof of ingress identity. + +## Admission and credential handling + +1. Privately capture at most one token, rejecting duplicate, empty, malformed or oversized values. Strip every token header from the managed request, even when geo is off. Validate original normalized header budgets so removing the token cannot bypass size/count limits. Admission callbacks receive a newly constructed sanitized head; the original head snapshot must not survive into them. +2. Keep no body read, secret lookup or geo resolution before successful request admission. Refused/aborted ingress retains its existing lifecycle. +3. With geo enabled, missing/invalid/duplicate token means selected `UntrustedIngress`, with no secret lookup. Otherwise asynchronously load the configured Spin variable under the admitted read deadline and the existing bounded-secret mechanism. Expected credentials must be 32–128 ASCII token bytes; use synthetic credentials only in tests. Lookup failure, missing variable, invalid credential configuration or deadline expiry produces a bounded provider failure outcome, never a permissive fallback or exposed backend error. +4. Compare equal-length validated credentials with the existing constant-time dependency. Length is not secret; do not claim memory zeroization or host allocation limits that the SDK cannot provide. +5. Only after matching the credential, capture bounded country/subdivision assertions. Identical or conflicting duplicate geographic fields, oversize, malformed, or subdivision-without-country assertions are invalid. Both fields absent means selected `MissingMetadata`; valid country with absent subdivision is country-only. Reuse existing CountryCode/SubdivisionCode/GeoAssertion semantics. Invalid authenticated assertions yield `InvalidAssertion`, preserving the distinction from a missing platform estimate. +6. Pass one owned outcome through `dispatch_admitted_with_geo` before router middleware/handlers. Public extensions or mutations of header fields cannot change it. Use truthful provenance `SpinIngress` and `AuthenticatedIngressHeader`, with a documented provider label `spin-ingress`; this does not claim Spin platform geolocation or a verified network topology. + +Keep APIs minimal: fixed headers, one variable-name selection, existing secret lookup/timer machinery, existing admitted outcome handoff, no new I/O-capable provider trait. Core source/trust enums are already non-exhaustive; their extension must not broaden platform-specific constructors to fabricate Spin platform provenance. + +## Deployment contract + +The upstream proxy must obtain country/subdivision from its own trusted platform metadata, remove every viewer-supplied geographic/token header, replace assertions, and inject a high-entropy credential from secret storage. Proxy-to-Spin transport must be protected with TLS or an isolated private loopback/network; the credential is a bearer secret. The origin must not forward/echo the credential, and proxy logs must redact it. Rotate through coordinated proxy/variable updates; this version supports one active credential and makes no zero-downtime rotation promise. + +Document both the supported header/variable binding and an example using a fronting platform's native geography. This is operator-configured ingress support, not automatic stock Spin geography or an IP geolocation service. Required local verification proves this mechanism through a disposable proxy and real Spin runtime. Actual hosted proxy configuration, metadata accuracy, transport isolation and Trusted Server adoption require separate deployment qualification. + +## Acceptance and preservation evidence + +- Cloudflare built Worker: US/CA, country-only, missing/XX/T1, header spoof rejection, request isolation, ordinary and missing routes, through the actual normal entry point under host-controlled metadata. +- Spin built component and local proxy: same country/region consumption through normal `run_app`; direct/missing/wrong/duplicate credential cannot obtain Located; authenticated malformed/duplicate assertions fail; token invisible to admission/middleware/handler; original header budgets still apply; private outcome survives extension tampering; off mode stays NoSelection; repeated requests and ordinary body/routes preserve behavior. Distinguish fixture platform metadata from deployed geolocation. +- Axum: execute the existing production-hosting manifest-selection test demonstrating country/region without a Trusted Server profile. No Axum production changes are planned. +- Run required Rust format, strict Clippy, workspace tests, feature compilation and Spin WASM check, plus Cloudflare WASM lib/contracts and affected Spin native/WASM/runtime suites. Documentation lint/format/build use pinned Node. +- Fresh independent design/plan, implementation and final self-reviews must reconcile all actionable blocking and optional findings. Create a signed, GitHub-verified draft PR against #502 after the required local gates pass. Closing #480 is justified only when all above acceptance evidence is established; otherwise retain the missing scope explicitly. + +## Alternatives + +CIDR admission based on `spin-client-addr` would depend on individual runtimes' treatment of user-supplied duplicates and omissions. A credential gate avoids that portability dependency. KV/API geo lookup needs a separate typed-IP/async provider contract and dataset/vendor decisions; the current synchronous GeoProvider expressly forbids I/O. Neither is needed for the supported trusted-ingress option. From b04f9ccd2d8579afeb8a4c85ba93cb436e7140a7 Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Wed, 18 Nov 2026 18:11:42 +0530 Subject: [PATCH 2/4] Tighten Spin geo configuration and production coverage --- crates/edgezero-adapter-spin/src/geo.rs | 16 +++- .../src/request/test_support.rs | 33 ++++++-- .../edgezero-adapter-spin/tests/contract.rs | 78 +++++++++++++++++-- docs/guide/adapters/spin.md | 15 ++++ .../plans/2026-11-18-cloudflare-spin-geo.md | 4 +- .../2026-11-18-cloudflare-spin-geo-design.md | 2 +- 6 files changed, 130 insertions(+), 18 deletions(-) diff --git a/crates/edgezero-adapter-spin/src/geo.rs b/crates/edgezero-adapter-spin/src/geo.rs index cb53008a..b311b98b 100644 --- a/crates/edgezero-adapter-spin/src/geo.rs +++ b/crates/edgezero-adapter-spin/src/geo.rs @@ -26,12 +26,15 @@ impl SpinGeoIngress { /// Select the Spin variable containing the expected ingress credential. /// /// # Errors - /// Rejects names outside `[a-z][a-z0-9_]{0,63}`. The credential itself is + /// Rejects names outside `[a-z][a-z0-9_]{0,63}`, trailing underscores, and + /// consecutive underscores, matching Spin's variable key rules. The credential is /// loaded per admitted request and is never retained in application state. #[inline] pub fn new(credential_variable: &str) -> Result { if credential_variable.is_empty() || credential_variable.len() > 64 + || credential_variable.ends_with('_') + || credential_variable.contains("__") || !credential_variable .as_bytes() .first() @@ -261,7 +264,16 @@ mod tests { .credential_variable(), "geo_token" ); - for name in ["", "GEO_TOKEN", "a-b", "1token", "a token", &"a".repeat(65)] { + for name in [ + "", + "GEO_TOKEN", + "a-b", + "1token", + "a token", + "a_", + "a__b", + &"a".repeat(65), + ] { assert!(SpinGeoIngress::new(name).is_err(), "{name}"); } } diff --git a/crates/edgezero-adapter-spin/src/request/test_support.rs b/crates/edgezero-adapter-spin/src/request/test_support.rs index 2a00416f..bb0537a4 100644 --- a/crates/edgezero-adapter-spin/src/request/test_support.rs +++ b/crates/edgezero-adapter-spin/src/request/test_support.rs @@ -6,19 +6,23 @@ use edgezero_core::http::Uri; use edgezero_core::http::request_builder; use edgezero_core::secret_store::{SecretError, SecretStore, finish_bounded_secret_read}; use std::future::pending; +use std::sync::atomic::{AtomicUsize, Ordering}; -pub(super) struct GeoSecret(Option); +pub(super) struct GeoSecret(Option, Option>); #[cfg(test)] impl GeoSecret { pub(super) fn missing() -> Self { - Self(None) + Self(None, None) } } #[async_trait::async_trait(?Send)] impl SecretStore for GeoSecret { async fn get_bytes(&self, _store: &str, _key: &str) -> Result, SecretError> { + if let Some(reads) = &self.1 { + reads.fetch_add(1, Ordering::SeqCst); + } Ok(self.0.clone()) } @@ -31,6 +35,20 @@ impl SecretStore for GeoSecret { max_backend_bytes: u64, max_value_bytes: u64, ) -> Result, SecretError> { + if self.1.is_some() { + assert_eq!( + max_backend_bytes, 128, + "geo lookup must bound backend credential bytes" + ); + assert_eq!( + max_value_bytes, 128, + "geo lookup must bound returned credential bytes" + ); + assert!( + !deadline.is_expired_at(clock.now()), + "admitted lookup must receive a live request deadline" + ); + } finish_bounded_secret_read( self.get_bytes(store_name, key).await, clock, @@ -87,7 +105,7 @@ where move || Ok(source), |_| pending::<()>(), Ok, - &GeoSecret(None), + &GeoSecret(None, None), ) .await } @@ -122,7 +140,7 @@ where make_source, |_| pending::<()>(), deliver, - &GeoSecret(None), + &GeoSecret(None, None), ) .await } @@ -157,7 +175,7 @@ where move || Ok(source), make_timer, Ok, - &GeoSecret(None), + &GeoSecret(None, None), ) .await } @@ -172,7 +190,7 @@ pub async fn dispatch_request( app: &App, req: SpinRequest, ) -> anyhow::Result { - dispatch_request_with_geo_secret(app, req, None).await + dispatch_request_with_geo_secret(app, req, None, None).await } /// Uses the production converter and managed ingress with an in-memory credential backend. @@ -186,6 +204,7 @@ pub async fn dispatch_request_with_geo_secret( app: &App, req: SpinRequest, secret: Option, + reads: Option>, ) -> anyhow::Result { let request_start = app.monotonic_now(); let (parts, native_body) = req.into_parts(); @@ -198,7 +217,7 @@ pub async fn dispatch_request_with_geo_secret( move || Ok(native_body.stream()), sleep, Ok, - &GeoSecret(secret), + &GeoSecret(secret, reads), ) .await } diff --git a/crates/edgezero-adapter-spin/tests/contract.rs b/crates/edgezero-adapter-spin/tests/contract.rs index e1eae0cb..ce4cd4da 100644 --- a/crates/edgezero-adapter-spin/tests/contract.rs +++ b/crates/edgezero-adapter-spin/tests/contract.rs @@ -1052,12 +1052,14 @@ mod tests { } }); let duplicate = "0123456789abcdef0123456789abcdef"; - for tokens in [ - &[][..], - &["short"][..], - &[duplicate, duplicate][..], - &[duplicate][..], + for (tokens, expected_reads) in [ + (&[][..], 0_usize), + (&["short"][..], 0), + (&[duplicate, duplicate][..], 0), + (&[duplicate][..], 1), + (&["fedcba9876543210fedcba9876543210"][..], 1), ] { + let reads = Arc::new(AtomicUsize::new(0)); let mut outgoing = SpinRequest::builder() .method("GET") .uri("http://example.test/geo") @@ -1081,12 +1083,17 @@ mod tests { &app, incoming, Some(Bytes::from_static(b"0123456789abcdef0123456789abcdef")), + Some(Arc::clone(&reads)), ) .await .expect("managed response"); assert_eq!(captured_body(response).as_ref(), b"observed"); + assert_eq!( + reads.load(Ordering::SeqCst), + if enabled { expected_reads } else { 0 } + ); } - assert_eq!(admissions.load(Ordering::SeqCst), 4); + assert_eq!(admissions.load(Ordering::SeqCst), 5); app.set_ingress_head_limits( IngressHeadLimits::default() .with_max_request_header_bytes(1024) @@ -1111,13 +1118,70 @@ mod tests { ); assert_eq!( admissions.load(Ordering::SeqCst), - 4, + 5, "stripping must not evade original header budget" ); } }); } + #[test] + fn configured_geo_does_not_read_secrets_before_admission() { + use edgezero_adapter_spin::geo::SpinGeoIngress; + sdk_block_on(async { + for abort in [false, true] { + let mut app = App::new(RouterService::builder().build()); + app.insert_state(SpinGeoIngress::new("geo_token").expect("selection")); + app.set_ingress_admission_policy(move |head| { + assert!(!head.headers().contains_key("x-edgezero-geo-token")); + if abort { + AdmissionDecision::Abort + } else { + AdmissionDecision::Refuse { + completion: ResponseEgressCompletion::empty(), + response: response_builder() + .status(StatusCode::SERVICE_UNAVAILABLE) + .body(Body::empty()) + .expect("refusal"), + } + } + }); + let secret = Bytes::from_static(b"0123456789abcdef0123456789abcdef"); + let request = SpinRequest::builder() + .method("GET") + .uri("http://example.test/geo") + .header("content-length", "0") + .header("x-edgezero-geo-token", "0123456789abcdef0123456789abcdef") + .body(http_body_util::Full::new(Bytes::new())) + .expect("request"); + let incoming = + SpinRequest::from_request(request.into_request().expect("WASI request")) + .expect("incoming request"); + let reads = Arc::new(AtomicUsize::new(0)); + let result = dispatch_request_with_geo_secret( + &app, + incoming, + Some(secret), + Some(Arc::clone(&reads)), + ) + .await; + match (abort, result) { + (true, Err(_)) => {} + (false, Ok(response)) => assert_eq!( + capture_response(response).status(), + StatusCode::SERVICE_UNAVAILABLE + ), + _ => panic!("admission decision must precede geo lookup"), + } + assert_eq!( + reads.load(Ordering::SeqCst), + 0, + "rejected admission must not fetch the credential" + ); + } + }); + } + #[test] fn standard_native_request_refuses_before_body_read() { sdk_block_on(async { diff --git a/docs/guide/adapters/spin.md b/docs/guide/adapters/spin.md index 2fb34633..614ef430 100644 --- a/docs/guide/adapters/spin.md +++ b/docs/guide/adapters/spin.md @@ -340,6 +340,8 @@ fn configure(app: &mut edgezero_core::app::App) -> Result<(), edgezero_core::Edg } ``` +Install this selection in adapter-local Hooks so shared handlers depend only on `ctx.geo()`. +This is a Rust opt-in capability; there is currently no `[adapters.spin.geo]` manifest switch. The constructor accepts a lowercase Spin variable name, not a credential. Bind the secret in `spin.toml` (replace `my-app` with your component id): @@ -357,6 +359,13 @@ application state, or command-line arguments. The adapter loads it for each admi request under the existing read deadline. There is one active credential; rotation requires coordinating the proxy and variable update. +Spin variables can use local or remote secret providers. This adapter reads the variable +once for each admitted request with a syntactically valid token, including a wrong token. +Environment-backed lookup is local; providers such as Vault or Azure Key Vault can perform +remote I/O on each read. Qualify the chosen provider's latency, throughput, and cost, and +restrict origin access so arbitrary internet traffic cannot amplify secret-provider calls. +The request deadline bounds guest waiting; it does not prove cancellation of remote work. + The fronting proxy must remove all viewer-supplied instances of these fields and replace them with its own geographic metadata and credential: @@ -389,6 +398,12 @@ fields yield `GeoError::InvalidAssertion`. A country without region remains coun There is no fallback to `CF-IPCountry`, CloudFront headers, or a prior request's result. These outcomes do not themselves choose an HTTP status or application permission policy. +Geographic assertions do not partition shared caches. Responses whose authorization or +consent policy depends on geography, including error responses, need an appropriate cache +policy at the application and proxy. Do not reuse a response across locations merely because +the URL matches. Applications that require verified geography must reject unavailable/error +states explicitly; authenticating assertions is not blanket origin access control. + The adapter strips every token header before admission, middleware, and handler callbacks, including when the selection is off. Its bytes still count toward original header limits. Applications without the selection remain `NoSelection`. The unmanaged request converter diff --git a/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md b/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md index 22fa7fe5..f88c9cf5 100644 --- a/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md +++ b/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md @@ -75,7 +75,7 @@ The additional Spin source is enabled explicitly by `SpinGeoIngress` configurati | Boundary | Executed evidence | Scope | | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cloudflare platform input | 141 WASM library tests, 31 managed contracts, 15 built Worker runtime cases | Local workerd with host-controlled metadata; normal fetch-to-run_app path | -| Spin ingress source | Five pure helper tests, 37 WASM contracts, 25 SDK resource contracts, 47 built component runtime cases | Actual Spin variable provider in the normal run_app runtime fixture; contracts inject an in-memory secret store through the same managed dispatch pipeline | +| Spin ingress source | Five pure helper tests, 38 WASM contracts, 25 SDK resource contracts, 47 built component runtime cases | Actual Spin variable provider in the normal run_app runtime fixture; contracts inject an in-memory secret store through the same managed dispatch pipeline | | Regression discrimination | Managed contract fails when token stripping is removed or the private outcome is dropped; restored source passes | Owned disposable source copy; production worktree unmodified by controls | | Axum manifest selection | Existing production-hosting manifest/settings test returns US/CA without a Trusted Server boot profile | Local real listener; external CloudFront/ALB configuration not qualified | @@ -90,3 +90,5 @@ replacement, transport isolation, or Trusted Server consent behavior. Those rema qualification obligations rather than changes to application policy. The required root gates, 32 native feature combinations, generated-project checks, app-demo tests and WASM builds, 178 tooling tests, and dependency checks passed. The isolated harness passed all 672 cases with four existing ignored cases under serial scheduling and unchanged deadlines. Its initial concurrent run encountered an uncached fixture dependency and process observation timeouts; locked fixture fetch plus the serial run resolved local qualification without source or timeout changes. + +Review follow-up: constructor validation matches Spin variable-key underscore rules. The managed backend contract observes zero reads for disabled, structurally invalid and rejected/aborted requests, and one bounded read for valid or well-formed mismatching credentials. Production guidance distinguishes local versus remote variable providers, shared cache policy, and programmatic opt-in from deploy-only selection. diff --git a/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md b/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md index 9cb70a80..74780c9b 100644 --- a/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md +++ b/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md @@ -47,4 +47,4 @@ Document both the supported header/variable binding and an example using a front ## Alternatives -CIDR admission based on `spin-client-addr` would depend on individual runtimes' treatment of user-supplied duplicates and omissions. A credential gate avoids that portability dependency. KV/API geo lookup needs a separate typed-IP/async provider contract and dataset/vendor decisions; the current synchronous GeoProvider expressly forbids I/O. Neither is needed for the supported trusted-ingress option. +CIDR admission based on `spin-client-addr` would depend on individual runtimes' treatment of user-supplied duplicates and omissions. A credential gate avoids that portability dependency. PR [#454](https://github.com/IABTechLab/edgezero/pull/454), reviewed at `925fe019`, already provides a portable asynchronous KV resolver and managed Axum serving. A Spin KV integration can reuse that reader, but still needs trusted viewer-IP admission, a KV binding, preparation/readiness, lookup budgets and cache-lifetime integration. The synchronous GeoProvider remains assertion-only and must not perform I/O. The ingress option is appropriate when a deployment already has trusted geographic assertions; it does not claim to supply standalone Spin IP lookup. From c6fcb9cedfbffecc836a89df1a7826e53b0b7685 Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Wed, 18 Nov 2026 19:54:06 +0530 Subject: [PATCH 3/4] feat(spin): resolve geo from pinned KV datasets --- .github/workflows/test.yml | 10 + crates/edgezero-adapter-axum/src/geo.rs | 29 + crates/edgezero-adapter-spin/Cargo.toml | 4 +- crates/edgezero-adapter-spin/src/geo.rs | 625 +++---- .../edgezero-adapter-spin/src/geo/kv_tests.rs | 472 +++++ crates/edgezero-adapter-spin/src/lib.rs | 23 +- .../src/outbound/test_support.rs | 1 + crates/edgezero-adapter-spin/src/request.rs | 15 +- .../src/request/test_support.rs | 22 +- .../edgezero-adapter-spin/tests/contract.rs | 322 ++-- crates/edgezero-core/src/env_config.rs | 28 + crates/edgezero-core/src/geo.rs | 42 +- crates/edgezero-core/src/manifest.rs | 51 +- docs/guide/adapters/spin.md | 163 +- .../plans/2026-11-18-cloudflare-spin-geo.md | 117 +- .../2026-11-18-cloudflare-spin-geo-design.md | 51 +- examples/geo-kv-prototype/Cargo.toml | 1 + examples/geo-kv-prototype/README.md | 19 +- examples/geo-kv-prototype/src/lib.rs | 4 + examples/geo-kv-prototype/src/main.rs | 4 +- examples/geo-kv-prototype/src/publication.rs | 10 +- examples/geo-spin-loader/.gitignore | 3 + examples/geo-spin-loader/Cargo.lock | 1622 +++++++++++++++++ examples/geo-spin-loader/Cargo.toml | 16 + examples/geo-spin-loader/README.md | 89 + examples/geo-spin-loader/load.py | 160 ++ examples/geo-spin-loader/spin.toml | 19 + examples/geo-spin-loader/src/lib.rs | 112 ++ examples/geo-spin-loader/test_load.py | 84 + 29 files changed, 3391 insertions(+), 727 deletions(-) create mode 100644 crates/edgezero-adapter-spin/src/geo/kv_tests.rs create mode 100644 examples/geo-kv-prototype/src/lib.rs create mode 100644 examples/geo-spin-loader/.gitignore create mode 100644 examples/geo-spin-loader/Cargo.lock create mode 100644 examples/geo-spin-loader/Cargo.toml create mode 100644 examples/geo-spin-loader/README.md create mode 100644 examples/geo-spin-loader/load.py create mode 100644 examples/geo-spin-loader/spin.toml create mode 100644 examples/geo-spin-loader/src/lib.rs create mode 100644 examples/geo-spin-loader/test_load.py diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 8ac81520..fbaf01b0 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -71,6 +71,7 @@ jobs: cargo fetch --locked cargo fetch --locked --manifest-path examples/app-demo/Cargo.toml cargo fetch --locked --manifest-path examples/geo-kv-prototype/Cargo.toml + cargo fetch --locked --manifest-path examples/geo-spin-loader/Cargo.toml cargo fetch --locked --manifest-path crates/edgezero-test-harness/fixtures/reusable-app/Cargo.toml cargo fetch --locked --manifest-path crates/edgezero-test-harness/Cargo.toml cargo fetch --locked --manifest-path crates/edgezero-test-harness/fixtures/request-fidelity/Cargo.toml @@ -228,6 +229,15 @@ jobs: cargo check --offline --locked -p edgezero-core --no-default-features --features geo-kv --target wasm32-unknown-unknown scripts/run_test_nonzero.sh kv_geo_listener_checks_reader_provenance_and_pinned_objects cargo test --offline --locked -p edgezero-adapter-axum --features geo-kv,geo-cloudfront,test-utils --test production_hosting kv_geo + - name: Spin KV operator loader + if: matrix.suite == 'workspace' + run: | + cargo fmt --manifest-path examples/geo-spin-loader/Cargo.toml -- --check + cargo clippy --offline --locked --manifest-path examples/geo-spin-loader/Cargo.toml --all-targets -- -D warnings + cargo test --offline --locked --manifest-path examples/geo-spin-loader/Cargo.toml + cargo check --offline --locked --manifest-path examples/geo-spin-loader/Cargo.toml --target wasm32-wasip2 + python3 -m unittest discover -s examples/geo-spin-loader -p test_load.py + - name: Native Geo public examples run: cargo test --offline --locked -p edgezero-adapter-axum --features geo-cloudfront --doc diff --git a/crates/edgezero-adapter-axum/src/geo.rs b/crates/edgezero-adapter-axum/src/geo.rs index 4731373b..d5c36fe4 100644 --- a/crates/edgezero-adapter-axum/src/geo.rs +++ b/crates/edgezero-adapter-axum/src/geo.rs @@ -305,6 +305,12 @@ fn configured_selection( env: &EnvConfig, defaults: Option<&ManifestAdapterGeo>, ) -> Result { + if env + .get(&["adapter", "geo", "credential_variable"]) + .is_some() + { + return Err(NativeGeoConfigError::InvalidSelection); + } let env_provider = env.get(&["adapter", "geo", "provider"]); let env_networks = env.get(&["adapter", "geo", "alb_peer_cidrs"]); let env_header = env.get(&["adapter", "geo", "origin_credential_header_name"]); @@ -791,6 +797,29 @@ mod tests { } } + #[test] + fn axum_rejects_spin_credential_override() { + struct NoGeo; + #[expect( + clippy::missing_trait_methods, + reason = "fixture retains unused Hooks defaults" + )] + impl Hooks for NoGeo { + fn routes() -> Result { + Ok(RouterService::builder().build()) + } + } + let options = AxumRunOptions::from_vars([( + "EDGEZERO__ADAPTER__GEO__CREDENTIAL_VARIABLE", + "geo_token", + )]) + .unwrap(); + assert_eq!( + options.geo_capability_for::(), + Err(NativeGeoConfigError::InvalidSelection) + ); + } + #[test] fn geo_capability_for_applies_the_app_manifest() { struct GeoApp; diff --git a/crates/edgezero-adapter-spin/Cargo.toml b/crates/edgezero-adapter-spin/Cargo.toml index 373758c3..d66460e9 100644 --- a/crates/edgezero-adapter-spin/Cargo.toml +++ b/crates/edgezero-adapter-spin/Cargo.toml @@ -17,7 +17,7 @@ test-utils = ["edgezero-core/test-utils"] cli = ["dep:edgezero-adapter", "edgezero-adapter/cli", "dep:ctor", "dep:rusqlite", "dep:toml", "dep:toml_edit", "dep:walkdir"] [dependencies] -edgezero-core = { path = "../edgezero-core" } +edgezero-core = { path = "../edgezero-core", features = ["geo-kv"] } edgezero-adapter = { path = "../edgezero-adapter", optional = true, features = ["cli"] } anyhow = { workspace = true } async-stream = { workspace = true } @@ -45,6 +45,6 @@ walkdir = { workspace = true, optional = true } rusqlite = { workspace = true, optional = true } [dev-dependencies] -edgezero-core = { path = "../edgezero-core", features = ["test-utils"] } +edgezero-core = { path = "../edgezero-core", features = ["test-utils", "geo-kv-build"] } http-body-util = { workspace = true } tempfile = { workspace = true } diff --git a/crates/edgezero-adapter-spin/src/geo.rs b/crates/edgezero-adapter-spin/src/geo.rs index b311b98b..121b60a8 100644 --- a/crates/edgezero-adapter-spin/src/geo.rs +++ b/crates/edgezero-adapter-spin/src/geo.rs @@ -1,391 +1,344 @@ -//! Authenticated ingress geography for Spin deployments. +//! Pinned KV geography from an authenticated visitor-IP assertion. #![expect( clippy::arbitrary_source_item_ordering, - reason = "group public configuration, platform-gated resolution and colocated tests" + reason = "configuration precedes request-owned resolution" )] +use edgezero_core::app::StoreMetadata; +use edgezero_core::env_config::EnvConfig; use edgezero_core::error::EdgeError; -#[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] use edgezero_core::geo::GeoProviderId; +use edgezero_core::geo::kv::Receipt; +use edgezero_core::manifest::{BakedManifest, ManifestGeoProvider}; +use std::time::Duration; + +#[cfg(all(feature = "spin", target_arch = "wasm32"))] +use edgezero_core::store_registry::KvRegistry; -/// Enables trusted ingress assertions on managed Spin dispatch. -/// -/// Insert this non-secret selection in App state from `Hooks::configure`. -/// The variable must contain a 32–128 byte ASCII credential (bytes 0x21–0x7e). The proxy -/// must replace viewer assertions and protect its transport to Spin. No geography -/// is selected when this configuration is absent. +/// Immutable deployment selection. Native store handles remain request-local. +#[cfg_attr( + not(any(test, all(feature = "spin", target_arch = "wasm32"))), + expect( + dead_code, + reason = "resolution fields are consumed only on Spin or in portable tests" + ) +)] #[derive(Clone, Debug)] -pub struct SpinGeoIngress { +pub struct SpinKvGeo { credential_variable: String, - #[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] + lookup_timeout: Duration, provider: GeoProviderId, + receipt: Receipt, + store_id: String, } -impl SpinGeoIngress { - /// Select the Spin variable containing the expected ingress credential. +fn invalid_selection() -> EdgeError { + EdgeError::validation("invalid Spin KV geo selection") +} + +impl SpinKvGeo { + /// Resolve manifest defaults and deployment overrides without performing I/O. /// /// # Errors - /// Rejects names outside `[a-z][a-z0-9_]{0,63}`, trailing underscores, and - /// consecutive underscores, matching Spin's variable key rules. The credential is - /// loaded per admitted request and is never retained in application state. + /// Rejects unsupported settings, undeclared bindings and invalid pins or budgets. #[inline] - pub fn new(credential_variable: &str) -> Result { - if credential_variable.is_empty() - || credential_variable.len() > 64 - || credential_variable.ends_with('_') - || credential_variable.contains("__") - || !credential_variable - .as_bytes() - .first() - .is_some_and(u8::is_ascii_lowercase) - || !credential_variable - .bytes() - .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_') + pub fn from_config( + baked: BakedManifest, + env: &EnvConfig, + metadata: Option, + ) -> Result, EdgeError> { + let defaults = match baked { + BakedManifest::Absent => None, + BakedManifest::Present(manifest) => manifest + .adapter_entry("spin") + .and_then(|(_, adapter)| adapter.geo.as_ref()), + BakedManifest::Malformed(_) | _ => return Err(invalid_selection()), + }; + let keys = [ + "provider", + "store_id", + "pin", + "reader_ip", + "credential_variable", + "lookup_timeout_ms", + ]; + if env + .keys_below(&["adapter", "geo"]) + .any(|path| path.len() != 1 || path.first().is_none_or(|key| !keys.contains(key))) { - return Err(EdgeError::validation( - "invalid Spin geo credential variable", - )); + return Err(invalid_selection()); + } + if defaults.is_some_and(|geo| { + geo.alb_peer_cidrs.is_some() + || geo.origin_credential_header_name.is_some() + || geo.max_in_flight.is_some() + }) { + return Err(invalid_selection()); + } + let get = |key: &str, default: Option<&str>| { + env.get(&["adapter", "geo", key]) + .map(str::to_owned) + .or_else(|| default.map(str::to_owned)) + }; + let provider = get( + "provider", + defaults + .and_then(|geo| geo.provider) + .map(|provider| match provider { + ManifestGeoProvider::Kv => "kv", + ManifestGeoProvider::Off => "off", + ManifestGeoProvider::CloudFront | _ => "unsupported", + }), + ); + let configured_store = get("store_id", defaults.and_then(|geo| geo.store_id.as_deref())); + let pin = get("pin", defaults.and_then(|geo| geo.pin.as_deref())); + let reader = get( + "reader_ip", + defaults.and_then(|geo| geo.reader_ip.as_deref()), + ); + let variable = get( + "credential_variable", + defaults.and_then(|geo| geo.credential_variable.as_deref()), + ); + let configured_timeout = get("lookup_timeout_ms", None); + let default_timeout = defaults.and_then(|geo| geo.lookup_timeout_ms); + if provider.as_deref().is_none_or(|value| value == "off") { + if configured_store.is_some() + || pin.is_some() + || reader.is_some() + || variable.is_some() + || configured_timeout.is_some() + || default_timeout.is_some() + { + return Err(invalid_selection()); + } + return Ok(None); + } + if provider.as_deref() != Some("kv") || reader.as_deref() != Some("authenticated-header") { + return Err(invalid_selection()); } - Ok(Self { - credential_variable: credential_variable.to_owned(), - #[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] - provider: GeoProviderId::new("spin-ingress").map_err(EdgeError::internal)?, - }) + let store_id = configured_store.ok_or_else(invalid_selection)?; + if !metadata.is_some_and(|stores| stores.ids.contains(&store_id.as_str())) { + return Err(invalid_selection()); + } + let credential_variable = variable.ok_or_else(invalid_selection)?; + if !valid_variable(&credential_variable) { + return Err(invalid_selection()); + } + let timeout = match configured_timeout { + Some(value) => value.parse::().map_err(|_error| invalid_selection())?, + None => default_timeout.unwrap_or(250), + }; + if !(1..=30000).contains(&timeout) { + return Err(invalid_selection()); + } + Ok(Some(Self { + credential_variable, + lookup_timeout: Duration::from_millis(u64::from(timeout)), + provider: GeoProviderId::kv(), + receipt: Receipt::from_pin(&pin.ok_or_else(invalid_selection)?) + .map_err(|_error| invalid_selection())?, + store_id, + })) } +} - /// Name of the variable, never its value. - #[inline] - #[must_use] - pub fn credential_variable(&self) -> &str { - &self.credential_variable - } +fn valid_variable(name: &str) -> bool { + !name.is_empty() + && name.len() <= 64 + && !name.ends_with('_') + && !name.contains("__") + && name.as_bytes().first().is_some_and(u8::is_ascii_lowercase) + && name + .bytes() + .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_') +} + +#[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] +use { + bytes::Bytes, + edgezero_core::{ + geo::{GeoOutcome, GeoStatus}, + key_value_store::KvHandle, + secret_store::SecretStore, + time::{Deadline, MonotonicClock}, + }, + std::{future::Future, net::IpAddr}, +}; + +#[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] +pub(crate) struct CapturedGeo { + ip: Result, ()>, + token: Option, } #[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] pub(crate) mod ingress { - use super::SpinGeoIngress; + use super::CapturedGeo; use bytes::Bytes; - use edgezero_core::geo::{ - CountryCode, GeoAssertion, GeoError, GeoLocation, GeoOutcome, GeoSource, GeoStatus, - GeoTrustBasis, GeoUnavailableReason, SubdivisionCode, - }; use edgezero_core::http::HeaderMap; - use edgezero_core::secret_store::SecretError; - #[cfg(all(feature = "spin", target_arch = "wasm32"))] - use edgezero_core::secret_store::SecretStore; - #[cfg(all(feature = "spin", target_arch = "wasm32"))] - use edgezero_core::time::{Deadline, MonotonicClock}; - use std::future::Future; - use std::str; - use subtle::ConstantTimeEq as _; + use std::net::IpAddr; - pub(crate) const COUNTRY_HEADER: &str = "x-edgezero-geo-country"; - pub(crate) const REGION_HEADER: &str = "x-edgezero-geo-region"; + pub(crate) const IP_HEADER: &str = "x-edgezero-geo-ip"; pub(crate) const TOKEN_HEADER: &str = "x-edgezero-geo-token"; - pub(crate) fn capture_token(headers: &mut HeaderMap) -> Option { - let mut values = headers.get_all(TOKEN_HEADER).iter(); - let token = values + pub(crate) fn valid_token(token: &[u8]) -> bool { + (32..=128).contains(&token.len()) && token.iter().all(u8::is_ascii_graphic) + } + + pub(crate) fn capture_inputs(headers: &mut HeaderMap) -> CapturedGeo { + let mut tokens = headers.get_all(TOKEN_HEADER).iter(); + let token = tokens .next() .filter(|value| valid_token(value.as_bytes())) - .filter(|_value| values.next().is_none()) + .filter(|_| tokens.next().is_none()) .map(|value| Bytes::copy_from_slice(value.as_bytes())); + let mut ips = headers.get_all(IP_HEADER).iter(); + let ip = match ips.next() { + None => Ok(None), + Some(value) if ips.next().is_none() && value.as_bytes().len() <= 45 => { + value.to_str().map_err(|_error| ()).and_then(|text| { + text.parse::() + .map(|ip| Some(ip.to_canonical())) + .map_err(|_error| ()) + }) + } + Some(_) => Err(()), + }; headers.remove(TOKEN_HEADER); - token - } - - fn valid_token(token: &[u8]) -> bool { - (32..=128).contains(&token.len()) && token.iter().all(u8::is_ascii_graphic) + headers.remove(IP_HEADER); + CapturedGeo { ip, token } } +} - fn assertion(headers: &HeaderMap, name: &str) -> GeoAssertion { - let mut values = headers.get_all(name).iter(); - match (values.next(), values.next()) { - (None, _) => GeoAssertion::absent(), - (Some(value), None) => GeoAssertion::from_bytes(value.as_bytes()), - _ => GeoAssertion::invalid(), +#[cfg(any(test, all(feature = "spin", target_arch = "wasm32")))] +#[expect( + clippy::multiple_inherent_impl, + reason = "request resolution is gated to Spin and portable tests" +)] +impl SpinKvGeo { + fn outcome(&self, status: GeoStatus) -> GeoOutcome { + GeoOutcome::Selected { + provider: self.provider.clone(), + status, } } - fn location(headers: &HeaderMap) -> Result, GeoError> { - let country_assertion = assertion::<2>(headers, COUNTRY_HEADER); - let region_assertion = assertion::<3>(headers, REGION_HEADER); - let country_bytes = country_assertion.as_bytes()?; - let region_bytes = region_assertion.as_bytes()?; - let Some(country_value) = country_bytes else { - return if region_bytes.is_none() { - Ok(None) - } else { - Err(GeoError::InvalidAssertion) - }; + pub(crate) async fn resolve( + &self, + input: CapturedGeo, + clock: &MonotonicClock, + admitted_deadline: Deadline, + secrets: &dyn SecretStore, + handle: Option, + make_timer: MakeTimer, + ) -> GeoOutcome + where + Timer: Future, + MakeTimer: Fn(Duration) -> Timer, + { + use edgezero_core::geo::kv::{IndexLimits, Resolver}; + use edgezero_core::geo::{ + GeoError, GeoSource, GeoStatus, GeoTrustBasis, GeoUnavailableReason, }; - let code = |bytes| str::from_utf8(bytes).map_err(|_error| GeoError::InvalidAssertion); - let country = - CountryCode::new(code(country_value)?).map_err(|_error| GeoError::InvalidAssertion)?; - let region = region_bytes - .map(|bytes| { - SubdivisionCode::new(code(bytes)?).map_err(|_error| GeoError::InvalidAssertion) - }) - .transpose()?; - Ok(Some(GeoLocation::new(country, region))) - } - - #[expect( - clippy::multiple_inherent_impl, - reason = "keep platform-only resolution separate from host-compilable configuration" - )] - impl SpinGeoIngress { - pub(crate) fn outcome(&self, status: GeoStatus) -> GeoOutcome { - GeoOutcome::Selected { - provider: self.provider.clone(), - status, - } + use edgezero_core::time::Deadline; + use futures_util::future::{Either, select}; + use subtle::ConstantTimeEq as _; + let failure = || self.outcome(GeoStatus::Error(GeoError::ProviderFailure)); + let untrusted = || { + self.outcome(GeoStatus::Unavailable( + GeoUnavailableReason::UntrustedIngress, + )) + }; + let Some(token) = input.token else { + return untrusted(); + }; + if admitted_deadline.is_expired_at(clock.now()) { + return failure(); } - - pub(crate) fn resolve_value( - &self, - supplied: &[u8], - expected: Option<&[u8]>, - headers: &HeaderMap, - ) -> GeoOutcome { - let Some(expected_value) = expected.filter(|value| valid_token(value)) else { - return self.outcome(GeoStatus::Error(GeoError::ProviderFailure)); - }; - if !bool::from(supplied.ct_eq(expected_value)) { - return self.outcome(GeoStatus::Unavailable( - GeoUnavailableReason::UntrustedIngress, - )); + let secret = secrets.get_bytes_bounded( + "", + &self.credential_variable, + clock, + admitted_deadline, + 128, + 128, + ); + let remaining = admitted_deadline + .instant() + .saturating_duration_since(clock.now()); + let read_value = match select(Box::pin(secret), Box::pin(make_timer(remaining))).await { + Either::Left((Ok(read), _)) if !admitted_deadline.is_expired_at(clock.now()) => { + read.value } - self.outcome(match location(headers) { - Ok(Some(location)) => GeoStatus::Located { - location, - source: GeoSource::SpinIngress, - trust_basis: GeoTrustBasis::AuthenticatedIngressHeader, - }, - Ok(None) => GeoStatus::Unavailable(GeoUnavailableReason::MissingMetadata), - Err(error) => GeoStatus::Error(error), - }) + Either::Left(_) | Either::Right(_) => return failure(), + }; + let Some(expected) = read_value.filter(|value| ingress::valid_token(value)) else { + return failure(); + }; + if !bool::from(token.as_ref().ct_eq(expected.as_ref())) { + return untrusted(); } - - pub(crate) async fn resolve_with( - &self, - supplied: Option, - headers: &HeaderMap, - lookup: F, - ) -> GeoOutcome - where - F: FnOnce() -> R, - R: Future, SecretError>>, - { - let Some(supplied_value) = supplied else { + let ip = match input.ip { + Ok(Some(ip)) => ip, + Ok(None) => { return self.outcome(GeoStatus::Unavailable( - GeoUnavailableReason::UntrustedIngress, + GeoUnavailableReason::MissingReaderIp, )); - }; - match lookup().await { - Ok(expected) => self.resolve_value(&supplied_value, expected.as_deref(), headers), - Err(_error) => self.outcome(GeoStatus::Error(GeoError::ProviderFailure)), } - } - - #[cfg(all(feature = "spin", target_arch = "wasm32"))] - pub(crate) async fn resolve( - &self, - supplied: Option, - headers: &HeaderMap, - clock: &MonotonicClock, - deadline: Deadline, - secrets: &dyn SecretStore, - ) -> GeoOutcome { - self.resolve_with(supplied, headers, || async { - secrets - .get_bytes_bounded("", &self.credential_variable, clock, deadline, 128, 128) - .await - .map(|read| read.value) - }) - .await - } - } -} - -#[cfg(test)] -mod tests { - use super::ingress::*; - use super::*; - use edgezero_core::geo::{ - GeoError, GeoOutcome, GeoSource, GeoStatus, GeoTrustBasis, GeoUnavailableReason, - }; - use edgezero_core::http::{HeaderMap, HeaderValue}; - - const TOKEN: &[u8] = b"0123456789abcdef0123456789abcdef"; - - #[test] - fn invalid_token_skips_lookup_and_backend_failure_is_bounded() { - use edgezero_core::secret_store::SecretError; - use futures::executor::block_on; - use std::cell::Cell; - let selection = SpinGeoIngress::new("geo_token").unwrap(); - let headers = HeaderMap::new(); - let calls = Cell::new(0_u32); - let lookup = || async { - calls.set(calls.get() + 1); - Err(SecretError::DeadlineExceeded) + Err(()) => return untrusted(), }; - let result = block_on(selection.resolve_with(None, &headers, lookup)); - assert!(matches!( - result, - GeoOutcome::Selected { - status: GeoStatus::Unavailable(GeoUnavailableReason::UntrustedIngress), - .. - } - )); - assert_eq!(calls.get(), 0); - let failed_lookup = block_on(selection.resolve_with( - Some(bytes::Bytes::from_static(TOKEN)), - &headers, - lookup, - )); - assert!(matches!( - failed_lookup, - GeoOutcome::Selected { - status: GeoStatus::Error(GeoError::ProviderFailure), - .. - } - )); - assert_eq!(calls.get(), 1); - } - - #[test] - fn selection_rejects_invalid_variable_names() { - assert_eq!( - SpinGeoIngress::new("geo_token") - .unwrap() - .credential_variable(), - "geo_token" + let Some(kv) = handle else { return failure() }; + let deadline = Deadline::at_instant( + admitted_deadline + .instant() + .min(clock.deadline_after(self.lookup_timeout).instant()), ); - for name in [ - "", - "GEO_TOKEN", - "a-b", - "1token", - "a token", - "a_", - "a__b", - &"a".repeat(65), - ] { - assert!(SpinGeoIngress::new(name).is_err(), "{name}"); + if deadline.is_expired_at(clock.now()) { + return failure(); } - } - - #[test] - fn credential_capture_strips_all_values_and_rejects_ambiguity() { - let mut headers = HeaderMap::new(); - headers.insert(TOKEN_HEADER, HeaderValue::from_bytes(TOKEN).unwrap()); - assert_eq!(capture_token(&mut headers).as_deref(), Some(TOKEN)); - assert!(!headers.contains_key(TOKEN_HEADER)); - for values in [ - vec![TOKEN, TOKEN], - vec![b"short".as_slice()], - vec![b"".as_slice()], - ] { - for value in values { - headers.append(TOKEN_HEADER, HeaderValue::from_bytes(value).unwrap()); - } - assert!(capture_token(&mut headers).is_none()); - assert!(!headers.contains_key(TOKEN_HEADER)); - } - headers.insert( - TOKEN_HEADER, - HeaderValue::from_str(&"a".repeat(129)).unwrap(), - ); - assert!(capture_token(&mut headers).is_none()); - assert!(!headers.contains_key(TOKEN_HEADER)); - } - - #[test] - fn authentication_precedes_geography_and_retains_provenance() { - let selection = SpinGeoIngress::new("geo_token").unwrap(); - let mut headers = HeaderMap::new(); - headers.insert(COUNTRY_HEADER, HeaderValue::from_static("us")); - headers.insert(REGION_HEADER, HeaderValue::from_static("ca")); - let outcome = selection.resolve_value(TOKEN, Some(TOKEN), &headers); - let GeoOutcome::Selected { - provider, - status: - GeoStatus::Located { - location, - source, - trust_basis, + let lookup = async { + let resolver = Resolver::open( + kv, + &self.receipt, + IndexLimits { + max_object_bytes: 384 * 1024, + max_path_objects: 3, + cache_bytes: 1024 * 1024, + cache_entries: 16, }, - } = outcome - else { - panic!("authenticated country and region must be located"); + ) + .await?; + resolver.verify_roots().await?; + resolver.lookup(ip).await }; - assert_eq!(provider.as_str(), "spin-ingress"); - assert_eq!(location.country().as_str(), "US"); - assert_eq!(location.subdivision().unwrap().as_str(), "CA"); - assert_eq!(source, GeoSource::SpinIngress); - assert_eq!(trust_basis, GeoTrustBasis::AuthenticatedIngressHeader); - assert!(matches!( - selection.resolve_value(TOKEN, Some(b"different-different-different-1234"), &headers), - GeoOutcome::Selected { - status: GeoStatus::Unavailable(GeoUnavailableReason::UntrustedIngress), - .. + let lookup_remaining = deadline.instant().saturating_duration_since(clock.now()); + match select(Box::pin(lookup), Box::pin(make_timer(lookup_remaining))).await { + Either::Left((Ok(found), _)) if !deadline.is_expired_at(clock.now()) => { + self.outcome(match found { + None => GeoStatus::Unavailable(GeoUnavailableReason::NoMatch), + Some(raw_location) => match raw_location.geo_location() { + Some(location) => GeoStatus::Located { + location, + source: GeoSource::Kv, + trust_basis: GeoTrustBasis::AuthenticatedIngressHeader, + }, + None => GeoStatus::Unavailable(GeoUnavailableReason::UnsupportedGeography), + }, + }) } - )); - assert!(matches!( - selection.resolve_value(TOKEN, None, &headers), - GeoOutcome::Selected { - status: GeoStatus::Error(GeoError::ProviderFailure), - .. - } - )); + Either::Left(_) | Either::Right(_) => failure(), + } } - #[test] - fn authenticated_assertions_preserve_absence_and_reject_invalid_or_duplicate_fields() { - let selection = SpinGeoIngress::new("geo_token").unwrap(); - let mut headers = HeaderMap::new(); - assert!(matches!( - selection.resolve_value(TOKEN, Some(TOKEN), &headers), - GeoOutcome::Selected { - status: GeoStatus::Unavailable(GeoUnavailableReason::MissingMetadata), - .. - } - )); - headers.insert(COUNTRY_HEADER, HeaderValue::from_static("US")); - let outcome = selection.resolve_value(TOKEN, Some(TOKEN), &headers); - assert!( - matches!(outcome, GeoOutcome::Selected { status: GeoStatus::Located { location, .. }, .. } if location.subdivision().is_none()) - ); - for country in ["XX", "USA", " US", "", "T1"] { - headers.insert(COUNTRY_HEADER, HeaderValue::from_str(country).unwrap()); - assert!(matches!( - selection.resolve_value(TOKEN, Some(TOKEN), &headers), - GeoOutcome::Selected { - status: GeoStatus::Error(GeoError::InvalidAssertion), - .. - } - )); - } - headers.insert(COUNTRY_HEADER, HeaderValue::from_static("US")); - headers.append(COUNTRY_HEADER, HeaderValue::from_static("US")); - assert!(matches!( - selection.resolve_value(TOKEN, Some(TOKEN), &headers), - GeoOutcome::Selected { - status: GeoStatus::Error(GeoError::InvalidAssertion), - .. - } - )); - headers.remove(COUNTRY_HEADER); - headers.insert(REGION_HEADER, HeaderValue::from_static("CA")); - assert!(matches!( - selection.resolve_value(TOKEN, Some(TOKEN), &headers), - GeoOutcome::Selected { - status: GeoStatus::Error(GeoError::InvalidAssertion), - .. - } - )); + #[cfg(all(feature = "spin", target_arch = "wasm32"))] + pub(crate) fn handle(&self, configured_registry: Option<&KvRegistry>) -> Option { + let registry = configured_registry?; + registry.named(&self.store_id) } } + +#[cfg(test)] +#[path = "geo/kv_tests.rs"] +mod kv_tests; diff --git a/crates/edgezero-adapter-spin/src/geo/kv_tests.rs b/crates/edgezero-adapter-spin/src/geo/kv_tests.rs new file mode 100644 index 00000000..e926a438 --- /dev/null +++ b/crates/edgezero-adapter-spin/src/geo/kv_tests.rs @@ -0,0 +1,472 @@ +#![expect( + clippy::missing_trait_methods, + clippy::too_many_lines, + clippy::unnecessary_wraps, + clippy::shadow_unrelated, + clippy::assertions_on_result_states, + clippy::clone_on_ref_ptr, + clippy::default_numeric_fallback, + clippy::absolute_paths, + reason = "colocated fault matrices use explicit test providers, default record methods and compact repeated fixtures" +)] +use super::*; +use edgezero_core::app::StoreMetadata; +use edgezero_core::env_config::EnvConfig; +use edgezero_core::manifest::{BakedManifest, Manifest}; +use std::time::Duration; + +const PIN: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"; + +fn metadata() -> Option { + Some(StoreMetadata { + ids: &["geo"], + default: "geo", + }) +} + +#[test] +fn kv_selection_uses_manifest_and_validated_overrides() { + let json: &'static str = Box::leak(format!(r#"{{"stores":{{"kv":{{"ids":["geo"]}}}},"adapters":{{"spin":{{"geo":{{"provider":"kv","store_id":"geo","pin":"{PIN}","reader_ip":"authenticated-header","credential_variable":"geo_token"}}}}}}}}"#).into_boxed_str()); + let baked = Manifest::from_baked_json(json); + assert!(matches!(baked, BakedManifest::Present(_))); + let selected = SpinKvGeo::from_config(baked, &EnvConfig::default(), metadata()) + .unwrap() + .unwrap(); + assert_eq!(selected.store_id, "geo"); + assert_eq!(selected.lookup_timeout, Duration::from_millis(250)); + let env = EnvConfig::from_vars([("EDGEZERO__ADAPTER__GEO__LOOKUP_TIMEOUT_MS", "17")]); + assert_eq!( + SpinKvGeo::from_config(baked, &env, metadata()) + .unwrap() + .unwrap() + .lookup_timeout, + Duration::from_millis(17) + ); + for (key, value) in [ + ("PROVIDER", "cloudfront"), + ("STORE_ID", "missing"), + ("PIN", "bad"), + ("CREDENTIAL_VARIABLE", "bad__key"), + ("READER_IP", "direct-peer"), + ("LOOKUP_TIMEOUT_MS", "0"), + ("LOOKUP_TIMEOUT_MS", "30001"), + ("TYPO", "private"), + ] { + let env = EnvConfig::from_vars([(format!("EDGEZERO__ADAPTER__GEO__{key}"), value)]); + assert!( + SpinKvGeo::from_config(baked, &env, metadata()).is_err(), + "{key}" + ); + } + assert!(SpinKvGeo::from_config(baked, &EnvConfig::default(), None).is_err()); + assert!( + SpinKvGeo::from_config( + BakedManifest::Malformed("broken"), + &EnvConfig::default(), + metadata() + ) + .is_err() + ); + assert!( + SpinKvGeo::from_config(BakedManifest::Absent, &EnvConfig::default(), metadata()) + .unwrap() + .is_none() + ); + let env = EnvConfig::from_vars([("EDGEZERO__ADAPTER__GEO__STORE_ID", "geo")]); + assert!(SpinKvGeo::from_config(BakedManifest::Absent, &env, metadata()).is_err()); +} + +use bytes::Bytes; +use edgezero_core::geo::kv::{Location, Range, Source, build, hex}; +use edgezero_core::geo::{GeoOutcome, GeoSource, GeoStatus, GeoTrustBasis, GeoUnavailableReason}; +use edgezero_core::http::{HeaderMap, HeaderValue}; +use edgezero_core::key_value_store::{KvError, KvHandle, KvPage, KvStore}; +use edgezero_core::secret_store::{SecretError, SecretStore}; +use edgezero_core::time::MonotonicClock; +use futures::executor::block_on; +use std::collections::BTreeMap; +use std::future::pending; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex}; + +#[derive(Default)] +struct Memory { + data: Mutex>, + reads: AtomicUsize, + writes: AtomicUsize, +} +#[async_trait::async_trait(?Send)] +impl KvStore for Memory { + async fn get_bytes(&self, key: &str) -> Result, KvError> { + self.reads.fetch_add(1, Ordering::SeqCst); + Ok(self.data.lock().unwrap().get(key).cloned()) + } + async fn put_bytes(&self, key: &str, value: Bytes) -> Result<(), KvError> { + self.writes.fetch_add(1, Ordering::SeqCst); + self.data.lock().unwrap().insert(key.to_owned(), value); + Ok(()) + } + async fn delete(&self, key: &str) -> Result<(), KvError> { + self.data.lock().unwrap().remove(key); + Ok(()) + } + async fn list_keys_page(&self, _: &str, _: Option<&str>, _: usize) -> Result { + panic!("serving must not list") + } + async fn put_bytes_with_ttl(&self, _: &str, _: Bytes, _: Duration) -> Result<(), KvError> { + panic!("serving must not write TTL") + } +} +struct Secret; +#[async_trait::async_trait(?Send)] +impl SecretStore for Secret { + async fn get_bytes(&self, _: &str, _: &str) -> Result, SecretError> { + Ok(Some(Bytes::from_static( + b"0123456789abcdef0123456789abcdef", + ))) + } + async fn get_bytes_bounded( + &self, + store_name: &str, + key: &str, + clock: &MonotonicClock, + deadline: edgezero_core::time::Deadline, + max_backend_bytes: u64, + max_value_bytes: u64, + ) -> Result, SecretError> { + edgezero_core::secret_store::finish_bounded_secret_read( + self.get_bytes(store_name, key).await, + clock, + deadline, + max_backend_bytes, + max_value_bytes, + ) + } +} + +fn inputs(ip: Option<&str>, token: &str) -> CapturedGeo { + let mut headers = HeaderMap::new(); + headers.insert(ingress::TOKEN_HEADER, HeaderValue::from_str(token).unwrap()); + if let Some(address) = ip { + headers.insert(ingress::IP_HEADER, HeaderValue::from_str(address).unwrap()); + } + let input = ingress::capture_inputs(&mut headers); + assert!(headers.is_empty()); + input +} + +#[test] +fn pinned_lookup_reaches_real_objects_and_never_writes() { + block_on(async { + let memory = Arc::new(Memory::default()); + let kv = KvHandle::new(memory.clone()); + let (receipt, _, _) = build( + &kv, + Source { + edition: "synthetic".into(), + files: vec![], + }, + &[ + Range { + start: 1, + end: 10, + location: Location::new("US", "CA").unwrap(), + }, + Range { + start: 20, + end: 30, + location: Location::new("GB", "").unwrap(), + }, + Range { + start: 40, + end: 50, + location: Location::new("XK", "").unwrap(), + }, + ], + &[Range { + start: 1, + end: 10, + location: Location::new("US", "CA").unwrap(), + }], + 1024, + ) + .await + .unwrap(); + let pin = format!( + "{}@{}", + receipt.manifest_key.split('/').nth(2).unwrap(), + hex(&receipt.manifest_hash) + ); + let env = EnvConfig::from_vars([ + ("EDGEZERO__ADAPTER__GEO__PROVIDER", "kv"), + ("EDGEZERO__ADAPTER__GEO__STORE_ID", "geo"), + ("EDGEZERO__ADAPTER__GEO__PIN", pin.as_str()), + ("EDGEZERO__ADAPTER__GEO__READER_IP", "authenticated-header"), + ("EDGEZERO__ADAPTER__GEO__CREDENTIAL_VARIABLE", "geo_token"), + ]); + let selected = SpinKvGeo::from_config(BakedManifest::Absent, &env, metadata()) + .unwrap() + .unwrap(); + let clock = MonotonicClock::default(); + let token = "0123456789abcdef0123456789abcdef"; + let writes = memory.writes.load(Ordering::SeqCst); + for ip in ["0.0.0.1", "::1", "::ffff:0.0.0.1"] { + let outcome = selected + .resolve( + inputs(Some(ip), token), + &clock, + clock.deadline_after(Duration::from_secs(1)), + &Secret, + Some(kv.clone()), + |_| pending(), + ) + .await; + assert!( + matches!(outcome, GeoOutcome::Selected { status: GeoStatus::Located { location, source: GeoSource::Kv, trust_basis: GeoTrustBasis::AuthenticatedIngressHeader }, .. } if location.country().as_str() == "US" && location.subdivision().unwrap().as_str() == "CA") + ); + } + let country_only = selected + .resolve( + inputs(Some("0.0.0.20"), token), + &clock, + clock.deadline_after(Duration::from_secs(1)), + &Secret, + Some(kv.clone()), + |_| pending(), + ) + .await; + assert!( + matches!(country_only, GeoOutcome::Selected { status: GeoStatus::Located { location, .. }, .. } if location.country().as_str() == "GB" && location.subdivision().is_none()) + ); + for (ip, reason) in [ + (Some("0.0.0.40"), GeoUnavailableReason::UnsupportedGeography), + (Some("0.0.0.11"), GeoUnavailableReason::NoMatch), + (None, GeoUnavailableReason::MissingReaderIp), + ] { + let result = selected + .resolve( + inputs(ip, token), + &clock, + clock.deadline_after(Duration::from_secs(1)), + &Secret, + Some(kv.clone()), + |_| pending(), + ) + .await; + assert!( + matches!(result, GeoOutcome::Selected { status: GeoStatus::Unavailable(actual), .. } if actual == reason) + ); + } + let reads = memory.reads.load(Ordering::SeqCst); + for (ip, token) in [ + (Some("0.0.0.1"), "ffffffffffffffffffffffffffffffff"), + (Some("0.0.0.1, 0.0.0.2"), token), + (Some("0.0.0.1:80"), token), + ] { + let result = selected + .resolve( + inputs(ip, token), + &clock, + clock.deadline_after(Duration::from_secs(1)), + &Secret, + Some(kv.clone()), + |_| pending(), + ) + .await; + assert!(matches!( + result, + GeoOutcome::Selected { + status: GeoStatus::Unavailable(GeoUnavailableReason::UntrustedIngress), + .. + } + )); + } + assert_eq!(reads, memory.reads.load(Ordering::SeqCst)); + assert_eq!(writes, memory.writes.load(Ordering::SeqCst)); + let elapsed = Arc::new(AtomicUsize::new(0)); + let observed = elapsed.clone(); + let started = clock.now(); + let advancing_clock = MonotonicClock::new(move || { + started + Duration::from_millis(u64::try_from(observed.load(Ordering::SeqCst)).unwrap()) + }); + let slow = KvHandle::new(Arc::new(AdvancingKv { + inner: kv.clone(), + elapsed: elapsed.clone(), + })); + let result = selected + .resolve( + inputs(Some("0.0.0.1"), token), + &advancing_clock, + advancing_clock.deadline_after(Duration::from_secs(1)), + &Secret, + Some(slow), + |_| pending(), + ) + .await; + assert!( + matches!( + result, + GeoOutcome::Selected { + status: GeoStatus::Error(_), + .. + } + ), + "four individually short reads must exceed one aggregate 250ms budget" + ); + assert_eq!(elapsed.load(Ordering::SeqCst), 320); + memory.data.lock().unwrap().remove(&receipt.manifest_key); + let result = selected + .resolve( + inputs(Some("0.0.0.1"), token), + &clock, + clock.deadline_after(Duration::from_secs(1)), + &Secret, + Some(kv), + |_| pending(), + ) + .await; + assert!(matches!( + result, + GeoOutcome::Selected { + status: GeoStatus::Error(_), + .. + } + )); + }); +} + +#[test] +fn duplicate_credentials_and_ip_assertions_are_rejected_and_removed() { + for header in [ingress::TOKEN_HEADER, ingress::IP_HEADER] { + let mut headers = HeaderMap::new(); + headers.insert( + ingress::TOKEN_HEADER, + HeaderValue::from_static("0123456789abcdef0123456789abcdef"), + ); + headers.insert(ingress::IP_HEADER, HeaderValue::from_static("192.0.2.1")); + let duplicate = headers[header].clone(); + headers.append(header, duplicate); + let captured = ingress::capture_inputs(&mut headers); + assert!(headers.is_empty()); + if header == ingress::TOKEN_HEADER { + assert!(captured.token.is_none()); + } else { + assert!(captured.ip.is_err()); + } + } + for ip in [ + " 192.0.2.1", + "192.0.2.1 ", + "192.0.2.1,192.0.2.2", + "[::1]", + "fe80::1%eth0", + "192.0.2.1:80", + ] { + assert!( + inputs(Some(ip), "0123456789abcdef0123456789abcdef") + .ip + .is_err() + ); + } +} + +struct PendingKv(Arc); +struct Dropped(Arc); +impl Drop for Dropped { + fn drop(&mut self) { + self.0.fetch_add(1, Ordering::SeqCst); + } +} +#[async_trait::async_trait(?Send)] +impl KvStore for PendingKv { + async fn get_bytes(&self, _: &str) -> Result, KvError> { + let _guard = Dropped(self.0.clone()); + pending().await + } + async fn put_bytes(&self, _: &str, _: Bytes) -> Result<(), KvError> { + panic!("read only") + } + async fn delete(&self, _: &str) -> Result<(), KvError> { + panic!("read only") + } + async fn list_keys_page(&self, _: &str, _: Option<&str>, _: usize) -> Result { + panic!("read only") + } + async fn put_bytes_with_ttl(&self, _: &str, _: Bytes, _: Duration) -> Result<(), KvError> { + panic!("read only") + } +} + +#[test] +fn lookup_timeout_drops_pending_backend_work() { + block_on(async { + let env = EnvConfig::from_vars([ + ("EDGEZERO__ADAPTER__GEO__PROVIDER", "kv"), + ("EDGEZERO__ADAPTER__GEO__STORE_ID", "geo"), + ("EDGEZERO__ADAPTER__GEO__PIN", PIN), + ("EDGEZERO__ADAPTER__GEO__READER_IP", "authenticated-header"), + ("EDGEZERO__ADAPTER__GEO__CREDENTIAL_VARIABLE", "geo_token"), + ]); + let selection = SpinKvGeo::from_config(BakedManifest::Absent, &env, metadata()) + .unwrap() + .unwrap(); + let clock = MonotonicClock::default(); + let drops = Arc::new(AtomicUsize::new(0)); + let timers = std::cell::Cell::new(0); + let outcome = selection + .resolve( + inputs(Some("192.0.2.1"), "0123456789abcdef0123456789abcdef"), + &clock, + clock.deadline_after(Duration::from_secs(1)), + &Secret, + Some(KvHandle::new(Arc::new(PendingKv(drops.clone())))), + |_| { + let call = timers.get(); + timers.set(call + 1); + if call == 0 { + futures::future::Either::Left(pending()) + } else { + futures::future::Either::Right(futures::future::ready(())) + } + }, + ) + .await; + assert!(matches!( + outcome, + GeoOutcome::Selected { + status: GeoStatus::Error(_), + .. + } + )); + assert_eq!(timers.get(), 2); + assert_eq!( + drops.load(Ordering::SeqCst), + 1, + "guest cancellation drops its pending read" + ); + }); +} + +struct AdvancingKv { + inner: KvHandle, + elapsed: Arc, +} +#[async_trait::async_trait(?Send)] +impl KvStore for AdvancingKv { + async fn get_bytes(&self, key: &str) -> Result, KvError> { + self.elapsed.fetch_add(80, Ordering::SeqCst); + self.inner.get_bytes(key).await + } + async fn put_bytes(&self, _: &str, _: Bytes) -> Result<(), KvError> { + panic!("read only") + } + async fn delete(&self, _: &str) -> Result<(), KvError> { + panic!("read only") + } + async fn list_keys_page(&self, _: &str, _: Option<&str>, _: usize) -> Result { + panic!("read only") + } + async fn put_bytes_with_ttl(&self, _: &str, _: Bytes, _: Duration) -> Result<(), KvError> { + panic!("read only") + } +} diff --git a/crates/edgezero-adapter-spin/src/lib.rs b/crates/edgezero-adapter-spin/src/lib.rs index 39cb96d9..12abee7a 100644 --- a/crates/edgezero-adapter-spin/src/lib.rs +++ b/crates/edgezero-adapter-spin/src/lib.rs @@ -265,8 +265,27 @@ where A: Hooks, { let stores = A::stores(); - request::dispatch_with_registries(app, req, stores.config, stores.kv, stores.secrets, &env) - .await + let geo = match geo::SpinKvGeo::from_config(A::manifest(), &env, stores.kv) { + Ok(geo) => geo, + Err(error) => { + return Ok(request::send_assembly_error( + req, + error, + app.monotonic_now(), + app.monotonic_clock(), + )?); + } + }; + request::dispatch_with_registries( + app, + req, + stores.config, + stores.kv, + stores.secrets, + &env, + geo, + ) + .await } #[cfg(test)] diff --git a/crates/edgezero-adapter-spin/src/outbound/test_support.rs b/crates/edgezero-adapter-spin/src/outbound/test_support.rs index eec506e0..cdeb7d1a 100644 --- a/crates/edgezero-adapter-spin/src/outbound/test_support.rs +++ b/crates/edgezero-adapter-spin/src/outbound/test_support.rs @@ -19,6 +19,7 @@ pub use super::spin_impl::test_support::{ pub use crate::request::test_support::{ deadline_body, dispatch_ingress_stream, dispatch_ingress_stream_with_timer, dispatch_ingress_with, dispatch_request, dispatch_request_with_geo_secret, + dispatch_request_with_geo_stores, }; #[cfg(all(feature = "spin", target_arch = "wasm32"))] pub use crate::response::test_support::next_response_body; diff --git a/crates/edgezero-adapter-spin/src/request.rs b/crates/edgezero-adapter-spin/src/request.rs index 895f36b1..dedbec98 100644 --- a/crates/edgezero-adapter-spin/src/request.rs +++ b/crates/edgezero-adapter-spin/src/request.rs @@ -12,7 +12,7 @@ pub(crate) mod test_support; use crate::SpinResponse; use crate::config_store::SpinConfigStore; use crate::context::{SpinRequestContext, parse_client_addr}; -use crate::geo::{SpinGeoIngress, ingress::capture_token}; +use crate::geo::{SpinKvGeo, ingress::capture_inputs}; use crate::ingress::capture_request_ingress; use crate::key_value_store::{DEFAULT_MAX_LIST_KEYS, SpinKvStore}; use crate::response::from_egress_response; @@ -61,6 +61,7 @@ use crate::outbound::{SpinOutboundClient, native_time}; pub(crate) struct Stores { config_registry: Option, config_store: Option, + geo: Option, kv: Option, kv_registry: Option, secret_registry: Option, @@ -404,7 +405,7 @@ where IngressFraming::HostManaged, ) .validate_normalized(app.ingress_head_limits()); - let token = capture_token(head_request.headers_mut()); + let geo_input = capture_inputs(head_request.headers_mut()); if let Err(error) = head_validation { let egress = detached_error_envelope(app, error, request_method, request_start)?; return Ok(deliver(egress)?); @@ -440,15 +441,17 @@ where return Ok(deliver(egress)?); } }; - let geo = match app.state::() { + let geo = match stores.geo.as_ref() { Some(selection) => { + let handle = selection.handle(stores.kv_registry.as_ref()); selection .resolve( - token, - head_request.headers(), + geo_input, &prepared.monotonic_clock(), prepared.read_deadline(), geo_secrets, + handle, + make_timer.clone(), ) .await } @@ -536,6 +539,7 @@ pub(crate) async fn dispatch_with_registries( kv_meta: Option, secret_meta: Option, env: &EnvConfig, + geo: Option, ) -> anyhow::Result { let request_start = app.monotonic_now(); let kv_registry = build_kv_registry(kv_meta, env); @@ -546,6 +550,7 @@ pub(crate) async fn dispatch_with_registries( req, Stores { config_registry, + geo, kv_registry, secret_registry, ..Default::default() diff --git a/crates/edgezero-adapter-spin/src/request/test_support.rs b/crates/edgezero-adapter-spin/src/request/test_support.rs index bb0537a4..c3a83b33 100644 --- a/crates/edgezero-adapter-spin/src/request/test_support.rs +++ b/crates/edgezero-adapter-spin/src/request/test_support.rs @@ -205,6 +205,22 @@ pub async fn dispatch_request_with_geo_secret( req: SpinRequest, secret: Option, reads: Option>, +) -> anyhow::Result { + dispatch_request_with_geo_stores(app, req, secret, reads, None).await +} + +/// Managed ingress with explicit test-only credential and KV registry injection. +/// +/// # Errors +/// Returns the managed admission, dispatch or delivery error. +#[doc(hidden)] +#[inline] +pub async fn dispatch_request_with_geo_stores( + app: &App, + req: SpinRequest, + secret: Option, + reads: Option>, + kv_registry: Option, ) -> anyhow::Result { let request_start = app.monotonic_now(); let (parts, native_body) = req.into_parts(); @@ -212,7 +228,11 @@ pub async fn dispatch_request_with_geo_secret( dispatch_ingress_stream_with_timer_and( app, core_request, - Stores::default(), + Stores { + geo: app.state::().cloned(), + kv_registry, + ..Stores::default() + }, request_start, move || Ok(native_body.stream()), sleep, diff --git a/crates/edgezero-adapter-spin/tests/contract.rs b/crates/edgezero-adapter-spin/tests/contract.rs index 06ea2cd3..13dfb3ba 100644 --- a/crates/edgezero-adapter-spin/tests/contract.rs +++ b/crates/edgezero-adapter-spin/tests/contract.rs @@ -1028,169 +1028,164 @@ mod tests { #[test] #[expect( clippy::too_many_lines, - reason = "one ordered matrix compares configured and disabled dispatch with credential and header-budget controls" + reason = "one real-index fixture traces admission and handler visibility through managed dispatch" )] - fn managed_geo_strips_credentials_and_preserves_selected_outcome() { - use edgezero_adapter_spin::geo::SpinGeoIngress; - use edgezero_core::geo::{GeoSource, GeoTrustBasis, GeoUnavailableReason}; - - #[edgezero_core::action] - async fn observe(mut ctx: RequestContext) -> String { - assert!(!ctx.headers().contains_key("x-edgezero-geo-token")); - ctx.extensions_mut().insert(GeoOutcome::NoSelection); - if *ctx - .extensions() - .get::() - .expect("selection expectation") - { - let GeoOutcome::Selected { provider, status } = ctx.geo() else { - panic!("configured managed dispatch must retain its selection"); - }; - assert_eq!(provider.as_str(), "spin-ingress"); - if ctx.headers().contains_key("x-test-located") { - let GeoStatus::Located { - location, - source, - trust_basis, - } = status - else { - panic!("authenticated managed request must be located"); - }; - assert_eq!(location.country().as_str(), "US"); - assert_eq!(location.subdivision().expect("region").as_str(), "CA"); - assert_eq!(*source, GeoSource::SpinIngress); - assert_eq!(*trust_basis, GeoTrustBasis::AuthenticatedIngressHeader); - } else { - assert_eq!( - *status, - GeoStatus::Unavailable(GeoUnavailableReason::UntrustedIngress) - ); - } - } else { - assert_eq!(ctx.geo(), &GeoOutcome::NoSelection); - } - "observed".to_owned() - } - - struct Sanitized; + fn managed_kv_geo_strips_ip_and_token_before_callbacks() { + use edgezero_adapter_spin::geo::SpinKvGeo; + use edgezero_adapter_spin::outbound::test_support::dispatch_request_with_geo_stores; + use edgezero_core::app::StoreMetadata; + use edgezero_core::env_config::EnvConfig; + use edgezero_core::geo::kv::{Location, Range, Source, build, hex}; + use edgezero_core::store_registry::KvRegistry; + use std::collections::BTreeMap; + #[derive(Default)] + struct Index(Mutex>); #[async_trait::async_trait(?Send)] - impl Middleware for Sanitized { - async fn handle( + #[expect( + clippy::missing_trait_methods, + reason = "ordinary-only index fixture retains default record methods" + )] + impl KvStore for Index { + async fn get_bytes(&self, key: &str) -> Result, KvError> { + Ok(self.0.lock().unwrap().get(key).cloned()) + } + async fn put_bytes(&self, key: &str, value: Bytes) -> Result<(), KvError> { + self.0.lock().unwrap().insert(key.to_owned(), value); + Ok(()) + } + async fn delete(&self, _: &str) -> Result<(), KvError> { + panic!("no deletion") + } + async fn list_keys_page( &self, - ctx: RequestContext, - next: Next<'_>, - ) -> Result { - assert!(!ctx.headers().contains_key("x-edgezero-geo-token")); - next.run(ctx).await + _: &str, + _: Option<&str>, + _: usize, + ) -> Result { + panic!("no listing") + } + async fn put_bytes_with_ttl( + &self, + _: &str, + _: Bytes, + _: Duration, + ) -> Result<(), KvError> { + panic!("no TTL") } } - + use edgezero_core::manifest::BakedManifest; + #[edgezero_core::action] + async fn observe(ctx: RequestContext) -> String { + assert!(!ctx.headers().contains_key("x-edgezero-geo-token")); + assert!(!ctx.headers().contains_key("x-edgezero-geo-ip")); + assert!( + matches!(ctx.geo(), GeoOutcome::Selected { status: GeoStatus::Located { location, .. }, .. } if location.country().as_str() == "US" && location.subdivision().unwrap().as_str() == "CA") + ); + "selected".to_owned() + } sdk_block_on(async { - for enabled in [false, true] { - let admissions = Arc::new(AtomicUsize::new(0)); - let observed_admissions = Arc::clone(&admissions); - let mut app = App::new( - RouterService::builder() - .middleware(Sanitized) - .get("/geo", observe) - .build(), - ); - app.insert_state(enabled); - if enabled { - app.insert_state( - SpinGeoIngress::new("unavailable_variable").expect("selection"), - ); - } - app.set_ingress_admission_policy(move |head| { - assert!(!head.headers().contains_key("x-edgezero-geo-token")); - observed_admissions.fetch_add(1, Ordering::SeqCst); - AdmissionDecision::Admit { - completion: ResponseEgressCompletion::empty(), - grant: IngressGrant::new(()), - read_deadline: head.read_deadline_after(Duration::from_secs(1)), - } - }); - let duplicate = "0123456789abcdef0123456789abcdef"; - for (tokens, expected_reads) in [ - (&[][..], 0_usize), - (&["short"][..], 0), - (&[duplicate, duplicate][..], 0), - (&[duplicate][..], 1), - (&["fedcba9876543210fedcba9876543210"][..], 1), - ] { - let reads = Arc::new(AtomicUsize::new(0)); - let mut outgoing = SpinRequest::builder() - .method("GET") - .uri("http://example.test/geo") - .header("content-length", "0") - .header("x-edgezero-geo-country", "US") - .header("x-edgezero-geo-region", "CA"); - if tokens == [duplicate] { - outgoing = outgoing.header("x-test-located", "yes"); - } - for token in tokens { - outgoing = outgoing.header("x-edgezero-geo-token", *token); - } - let request = outgoing - .body(http_body_util::Full::new(Bytes::new())) - .expect("native request"); - let incoming = SpinRequest::from_request( - request.into_request().expect("WASI request"), - ) - .expect("incoming request"); - let response = dispatch_request_with_geo_secret( - &app, - incoming, - Some(Bytes::from_static(b"0123456789abcdef0123456789abcdef")), - Some(Arc::clone(&reads)), - ) - .await - .expect("managed response"); - assert_eq!(captured_body(response).as_ref(), b"observed"); - assert_eq!( - reads.load(Ordering::SeqCst), - if enabled { expected_reads } else { 0 } - ); + let kv = KvHandle::new(Arc::new(Index::default())); + let (receipt, _, _) = build( + &kv, + Source { + edition: "synthetic".into(), + files: vec![], + }, + &[Range { + start: 0, + end: u128::from(u32::MAX), + location: Location::new("US", "CA").unwrap(), + }], + &[], + 1024, + ) + .await + .unwrap(); + let pin = format!( + "{}@{}", + receipt.manifest_key.split('/').nth(2).unwrap(), + hex(&receipt.manifest_hash) + ); + let env = EnvConfig::from_vars([ + ("EDGEZERO__ADAPTER__GEO__PROVIDER", "kv"), + ("EDGEZERO__ADAPTER__GEO__STORE_ID", "geo"), + ("EDGEZERO__ADAPTER__GEO__PIN", pin.as_str()), + ("EDGEZERO__ADAPTER__GEO__READER_IP", "authenticated-header"), + ("EDGEZERO__ADAPTER__GEO__CREDENTIAL_VARIABLE", "geo_token"), + ]); + let selection = SpinKvGeo::from_config( + BakedManifest::Absent, + &env, + Some(StoreMetadata { + default: "geo", + ids: &["geo"], + }), + ) + .unwrap() + .unwrap(); + let mut app = App::new(RouterService::builder().get("/geo", observe).build()); + app.insert_state(selection); + app.set_ingress_admission_policy(|head| { + assert!(!head.headers().contains_key("x-edgezero-geo-token")); + assert!(!head.headers().contains_key("x-edgezero-geo-ip")); + AdmissionDecision::Admit { + completion: ResponseEgressCompletion::empty(), + grant: edgezero_core::IngressGrant::new(()), + read_deadline: head + .read_deadline_after(edgezero_core::DEFAULT_INBOUND_READ_BUDGET), } - assert_eq!(admissions.load(Ordering::SeqCst), 5); - app.set_ingress_head_limits( - IngressHeadLimits::default() - .with_max_request_header_bytes(1024) - .expect("header budget"), - ); - let request = SpinRequest::builder() - .method("GET") - .uri("http://example.test/geo") - .header("content-length", "0") - .header("x-edgezero-geo-token", "a".repeat(1500)) - .body(http_body_util::Full::new(Bytes::new())) - .expect("oversized native request"); - let incoming = - SpinRequest::from_request(request.into_request().expect("WASI request")) - .expect("incoming request"); - let response = dispatch_request(&app, incoming) - .await - .expect("bounded response"); - assert_eq!( - capture_response(response).status(), - StatusCode::REQUEST_HEADER_FIELDS_TOO_LARGE - ); - assert_eq!( - admissions.load(Ordering::SeqCst), - 5, - "stripping must not evade original header budget" - ); - } + }); + let request = SpinRequest::builder() + .method("GET") + .uri("http://example.test/geo") + .header("content-length", "0") + .header("x-edgezero-geo-ip", "192.0.2.1") + .header("x-edgezero-geo-token", "0123456789abcdef0123456789abcdef") + .body(http_body_util::Full::new(Bytes::new())) + .unwrap(); + let incoming = SpinRequest::from_request(request.into_request().unwrap()).unwrap(); + let response = dispatch_request_with_geo_stores( + &app, + incoming, + Some(Bytes::from_static(b"0123456789abcdef0123456789abcdef")), + None, + Some(KvRegistry::single_id("geo".to_owned(), kv)), + ) + .await + .unwrap(); + assert_eq!(captured_body(response).as_ref(), b"selected"); }); } #[test] fn configured_geo_does_not_read_secrets_before_admission() { - use edgezero_adapter_spin::geo::SpinGeoIngress; + use edgezero_adapter_spin::geo::SpinKvGeo; + use edgezero_core::app::StoreMetadata; + use edgezero_core::env_config::EnvConfig; + use edgezero_core::manifest::BakedManifest; sdk_block_on(async { for abort in [false, true] { let mut app = App::new(RouterService::builder().build()); - app.insert_state(SpinGeoIngress::new("geo_token").expect("selection")); + let pin = format!("{}@{}", "a".repeat(64), "b".repeat(64)); + let env = EnvConfig::from_vars([ + ("EDGEZERO__ADAPTER__GEO__PROVIDER", "kv"), + ("EDGEZERO__ADAPTER__GEO__STORE_ID", "geo"), + ("EDGEZERO__ADAPTER__GEO__PIN", pin.as_str()), + ("EDGEZERO__ADAPTER__GEO__READER_IP", "authenticated-header"), + ("EDGEZERO__ADAPTER__GEO__CREDENTIAL_VARIABLE", "geo_token"), + ]); + app.insert_state( + SpinKvGeo::from_config( + BakedManifest::Absent, + &env, + Some(StoreMetadata { + default: "geo", + ids: &["geo"], + }), + ) + .unwrap() + .unwrap(), + ); app.set_ingress_admission_policy(move |head| { assert!(!head.headers().contains_key("x-edgezero-geo-token")); if abort { @@ -1241,6 +1236,37 @@ mod tests { }); } + #[test] + fn private_geo_headers_count_toward_original_head_limits() { + sdk_block_on(async { + for header in ["x-edgezero-geo-token", "x-edgezero-geo-ip"] { + let mut app = App::new(RouterService::builder().build()); + app.set_ingress_head_limits( + IngressHeadLimits::default() + .with_max_request_header_bytes(1024) + .unwrap(), + ); + app.set_ingress_admission_policy(|_| { + panic!("oversized original head must be rejected before callbacks") + }); + let request = SpinRequest::builder() + .method("GET") + .uri("http://example.test/geo") + .header("content-length", "0") + .header(header, "a".repeat(1500)) + .body(http_body_util::Full::new(Bytes::new())) + .unwrap(); + let incoming = + SpinRequest::from_request(request.into_request().unwrap()).unwrap(); + let response = dispatch_request(&app, incoming).await.unwrap(); + assert_eq!( + capture_response(response).status(), + StatusCode::REQUEST_HEADER_FIELDS_TOO_LARGE + ); + } + }); + } + #[test] fn standard_native_request_refuses_before_body_read() { sdk_block_on(async { diff --git a/crates/edgezero-core/src/env_config.rs b/crates/edgezero-core/src/env_config.rs index 3e4f2df0..3991919d 100644 --- a/crates/edgezero-core/src/env_config.rs +++ b/crates/edgezero-core/src/env_config.rs @@ -94,6 +94,19 @@ impl EnvConfig { self.entries.get(&path).map(String::as_str) } + /// Enumerate relative key paths in a configuration namespace, without values. + #[inline] + pub fn keys_below(&self, prefix: &[&str]) -> impl Iterator> { + let folded_prefix: Vec<_> = prefix + .iter() + .map(|part| part.to_ascii_lowercase()) + .collect(); + self.entries.keys().filter_map(move |key| { + key.strip_prefix(folded_prefix.as_slice()) + .map(|suffix| suffix.iter().map(String::as_str).collect()) + }) + } + /// `EDGEZERO__LOGGING__ENDPOINT`. Adapters that wire a platform-specific /// logger (e.g. Fastly's named log endpoints) read this to know which /// endpoint to attach to; a `None` value means "don't init a platform @@ -590,3 +603,18 @@ mod tests { assert_eq!(cfg.get(&["adapter"]), None); } } + +#[cfg(test)] +mod prefix_tests { + use super::EnvConfig; + #[test] + fn prefix_keys_are_case_folded_and_do_not_include_values() { + let env = EnvConfig::from_vars([ + ("EDGEZERO__ADAPTER__GEO__PROVIDER", "kv"), + ("EDGEZERO__ADAPTER__GEO__TYPO", "private"), + ("EDGEZERO__STORES__KV__GEO__NAME", "binding"), + ]); + let keys: Vec<_> = env.keys_below(&["ADAPTER", "geo"]).collect(); + assert_eq!(keys, vec![vec!["provider"], vec!["typo"]]); + } +} diff --git a/crates/edgezero-core/src/geo.rs b/crates/edgezero-core/src/geo.rs index 85aa3fdd..e31450b3 100644 --- a/crates/edgezero-core/src/geo.rs +++ b/crates/edgezero-core/src/geo.rs @@ -333,8 +333,6 @@ pub enum GeoSource { CloudFront, Cloudflare, Fastly, - /// Geographic assertions supplied by an authenticated Spin ingress proxy. - SpinIngress, Kv, } @@ -342,8 +340,7 @@ pub enum GeoSource { #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[non_exhaustive] pub enum GeoTrustBasis { - /// A dedicated ingress credential matched a deployment-selected secret. - /// The operator remains responsible for proxy metadata and protected transport. + /// An ingress credential authenticated the proxy assertion. AuthenticatedIngressHeader, CheckedDirectPeer, CheckedForwardedClient, @@ -387,7 +384,6 @@ impl GeoOutcome { /// Cloudflare's `XX` (unknown) or `T1` (Tor), means the platform has no usable /// geography rather than a forged assertion: an absent or unusable country is /// missing metadata, and an unusable subdivision leaves a country-only result. - /// `SpinIngress` is not platform metadata and returns `ProviderFailure` here. #[inline] #[must_use] pub fn platform(source: GeoSource, country: Option<&str>, subdivision: Option<&str>) -> Self { @@ -396,25 +392,20 @@ impl GeoOutcome { GeoSource::CloudFront => "cloudfront", GeoSource::Cloudflare => "cloudflare", GeoSource::Fastly => "fastly", - GeoSource::SpinIngress => "spin-ingress", GeoSource::Kv => return Self::NoSelection, } .to_owned(), ); - let status = if source == GeoSource::SpinIngress { - GeoStatus::Error(GeoError::ProviderFailure) - } else { - match country.and_then(|raw| CountryCode::new(raw).ok()) { - None => GeoStatus::Unavailable(GeoUnavailableReason::MissingMetadata), - Some(country_code) => GeoStatus::Located { - location: GeoLocation::new( - country_code, - subdivision.and_then(|raw| SubdivisionCode::new(raw).ok()), - ), - source, - trust_basis: GeoTrustBasis::PlatformMetadata, - }, - } + let status = match country.and_then(|raw| CountryCode::new(raw).ok()) { + None => GeoStatus::Unavailable(GeoUnavailableReason::MissingMetadata), + Some(country_code) => GeoStatus::Located { + location: GeoLocation::new( + country_code, + subdivision.and_then(|raw| SubdivisionCode::new(raw).ok()), + ), + source, + trust_basis: GeoTrustBasis::PlatformMetadata, + }, }; Self::Selected { provider, status } } @@ -428,17 +419,6 @@ mod tests { use std::rc::Rc; use std::str; - #[test] - fn ingress_source_cannot_be_labeled_as_platform_metadata() { - assert!(matches!( - GeoOutcome::platform(GeoSource::SpinIngress, Some("US"), Some("CA")), - GeoOutcome::Selected { - status: GeoStatus::Error(GeoError::ProviderFailure), - .. - } - )); - } - #[test] fn geo_country_codes_normalize_and_reject_unsupported() { assert_eq!(CountryCode::new("us").unwrap().as_str(), "US"); diff --git a/crates/edgezero-core/src/manifest.rs b/crates/edgezero-core/src/manifest.rs index 82c326b9..55b825e2 100644 --- a/crates/edgezero-core/src/manifest.rs +++ b/crates/edgezero-core/src/manifest.rs @@ -683,8 +683,7 @@ pub struct ManifestAdapter { #[serde(default)] #[validate(nested)] pub commands: ManifestAdapterCommands, - /// `[adapters.axum.geo]`: native geo selection. Only Axum reads it; other - /// adapters use their platform's geo and reject the table. + /// Geo selection for native Axum or authenticated-IP Spin KV lookup. #[serde(default, skip_serializing_if = "Option::is_none")] #[validate(nested)] pub geo: Option, @@ -699,10 +698,10 @@ pub struct ManifestAdapter { pub logging: ManifestLoggingConfig, } -/// `[adapters.axum.geo]`. Each key is a default that the matching +/// `[adapters.axum.geo]` or `[adapters.spin.geo]`. Each key is a default that the matching /// `EDGEZERO__ADAPTER__GEO__*` variable overrides at startup, so deployment-only /// values such as ALB networks can stay out of the compiled manifest. The -/// merged selection is validated before the server listens. +/// merged selection is validated before native serving or Spin request dispatch. #[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize, Validate)] #[serde(deny_unknown_fields)] #[non_exhaustive] @@ -711,6 +710,9 @@ pub struct ManifestAdapterGeo { /// ALB peer networks admitted as the protected `CloudFront` source. #[serde(default, skip_serializing_if = "Option::is_none")] pub alb_peer_cidrs: Option>, + /// Spin variable containing the expected ingress credential, never the value. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub credential_variable: Option, /// Aggregate per-request KV lookup deadline in milliseconds. #[serde(default, skip_serializing_if = "Option::is_none")] pub lookup_timeout_ms: Option, @@ -746,7 +748,7 @@ impl ManifestAdapterGeo { } } -/// Geo provider an Axum deployment selects. +/// Geo provider an Axum or Spin deployment selects. #[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] #[serde(rename_all = "lowercase")] #[non_exhaustive] @@ -1515,7 +1517,7 @@ fn validate_manifest_adapter_definition( fn validate_manifest_adapter_geo(geo: &ManifestAdapterGeo) -> Result<(), ValidationError> { let assertion = geo.alb_peer_cidrs.is_some() || geo.origin_credential_header_name.is_some(); - let kv = geo.has_kv_fields(); + let kv = geo.has_kv_fields() || geo.credential_variable.is_some(); if geo.provider == Some(ManifestGeoProvider::Off) && (assertion || kv) { let mut error = ValidationError::new("geo_off_with_policy"); error.message = Some( @@ -1534,11 +1536,24 @@ fn validate_manifest_adapter_geo(geo: &ManifestAdapterGeo) -> Result<(), Validat fn validate_manifest_adapter_geo_placement(manifest: &Manifest) -> Result<(), ValidationError> { for (name, adapter) in &manifest.adapters { - if adapter.geo.is_some() && !name.eq_ignore_ascii_case("axum") { + let Some(geo) = &adapter.geo else { continue }; + if name.eq_ignore_ascii_case("axum") { + if geo.credential_variable.is_some() { + return Err(ValidationError::new("geo_spin_field_on_axum")); + } + } else if name.eq_ignore_ascii_case("spin") { + if geo.alb_peer_cidrs.is_some() + || geo.origin_credential_header_name.is_some() + || geo.max_in_flight.is_some() + || geo.provider == Some(ManifestGeoProvider::CloudFront) + { + return Err(ValidationError::new("geo_unsupported_spin_fields")); + } + } else { let mut error = ValidationError::new("geo_adapter_unsupported"); error.message = Some( format!( - "`[adapters.{name}.geo]` is not supported; only Axum selects geo, \ + "`[adapters.{name}.geo]` is not supported; only Axum selects geo from CloudFront; Spin supports KV, \ other adapters use their platform's geo" ) .into(), @@ -3811,6 +3826,26 @@ component = "my-app" assert_eq!(adapter.adapter.component.as_deref(), Some("my-app")); } + #[test] + fn spin_kv_geo_manifest_accepts_deployment_selection() { + let input = format!( + r#" +[stores.kv] +ids = ["geo"] +[adapters.spin.geo] +provider = "kv" +store_id = "geo" +pin = "{}@{}" +reader_ip = "authenticated-header" +credential_variable = "geo_token" +"#, + "a".repeat(64), + "b".repeat(64) + ); + let loaded = ManifestLoader::try_load_from_str(&input); + assert!(loaded.is_ok(), "Spin KV deployment selection must load"); + } + #[test] fn adapter_definition_rejects_unknown_field_with_migration_pointer() { // Hard cutoff: the portable manifest enumerates the per-adapter diff --git a/docs/guide/adapters/spin.md b/docs/guide/adapters/spin.md index 614ef430..6f256a8b 100644 --- a/docs/guide/adapters/spin.md +++ b/docs/guide/adapters/spin.md @@ -325,91 +325,110 @@ manifest I/O or parsing. It does not initialize a logger, configure filters, rea runtime overrides or change `owns_logging`. Existing runner and application-owned logging responsibilities remain unchanged. -## Geographic context from trusted ingress +## Geographic context from a pinned KV dataset -Spin does not supply native country/region metadata. An application can enable -authenticated ingress assertions by inserting a `SpinGeoIngress` selection in its existing -`Hooks::configure` implementation: +Spin has no native country/region metadata. Managed `run_app`, `run_app_with_platform` +and `dispatch_app` can resolve `ctx.geo()` from an immutable KV dataset. Select it in +the application's baked `edgezero.toml`; no adapter-specific `Hooks::configure` is needed: -```rust -fn configure(app: &mut edgezero_core::app::App) -> Result<(), edgezero_core::EdgeError> { - app.insert_state(edgezero_adapter_spin::geo::SpinGeoIngress::new( - "geo_ingress_token", - )?); - Ok(()) -} +```toml +[stores.kv] +ids = ["geo"] +default = "geo" + +[adapters.spin.geo] +provider = "kv" +store_id = "geo" +pin = "@" # Replace with the verified dataset receipt. +reader_ip = "authenticated-header" +credential_variable = "geo_token" +lookup_timeout_ms = 250 ``` -Install this selection in adapter-local Hooks so shared handlers depend only on `ctx.geo()`. -This is a Rust opt-in capability; there is currently no `[adapters.spin.geo]` manifest switch. -The constructor accepts a lowercase Spin variable name, not a credential. Bind the secret -in `spin.toml` (replace `my-app` with your component id): +The provider defaults to off. `EDGEZERO__ADAPTER__GEO__PROVIDER`, `__STORE_ID`, +`__PIN`, `__READER_IP`, `__CREDENTIAL_VARIABLE` and `__LOOKUP_TIMEOUT_MS` override +matching manifest defaults. A timeout must be 1–30000 milliseconds. Invalid pins, +undeclared logical bindings, unknown geo override keys and mixed provider settings +are configuration errors; `provider = "off"` must not retain source settings. +Spin rejects Axum's peer/CloudFront policy and `max_in_flight` fields. + +Declare the physical store and credential variable in the consuming component's +`spin.toml` (replace `my-app` with its component id): ```toml [variables] -geo_ingress_token = { required = true, secret = true } +geo_token = { required = true, secret = true } + +[component.my-app] +key_value_stores = ["geo_runtime"] [component.my-app.variables] -geo_ingress_token = "{{ geo_ingress_token }}" +geo_token = "{{ geo_token }}" + +[component.my-app.environment] +EDGEZERO__STORES__KV__GEO__NAME = "geo_runtime" ``` -Supply the variable through your deployment's secret provider. Its value must be a -high-entropy credential of 32–128 ASCII bytes in the range `0x21`–`0x7e`; do not put it in source, logs, -application state, or command-line arguments. The adapter loads it for each admitted -request under the existing read deadline. There is one active credential; rotation requires +Supply the variable through the deployment's secret provider. Use a high-entropy +credential of 32–128 ASCII bytes in `0x21`–`0x7e`, never source, logs or command-line +arguments. The adapter loads it once per admitted request with a syntactically valid +token, including wrong tokens. Remote variable providers can incur network cost on +each read; qualify latency and restrict direct origin access. Rotation requires coordinating the proxy and variable update. -Spin variables can use local or remote secret providers. This adapter reads the variable -once for each admitted request with a syntactically valid token, including a wrong token. -Environment-backed lookup is local; providers such as Vault or Azure Key Vault can perform -remote I/O on each read. Qualify the chosen provider's latency, throughput, and cost, and -restrict origin access so arbitrary internet traffic cannot amplify secret-provider calls. -The request deadline bounds guest waiting; it does not prove cancellation of remote work. - -The fronting proxy must remove all viewer-supplied instances of these fields and replace -them with its own geographic metadata and credential: - -| Header | Value | -| ------------------------ | ----------------------------------------------------------- | -| `x-edgezero-geo-country` | ISO country, such as `US` | -| `x-edgezero-geo-region` | Optional subdivision component, such as `CA`, without `US-` | -| `x-edgezero-geo-token` | The secret credential shared with Spin | - -For example, a fronting Cloudflare Worker can take assertions from `request.cf.country` and -`request.cf.regionCode`, rather than viewer headers. Build a new header set after deleting -the three fields above; set only known geographic values and inject the credential from a -Worker secret binding. Forward to a fixed HTTPS Spin origin with redirects disabled so the -credential cannot follow an origin redirect. Protect proxy-to-origin transport with TLS or -an isolated private network, redact the token in proxy logs, and restrict direct origin -access. Matching a bearer credential authenticates its holder; it does not verify the -proxy's geography or network configuration. Spin's `spin-client-addr` is not used as geo -authentication because its availability and duplicate handling vary by runtime. - -Managed `run_app`, `run_app_with_platform`, `dispatch_app`, and manual managed dispatch -consume the selection automatically. Successful authentication produces provider -`spin-ingress`, source `GeoSource::SpinIngress`, and trust basis -`GeoTrustBasis::AuthenticatedIngressHeader`. Read country and optional subdivision from -`GeoStatus::Located` through the same `ctx.geo()` interface as the other adapters. - -Missing, invalid, duplicated, or incorrect credentials yield selected `UntrustedIngress`. -Secret lookup failure or invalid secret configuration yields `GeoError::ProviderFailure`. -Authenticated missing geography yields `MissingMetadata`; malformed or duplicated geographic -fields yield `GeoError::InvalidAssertion`. A country without region remains country-only. -There is no fallback to `CF-IPCountry`, CloudFront headers, or a prior request's result. -These outcomes do not themselves choose an HTTP status or application permission policy. - -Geographic assertions do not partition shared caches. Responses whose authorization or -consent policy depends on geography, including error responses, need an appropriate cache -policy at the application and proxy. Do not reuse a response across locations merely because -the URL matches. Applications that require verified geography must reject unavailable/error -states explicitly; authenticating assertions is not blanket origin access control. - -The adapter strips every token header before admission, middleware, and handler callbacks, -including when the selection is off. Its bytes still count toward original header limits. -Applications without the selection remain `NoSelection`. The unmanaged request converter -does not authenticate ingress. Local proxy/Spin fixtures prove the configured mechanism; -hosted metadata accuracy, transport protection, and downstream consent policy require -separate deployment qualification. +A trusted proxy must remove every viewer-supplied instance of these headers and +replace them with its own values: + +| Header | Value | +| ---------------------- | ------------------------------------------------------------- | +| `x-edgezero-geo-ip` | One original visitor IP, such as `192.0.2.1` or `2001:db8::1` | +| `x-edgezero-geo-token` | The credential shared with Spin | + +The IP must have no port, list, whitespace or zone identifier. IPv4-mapped IPv6 is +canonicalized. The proxy needs no geographic database. Protect its transport to a +fixed Spin origin with TLS or an isolated network, redact both fields in logs, and +disable credential-bearing redirects. A credential authenticates its holder; the +operator remains responsible for the claimed visitor IP and network topology. +`Forwarded`, `X-Forwarded-For`, country headers and `spin-client-addr` are not geo +trust sources. + +Publish the dataset through the separate [Spin operator loader](https://github.com/IABTechLab/edgezero/blob/main/examples/geo-spin-loader/README.md) +after building and verifying it with the [KV geo tools](https://github.com/IABTechLab/edgezero/blob/main/examples/geo-kv-prototype/README.md). +The loader uses ordinary binary KV writes, checks immutable conflicts, reads writes +back, publishes the manifest last and verifies the full tree. It is a temporary +loopback application, never a route in the serving app. Use the exact same named +store and backend configuration for loading and serving; local Spin storage requires +an absolute database path. Select the pin only after verification through the serving +identity/path. Rollback requires re-verifying the previous permitted generation. + +Serving performs exact-key reads only. Each admitted/authenticated request opens the +pinned manifest, verifies both roots, and looks up the visitor IP through the shared +portable resolver. All SDK handles and validated cache bytes are request-local, +including retained `dispatch_app` applications. This repeats manifest/root reads on +every request; measure cold-request latency and capacity with the selected backend. +The local cache is limited to 1 MiB/16 entries, objects to 384 KiB and paths to three +objects. The SDK materializes values before core validates their size, so these are +not hard host allocation limits. Platform controls govern aggregate concurrency. + +One KV deadline covers preparation and lookup. Secret and KV work also share the +remaining admitted request deadline. Expiry drops guest futures; it does not certify +cancellation of host/backend work. There is no automatic fallback or previous-request +result. Outcomes retain provider `kv`; a location has `GeoSource::Kv` and +`GeoTrustBasis::AuthenticatedIngressHeader`: + +- Missing, duplicate, invalid or wrong credentials: `UntrustedIngress`. +- Authenticated missing IP: `MissingReaderIp`; invalid or duplicate IP: `UntrustedIngress`. +- Secret/backend errors, expired work, or missing/corrupt pinned objects: `ProviderFailure`. +- A valid dataset gap: `NoMatch`; a source country unsupported by core: `UnsupportedGeography`. +- A country without subdivision remains country-only. + +The adapter strips both private headers before admission, middleware and handlers, +even when geo is off; original bytes still count toward header limits. Public header +or extension mutations cannot change the private outcome. Configuration errors fail +assembly; ordinary geo errors do not themselves choose an HTTP status or grant +permission. Applications must define unavailable/error policy and geography-sensitive +cache behavior, including error responses. Local runtime verification does not certify +hosted proxy protection, data accuracy, licensed-data permissions or production load. ## Context Access diff --git a/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md b/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md index f88c9cf5..95020b21 100644 --- a/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md +++ b/docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md @@ -1,94 +1,57 @@ -# Cloudflare and Spin geo implementation plan +# Spin KV geography implementation plan -**Goal:** Satisfy #480 through existing Cloudflare/Axum integration and a configured authenticated ingress source on Spin. +> Approved implementation plan. Integrate incrementally, with independent review and build/runtime verification. -**Architecture:** Reuse #502 platform geo and Axum binding. Add one non-secret Spin App configuration, private credential capture/removal, deadline-bounded secret lookup after admission, and the existing immutable Geo outcome handoff. Use fixed geographic/token headers and a Spin variable reference. +**Goal:** Complete 480/486 with a deployable Spin KV resolver reusing PR454 and existing Cloudflare coverage. +**Architecture:** Authenticated single visitor-IP admission, declared Spin KV binding, request-owned pinned resolver, private GeoOutcome. Separate operator publication component reuses existing immutable publication logic. +**Tech stack:** Rust, portable core geo-kv, Spin SDK8/Spin4.1, existing EnvConfig and manifest, WASI p2; no new Tokio dependencies in portable code. -**Technology:** Pinned Rust 1.98.1, Node 24.20.0, worker/worker-build 0.8.5, wasm-bindgen 0.2.128, Spin SDK8 and runtime4.1.0, existing subtle comparison and bounded secret lookup. +## Task 1: Integrate the existing foundation -## 1. Scope, review and isolation +- [ ] Refresh PR454/502/514 head/base and preserve clean implementation worktree; stop if unreviewed upstream changes alter assumptions. +- [ ] Normally merge exact reviewed 454 into feature/480-cloudflare-spin-geo; resolve crates/edgezero-core/src/geo.rs union and preserve intended private-outcome behavior. Do not alter parent branches or rewrite history. Run cargo test --workspace --all-targets after conflict resolution. +- [ ] Update existing docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md and corresponding plan to approved final design; retain accurate inherited scope. -- [x] Independently review the combined spec and this plan; resolve blocking and optional actionable findings. Obtain approval for the revised Spin design before production edits. -- [x] Preserve the owned `/private/tmp/edgezero-480` worktree on `feature/480-cloudflare-spin-geo`, based on #502 `8cd7af96`. Recheck parent head before publication and reassess relevant changes. -- [x] Replace the provisional Cloudflare-only docs with these approved documents under `docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md` and `docs/superpowers/plans/2026-11-18-cloudflare-spin-geo.md`. Keep private evidence outside the repository. +## Task 2: Static deployment configuration -## 2. Cloudflare contracts and guides +Files: crates/edgezero-core/src/manifest.rs; crates/edgezero-core/src/env_config.rs (narrow prefix-key enumeration and tests); crates/edgezero-adapter-spin/src/{geo.rs,lib.rs,request.rs}; affected Axum geo configuration validation/tests. -**Files:** `crates/edgezero-adapter-cloudflare/tests/contract.rs`, `docs/guide/adapters/cloudflare.md`, `docs/guide/native-geo.md`. +- [ ] First write failing manifest/config tests for Spin kv/off, env precedence, unknown GEO override names, invalid pins/store ids/variable names/reader mode/timeouts, provider-field mixing and Axum/Cloudflare/Fastly rejection of inappropriate settings. Confirm failures by scoped cargo test. +- [ ] Reuse ManifestAdapterGeo KV fields from454; add credential_variable and adapter-specific validation. Implement Spin immutable selection resolution through existing manifest and EnvConfig accessors on both public dispatch paths. No Rust-only activation requirement. +- [ ] Remove superseded SpinGeoIngress country/region API and activation tests; preserve useful token-admission implementation/tests. No draft compatibility shim unless a real consumer is discovered. +- [ ] Run scoped cargo test after each code change; build both native and spin-WASM feature surfaces. -- [x] Retain/finish the already implemented managed matrix: service/run_app/dispatch_app, independent provider/source/trust/status assertions, US/CA vs DE/BE forged headers, region display name, lowercase/leading-zero subdivision, country-only, invalid region, XX/T1, no country and no metadata, sequential isolation. -- [x] Run scoped cargo test after every code edit. Execute WASM lib/contracts with `--features "cloudflare test-utils"` using the lock-matched runner and pinned Node. -- [x] Correct stale NoSelection claims. Explain country/subdivision outcomes, platform-only source, header rejection and local-versus-hosted limits. +## Task 3: Authenticated IP and request-owned resolver -## 3. Spin geo selection and bounded assertion logic +Files: crates/edgezero-adapter-spin/src/{geo.rs,request.rs}; core geo provenance tests only as needed; crates/edgezero-adapter-spin/tests/{contract.rs,sdk_resources.rs} and existing test-support. -**Create:** `crates/edgezero-adapter-spin/src/geo.rs`. -**Modify:** `crates/edgezero-adapter-spin/src/lib.rs`, `crates/edgezero-core/src/geo.rs`. +- [ ] Write failing tests proving a valid token plus IPv4/IPv6 reaches actual KV lookup, source/provenance and private context; cover country-only/no-match/unsupported location and mapped IPv6. +- [ ] Reuse credential capture/stripping/admission before callbacks; capture the bounded single x-edgezero-geo-ip privately and strip both IP and token headers before admission snapshots. Preserve request budget accounting before credential removal. Keep secrets/reader IP absent from logs and diagnostics. +- [ ] After admission/authentication resolve declared registry KvHandle, open pinned Resolver, verify roots, and lookup under a single absolute KV deadline computed once after authentication as min(admitted deadline, now + configured KV timeout), never reset per stage. Secret work remains covered by the admitted deadline. Use 384 KiB max object, path3, request-local 1 MiB/16-entry cache. Never retain SDK handles across calls or add background work. +- [ ] Map missing/corrupt data and backend failures to existing typed outcome; no policy/status or fallback changes. Exercise deterministic timeout/drop and secret failures; assert zero KV reads for rejected inputs and zero writes always. +- [ ] Add input-reach tests for duplicate token/IP, wrong token, spoof country/forwarding/platform headers, missing binding, wrong pin, corruption, cancellation, retained dispatch_app and repeated requests. Run cargo test for each changed crate and maintained WASM contracts after each code batch. -- [x] Write failing host tests for validated variable-name configuration; exact fixed-header capture; absent/duplicate/oversized/non-ASCII credentials; credential removal; normalized original limits; constant-time match/mismatch; no-selection/untrusted/error/country-only/Located outcomes; duplicate/invalid geographic assertions. -- [x] Export `geo` configuration on native as well as WASM, with runtime-only secret resolution gated appropriately. Constructor accepts a valid Spin variable name only, retaining no credential bytes. No new runtime dependencies. -- [x] Add truthful non-exhaustive provenance variants for authenticated Spin ingress. Resolve provider label through existing validated ID APIs. Keep `GeoOutcome::platform`'s existing signature; for unsupported `SpinIngress`, return selected `spin-ingress` with `ProviderFailure`, document it and test it cannot yield Located/PlatformMetadata. The authenticated ingress resolver constructs outcomes directly. Ensure unavailable/error results retain the selected identity. -- [x] Implement minimal pure capture/validation/resolution helpers and independently typed outcome tests. Use GeoAssertion/CountryCode/SubdivisionCode, do not clone all request headers for the source input. Secret comparison uses existing subtle dependency. -- [x] Run `cargo +1.98.1 test --locked -p edgezero-core -p edgezero-adapter-spin` after each logical code edit. Confirm source-established failing cases then passing behavior before integrating dispatch. +## Task 4: A supported binary dataset loading path -## 4. Spin production dispatch and preservation tests +Files: examples/geo-kv-prototype/{Cargo.toml,src/lib.rs,src/main.rs,src/publication.rs,README.md}; new excluded examples/geo-spin-loader/{Cargo.toml,Cargo.lock,src/lib.rs,spin.toml,README.md}; operator runner under that example. -**Modify:** `crates/edgezero-adapter-spin/src/request.rs`; extend colocated WASM tests and/or `tests/contract.rs` using existing test-support machinery. +- [ ] Verify WASI compilation of the proposed small library before depending on it; keep importer/native backend dependencies isolated if required, without moving publication into production core. +- [ ] Expose existing index/store/publication library modules; add publisher feature to enable existing publish/report without native backends. Keep native tool commands behavior and tests unchanged. +- [ ] Add separate loader component and runner: read-only artifact mount; loopback-only listener; ephemeral credential supplied via Spin variable; authenticate exact single POST before work; validate artifact before target store preparation; publish then full verify; payload-free failure output; stop process using a trap on all exits including timeout and interruption. Enforce finite readiness/publication windows (30 seconds/10 minutes by default, configurable), with a cleanup-on-timeout test. Use environment-backed Spin variable injection and an in-memory POST so credentials never appear in process arguments or temporary files. Stage and remove an owned artifact copy inside the temporary application directory required by Spin. Never add this endpoint to serving manifests. +- [ ] Validate explicit backend configuration and exact store label. For local file-backed KV require absolute path, no implicit loader .spin database; document external backends and exclusive publisher ownership. Credentials must not appear in process arguments/logs. +- [ ] Red/green tests for tampering, wrong credentials, immutable replay/conflict, manifest-last/readback failure, remote full-tree failure and process cleanup. Run locked standalone tool tests and WASI component build after changes. -- [x] At the shared managed ingress function, obtain a clone of non-secret selection from App state; capture/strip every fixed token header privately. Validate original normalized head before removal can reduce budgets, drop original cloned head, and construct sanitized head for admission. -- [x] Ensure source construction, variable fetch and provider work happen only after Admitted. Preserve existing refused/aborted, body-laziness and response-egress paths. No credentials enter callbacks, App state or public extensions. -- [x] Resolve configured variable using existing `secret_store::bounded_secret_read` or bounded SecretStore consumer under `PreparedIngress::read_deadline`, with max expected credential128 bytes and validation min32 ASCII bytes. Missing/error/invalid config becomes a category-only Geo provider error; no raw SDK error propagation/logging. -- [x] Produce NoSelection when no configuration; UntrustedIngress for invalid/missing/mismatching token; authenticated assertions resolved once; pass geo to dispatch_admitted_with_geo with existing framework-error detail. -- [x] Regression tests cover no secret fetch on rejected/aborted admission or absent/structurally invalid/duplicate tokens; well-formed mismatches perform one bounded lookup. Also cover original header budget failure, sanitized admission views, private immutability, unchanged body handling and sequence isolation. Use test-only injection seam only for secret backend failures/deadlines; normal Spin runtime must also exercise the actual variable provider. -- [x] Run scoped cargo tests after each edit, then native strict Clippy and WASM compilation to catch cfg-only errors. +## Task 5: Real application verification and preservation -## 5. Normal runtime qualification +- [ ] Use pinned Rust1.98.1, SDK8 and actual Spin4.1 binary. Build synthetic artifact with core builder via offline tool; no licensed fixtures. Load through real loader into a declared local store and stop loader. +- [ ] Start separately built serving app using exactly that named store/absolute backend config, through normal manifest/env activation. Test US/CA and IPv6, country-only, missing coverage/unsupported code, wrong pin/corrupt or missing objects, permissions, auth/IP rejection, timeout, privacy, normal routes/bodies and repeated dispatch. Capture source inventory, artifact hashes and exact revision. +- [ ] Show meaningful deliberately broken lookup and authentication controls fail expected assertions, then restore. Verify loader port/process cleanup and that serving issues no writes. +- [ ] Re-run real Cloudflare metadata/forged-header proof and Axum manifest listener proof when relevant inputs change; run Fastly contracts after foundation merge. Separate local runtime evidence from hosted qualification. +- [ ] Run cargo fmt --all -- --check; cargo clippy --workspace --all-targets --all-features -- -D warnings; cargo test --workspace --all-targets; cargo check --workspace --all-targets --features "fastly cloudflare spin"; cargo check -p edgezero-adapter-spin --target wasm32-wasip2 --features spin. Complete repository run_tests equivalents, isolated consumer harness, affected standalone/example tests and docs lint/format/build. -- [x] Retain executed Cloudflare runtime evidence if production inputs remain identical; otherwise rerun affected cases. Actual built fetch -> run_app -> action, Miniflare host-controlled cf (explicit empty base cf to avoid fallback), typed assertions and source/artifact hashes. Runtime-only dependencies stay task-owned. -- [x] Build an isolated Spin SDK8 fixture with real HTTP handler -> run_app::; configure SpinGeoIngress from Hooks, actual declared Spin secret variable, ordinary/body/geo routes and admission/middleware token-absence observations. Use installed verified Spin4.1.0 binary, not default4.0. -- [x] Start owned loopback Spin and fronting proxy processes. Proxy must remove all viewer assertions/token, inject metadata from a controlled host fixture and its credential, and forward to Spin. Do not expose a header switch that enables authentication inside the Rust app. -- [x] Prove US/CA, country-only, missing/malformed/duplicate assertions, direct/wrong/missing/duplicate credentials, viewer spoof replacement, repeated requests, off-mode and body/routes, credential removal at callback boundaries and original header-size enforcement. Correlate typed source/trust/provider output and artifact identity. Stop owned resources after preserving sanitized evidence. -- [x] Run existing Axum production-hosting geo manifest/settings acceptance test; establish country/region without TS profile. Do not claim deployed CloudFront/ALB configuration. -- [x] Report independent runtime verdicts for CF, Spin and Axum, separating real SDK/runtime execution with fixtures from hosted metadata accuracy and transport qualification. Failed or blocked required scope cannot be relabeled VERIFIED. +## Task 6: Review and draft publication -## 6. Documentation, full gates and fresh review - -**Modify:** `docs/guide/adapters/spin.md`, current native/Cloudflare guides and approved spec/plan. - -- [x] Document exact Hooks configuration, fixed headers, `[variables]`/component variable binding, credential entropy/size, missing/failure semantics, proxy replacement/HTTPS/isolation requirements, rotation limitation and default-off behavior. Explain that stock Spin does not perform geolocation. -- [x] Execute `cargo +1.98.1 fmt --all -- --check`; `cargo +1.98.1 clippy --workspace --all-targets --all-features -- -D warnings`; `cargo +1.98.1 test --workspace --all-targets`; `cargo +1.98.1 check --workspace --all-targets --features "fastly cloudflare spin"`; `cargo +1.98.1 check -p edgezero-adapter-spin --target wasm32-wasip2 --features spin`. -- [x] Execute affected Cloudflare WASM suites, Spin WASM contracts/runtime tests, docs lint/format/build and git diff --check; run `cargo +1.98.1 test --offline --locked --manifest-path crates/edgezero-test-harness/Cargo.toml` plus its acceptance manifest/coverage checks. Inspect `scripts/run_tests.sh` and execute its applicable equivalent checks (dependency/forwarding checks, native feature matrices, adapter contracts, app-demo workspace and WASM compilation, generated-consumer and documentation contracts), recording any missing tools/existing failures separately. Pin versions, revision/tree and exact outcomes. -- [x] Fresh independent implementation review against full requirements and affected unchanged consumers. Resolve all blocking and optional actionable findings and rerun affected checks. - -## 7. Draft PR and fresh local self-review - -- [ ] Before committing explain implemented behavior, tradeoffs and verification limits. Explicitly sign commits, verify locally, push new branch normally, and confirm GitHub Verified per new SHA. -- [ ] Create draft PR assigned to current user using repository template/pr-creator instructions, base #502. Explain stacking and combined acceptance accurately; use Closes #480 only if all required scoped acceptance is demonstrated. Follow authorized project-board handling while preserving advanced statuses. -- [ ] Perform fresh independent local self-review of full PR against merge base and relevant unchanged paths; recheck live head/base and required gates. Resolve findings under user's implementation authorization, repeat affected verification and update draft. -- [ ] Final report: understandable behavior/corrections, exact revision, runtime/control results and limits, local checks vs hosted CI, signatures/publication URL, findings state and owned-resource cleanup. Preserve implementation worktree/unpublished work; remove only clean disposable review resources. - -## Local qualification checkpoint - -The implementation reuses #502's Cloudflare/Fastly metadata and Axum manifest binding. -The additional Spin source is enabled explicitly by `SpinGeoIngress` configuration. - -| Boundary | Executed evidence | Scope | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Cloudflare platform input | 141 WASM library tests, 31 managed contracts, 15 built Worker runtime cases | Local workerd with host-controlled metadata; normal fetch-to-run_app path | -| Spin ingress source | Five pure helper tests, 38 WASM contracts, 25 SDK resource contracts, 47 built component runtime cases | Actual Spin variable provider in the normal run_app runtime fixture; contracts inject an in-memory secret store through the same managed dispatch pipeline | -| Regression discrimination | Managed contract fails when token stripping is removed or the private outcome is dropped; restored source passes | Owned disposable source copy; production worktree unmodified by controls | -| Axum manifest selection | Existing production-hosting manifest/settings test returns US/CA without a Trusted Server boot profile | Local real listener; external CloudFront/ALB configuration not qualified | - -The generic Wasmtime contract runner cannot execute the entire Spin library test binary: -that binary imports Spin-specific KV host interfaces. The maintained CI path executes -`contract` and `sdk_resources`; those suites pass. Changed pure helper tests also execute -natively, and the real Spin fixture covers the actual secret backend. No generic-runner -result is represented as live Spin service evidence. - -Runtime checks do not establish hosted IP geolocation accuracy, deployed proxy header -replacement, transport isolation, or Trusted Server consent behavior. Those remain deployment -qualification obligations rather than changes to application policy. - -The required root gates, 32 native feature combinations, generated-project checks, app-demo tests and WASM builds, 178 tooling tests, and dependency checks passed. The isolated harness passed all 672 cases with four existing ignored cases under serial scheduling and unchanged deadlines. Its initial concurrent run encountered an uncached fixture dependency and process observation timeouts; locked fixture fetch plus the serial run resolved local qualification without source or timeout changes. - -Review follow-up: constructor validation matches Spin variable-key underscore rules. The managed backend contract observes zero reads for disabled, structurally invalid and rejected/aborted requests, and one bounded read for valid or well-formed mismatching credentials. Production guidance distinguishes local versus remote variable providers, shared cache policy, and programmatic opt-in from deploy-only selection. +- [ ] Obtain fresh independent full-delta code/architecture review and build validation; resolve all blocking and optional actionable findings, with tests after changes. Repeat affected runtime proof for final source. +- [ ] Update public technical docs for proxy IP contract, default off/configuration, pinned data publication/rollout, cold-request costs, capacity and host-allocation/cancellation limits; do not claim standalone direct-peer trust or production-load certification. +- [ ] Sign and locally verify new commits, normally push, verify GitHub signatures. Retarget existing draft514 to feature/kv-geoip and rewrite body around final delta, still linked to480/486. No force push, review requests, comments, merge or deployment. +- [ ] Fresh independent self-review after publication; inspect current-head CI without attributing older results. Fix findings under existing authorization and repeat required checks. Keep draft if any required evidence remains pending; report exact outstanding state. diff --git a/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md b/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md index 74780c9b..899af7ed 100644 --- a/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md +++ b/docs/superpowers/specs/2026-11-18-cloudflare-spin-geo-design.md @@ -1,50 +1,37 @@ -# Cloudflare and Spin geographic context +# Spin KV geography production design -## Requirements and existing implementation +Status: approved. Supersedes the Spin geographic-assertion portion of the previous Cloudflare/Spin design; Cloudflare and Axum acceptance remains. -Issue #480 requires country and first-level region through `ctx.geo()` on Cloudflare and Spin, with Axum's CloudFront selection driven by EdgeZero's manifest rather than Trusted Server configuration. Fastly preserves its existing geo. This supersedes the earlier Cloudflare-only proposal following scope clarification. +## Goal and existing foundation -Stack on PR #502 (`spec/482-axum-geo-manifest-binding`, initial head `8cd7af96e94778df359e7ffed05be595fbfd901f`). It already implements Cloudflare platform metadata, Fastly geo, and Axum manifest binding. Reuse that code and test the combined acceptance. Do not import unrelated later #439 changes or implement a second copy on main. +Complete issues 480 and 486 using Cloudflare native metadata and Spin geography resolved from an explicitly pinned immutable KV dataset. Deployment topology is not assumed. -## Cloudflare +Live PR454 commit 925fe01926e2ad71222d274610b7c80b0918de48 contains portable async core geo::kv, native managed serving, dataset builder, integrity validation, immutable publisher and verification. It already contains exact PR502 commit 8cd7af96e94778df359e7ffed05be595fbfd901f. PR514 b04f9ccd2d8579afeb8a4c85ba93cb436e7140a7 adds the existing authenticated geographic assertion path. Integrate 454 by an ordinary merge into 514, preserving published history, and retarget 514 to feature/kv-geoip. No parent edits, rebases or force pushes. Union overlapping core provenance changes, then remove the superseded SpinIngress API from the final delta. -Keep automatic platform selection. Read `cf.country` and `cf.regionCode`, never a client header or descriptive `region`. Preserve normalization, country-only results when subdivision is absent/unusable, and selected `MissingMetadata` for absent/unusable country including XX/T1. Strengthen managed contracts with independent field expectations, conflicting header values, and sequences through `run_app` and retained-app `dispatch_app`. +## Source and trust -## Spin source and configuration +Choose KV plus authenticated visitor-IP admission. This reuses the portable dataset and current credential mechanism, without requiring an ingress service to determine geography. It still requires an operator-controlled proxy to replace the original visitor-IP header and credential. Deployment topology is not established by this implementation. Never trust arbitrary Forwarded, X-Forwarded-For, spin-client-addr, or a client-supplied country/region. -Spin has no native geographic object. Choose the issue's trusted-ingress option: a deployment-controlled fronting proxy supplies geographic assertions and authenticates them with a dedicated shared credential. This avoids adding asynchronous IP lookup, a dataset, or a provider vendor. +Use fixed x-edgezero-geo-ip and x-edgezero-geo-token. Token admission retains existing 32–128-byte visible ASCII syntax, exact single-value handling, constant-time comparison, bounded Spin variable lookup, original-header admission budgets, and removal before public request snapshots or callbacks. Capture both token and visitor-IP assertion into bounded private values and remove both headers after accounting the original head and before creating the admission snapshot. An authenticated IP must be exactly one strict IpAddr with no ports, whitespace, lists or zone identifiers; canonicalize IPv4-mapped IPv6. Missing/duplicate/invalid credential fails closed before any KV read. After successful authentication, missing IP is MissingReaderIp, duplicate/malformed IP is UntrustedIngress. Do not echo IP or token in logs, errors or debug output. Credential variable name is non-secret configuration; secret value remains in Spin variable providers. -Introduce `edgezero_adapter_spin::geo::SpinGeoIngress`, a validated non-secret configuration value enabled by inserting it into App state from `Hooks::configure`. Its constructor takes the Spin variable name containing the credential. The dedicated headers are fixed: `x-edgezero-geo-country`, `x-edgezero-geo-region`, `x-edgezero-geo-token`. Configuration stores only the variable name; credential bytes never enter App state, extensions, diagnostics or normal callback views. An app without this configuration remains `NoSelection`. This requires no change to Axum's manifest schema or existing provider trait. +Resolve into existing private immutable GeoOutcome with provider identity kv, source Kv, and AuthenticatedIngressHeader trust basis (meaning this credential-gated IP assertion, not host socket attestation). Keep existing NoMatch, UnsupportedGeography and ProviderFailure semantics. Corrupt/missing pinned data is an error, never a different generation or fallback to headers. Applications explicitly decide policy on unavailable/error; a selected geo error does not itself change ordinary HTTP status. -The normal Spin `run_app`, `run_app_with_platform`, and `dispatch_app` paths consume this state automatically through their shared request dispatch. Manual managed dispatcher paths with the configured App also receive the same treatment. Unmanaged request conversion retains its established contract and is not an authentication entry point. +## Configuration and lifecycle -Spin client-address headers are not a portable authentication source: pinned Spin runtime code retains user fields alongside generated metadata, and some runtimes omit client address entirely. Do not use the existing `.get("spin-client-addr")` as proof of ingress identity. +Extend existing ManifestAdapterGeo and EnvConfig conventions for [adapters.spin.geo], with provider off (default) or kv. KV requires store_id, pin, reader_ip = "authenticated-header", and credential_variable. lookup_timeout_ms defaults to 250 and must be 1..=30000. The same EDGEZERO__ADAPTER__GEO__* overrides take precedence on Spin. provider=off rejects source settings. Reject CloudFront-only fields, max_in_flight (no misleading per-process limit), unknown manifest keys and unknown EDGEZERO__ADAPTER__GEO__* override keys, unsupported provider/input combinations, invalid variable names, undeclared logical store ids, and malformed pins. Axum rejects Spin-only settings; Cloudflare/Fastly continue rejecting geo selection tables. Both run_app and dispatch_app apply the same configuration rules. Add a narrow EnvConfig prefix-key enumeration helper to validate this namespace without exposing values in diagnostics; do not change unrelated namespace behavior. Validate merged static selection before invoking request lifecycle callbacks; use existing typed assembly-error behavior. Configuration errors are not ordinary missing geography. -## Admission and credential handling +Selection state contains immutable configuration only. After request admission and credential verification, obtain the existing declared KV registry handle and create Resolver for this request. Open pinned manifest, verify both roots, and lookup using current core reader. Bound all secret/preparation/lookup work by remaining admitted request deadline; bound KV preparation plus lookup additionally by one absolute deadline created once immediately after authentication, capped by lookup_timeout_ms and the remaining admitted deadline. Do not reset this deadline between manifest, roots and lookup. A secret failure yields ProviderFailure without reading KV. Timeouts cancel guest futures; no claim of cancelling host work. No retained Spin Store resource, future, global resolver or cross-request cache. Bound request-local validated cache to 1 MiB/16 entries, max object 384 KiB and max path 3 objects, consistent with the qualified artifact shape. SDK materializes values before core validates size; these are guest validation/cache limits, not a hard host allocation ceiling. Document repeated manifest/root reads and cold request cost; platform capacity controls govern aggregate concurrency. -1. Privately capture at most one token, rejecting duplicate, empty, malformed or oversized values. Strip every token header from the managed request, even when geo is off. Validate original normalized header budgets so removing the token cannot bypass size/count limits. Admission callbacks receive a newly constructed sanitized head; the original head snapshot must not survive into them. -2. Keep no body read, secret lookup or geo resolution before successful request admission. Refused/aborted ingress retains its existing lifecycle. -3. With geo enabled, missing/invalid/duplicate token means selected `UntrustedIngress`, with no secret lookup. Otherwise asynchronously load the configured Spin variable under the admitted read deadline and the existing bounded-secret mechanism. Expected credentials must be 32–128 ASCII token bytes; use synthetic credentials only in tests. Lookup failure, missing variable, invalid credential configuration or deadline expiry produces a bounded provider failure outcome, never a permissive fallback or exposed backend error. -4. Compare equal-length validated credentials with the existing constant-time dependency. Length is not secret; do not claim memory zeroization or host allocation limits that the SDK cannot provide. -5. Only after matching the credential, capture bounded country/subdivision assertions. Identical or conflicting duplicate geographic fields, oversize, malformed, or subdivision-without-country assertions are invalid. Both fields absent means selected `MissingMetadata`; valid country with absent subdivision is country-only. Reuse existing CountryCode/SubdivisionCode/GeoAssertion semantics. Invalid authenticated assertions yield `InvalidAssertion`, preserving the distinction from a missing platform estimate. -6. Pass one owned outcome through `dispatch_admitted_with_geo` before router middleware/handlers. Public extensions or mutations of header fields cannot change it. Use truthful provenance `SpinIngress` and `AuthenticatedIngressHeader`, with a documented provider label `spin-ingress`; this does not claim Spin platform geolocation or a verified network topology. +## Dataset publication -Keep APIs minimal: fixed headers, one variable-name selection, existing secret lookup/timer machinery, existing admitted outcome handoff, no new I/O-capable provider trait. Core source/trust enums are already non-exhaustive; their extension must not broaden platform-specific constructors to fabricate Spin platform provenance. +Serving performs exact-key reads only. Provide a separate operator-only Spin loader using ordinary SpinKvStore binary writes and the existing validated publisher. No serving bootstrap writes, public serving upload route, native database-format writes, active-generation key, or hosted deployment automation. -## Deployment contract +Expose only existing offline artifact/publication modules as a small library in examples/geo-kv-prototype (optional publisher feature; native SDKs remain optional). Keep CSV import/main separate. A standalone excluded examples/geo-spin-loader component mounts an existing artifact directory read-only at /artifact. Its single authenticated POST validates Artifact::open before opening the target Spin store; then invokes existing publish (identical replay, conflict rejection, readback, manifest last) and full remote verify. Return aggregate counts and pin, no addresses, secrets or raw backend errors. Pin selection remains an explicit serving configuration change after verification. -The upstream proxy must obtain country/subdivision from its own trusted platform metadata, remove every viewer-supplied geographic/token header, replace assertions, and inject a high-entropy credential from secret storage. Proxy-to-Spin transport must be protected with TLS or an isolated private loopback/network; the credential is a bearer secret. The origin must not forward/echo the credential, and proxy logs must redact it. Rotate through coordinated proxy/variable updates; this version supports one active credential and makes no zero-downtime rotation promise. +An operator runner starts the loader only on loopback using an ephemeral variable credential, invokes it, and stops it on success/failure, timeout or interruption. Give runner readiness and total publication finite configurable deadlines (defaults 30 seconds readiness, 10 minutes publication); fail closed if either expires, with a cleanup-on-timeout test. Supply the ephemeral credential through a Spin environment-backed variable provider and send the POST from process memory, never secret-bearing process arguments or files. Stage the artifact inside the temporary application directory required by Spin and remove the owned copy on exit. It must never expose the endpoint on the serving app. Loader and serving use the same explicit named store and absolute backend path/runtime configuration; a relative .spin path is insufficient proof of shared storage. Default local SQLite backing is a supported rehearsal; external Spin backends remain subject to their documented configuration and hosted qualification. Exclusive single publisher per generation remains required; read-before-write is not a distributed lock. No licensed artifact or source data enters Git or release images. Loader must compile for the actual selected WASI/Spin SDK versions before acceptance. -Document both the supported header/variable binding and an example using a fronting platform's native geography. This is operator-configured ingress support, not automatic stock Spin geography or an IP geolocation service. Required local verification proves this mechanism through a disposable proxy and real Spin runtime. Actual hosted proxy configuration, metadata accuracy, transport isolation and Trusted Server adoption require separate deployment qualification. +## Acceptance and limitations -## Acceptance and preservation evidence +Real Spin4.1 runtime proof must build a synthetic IPv4/IPv6 artifact through 454 tooling, publish through the operator loader, stop it, start a separate serving component on the same store, and observe US/CA through ctx.geo(). Also country-only, gaps, unsupported geography, invalid/missing/corrupt objects, wrong pins, missing store permissions, input spoofing/duplicates, secret failures, deadlines, repeated requests and retained dispatch_app; prove sensitive headers are absent from every public callback. Include deliberate broken controls that discriminate missing lookup and credential enforcement. Prove publication idempotence/conflicts/tampering and no serving writes. -- Cloudflare built Worker: US/CA, country-only, missing/XX/T1, header spoof rejection, request isolation, ordinary and missing routes, through the actual normal entry point under host-controlled metadata. -- Spin built component and local proxy: same country/region consumption through normal `run_app`; direct/missing/wrong/duplicate credential cannot obtain Located; authenticated malformed/duplicate assertions fail; token invisible to admission/middleware/handler; original header budgets still apply; private outcome survives extension tampering; off mode stays NoSelection; repeated requests and ordinary body/routes preserve behavior. Distinguish fixture platform metadata from deployed geolocation. -- Axum: execute the existing production-hosting manifest-selection test demonstrating country/region without a Trusted Server profile. No Axum production changes are planned. -- Run required Rust format, strict Clippy, workspace tests, feature compilation and Spin WASM check, plus Cloudflare WASM lib/contracts and affected Spin native/WASM/runtime suites. Documentation lint/format/build use pinned Node. -- Fresh independent design/plan, implementation and final self-reviews must reconcile all actionable blocking and optional findings. Create a signed, GitHub-verified draft PR against #502 after the required local gates pass. Closing #480 is justified only when all above acceptance evidence is established; otherwise retain the missing scope explicitly. - -## Alternatives - -CIDR admission based on `spin-client-addr` would depend on individual runtimes' treatment of user-supplied duplicates and omissions. A credential gate avoids that portability dependency. PR [#454](https://github.com/IABTechLab/edgezero/pull/454), reviewed at `925fe019`, already provides a portable asynchronous KV resolver and managed Axum serving. A Spin KV integration can reuse that reader, but still needs trusted viewer-IP admission, a KV binding, preparation/readiness, lookup budgets and cache-lifetime integration. The synchronous GeoProvider remains assertion-only and must not perform I/O. The ingress option is appropriate when a deployment already has trusted geographic assertions; it does not claim to supply standalone Spin IP lookup. +Preserve Cloudflare native metadata and forged-header resistance, Fastly behavior, Axum manifest-only activation and normal Spin bodies/routes. Complete required project checks, WASM contract suites, actual application runtimes, fresh independent review and all actionable findings before publishing signed commits and updating draft514. Production load/capacity, geography accuracy, data licensing, host-side cancellation, and external-backend permissions are not certified by local tests. diff --git a/examples/geo-kv-prototype/Cargo.toml b/examples/geo-kv-prototype/Cargo.toml index 649d3acd..73720933 100644 --- a/examples/geo-kv-prototype/Cargo.toml +++ b/examples/geo-kv-prototype/Cargo.toml @@ -9,6 +9,7 @@ publish = false [features] default = [] +publisher = [] celld = ["dep:edgezero-store-celld", "dep:tokio"] dynamodb = ["dep:edgezero-store-aws", "dep:tokio"] diff --git a/examples/geo-kv-prototype/README.md b/examples/geo-kv-prototype/README.md index 6931a05d..0bc6b2bb 100644 --- a/examples/geo-kv-prototype/README.md +++ b/examples/geo-kv-prototype/README.md @@ -127,11 +127,13 @@ Use a serving role allowing only `dynamodb:DescribeTable` and `dynamodb:GetItem` ```json { "Version": "2012-10-17", - "Statement": [{ - "Effect": "Allow", - "Action": ["dynamodb:DescribeTable", "dynamodb:GetItem"], - "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/edgezero-kv" - }] + "Statement": [ + { + "Effect": "Allow", + "Action": ["dynamodb:DescribeTable", "dynamodb:GetItem"], + "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/edgezero-kv" + } + ] } ``` @@ -154,3 +156,10 @@ Core owns the `EZG1` binary encoding and schema validation. Objects use sorted i `store.rs` is a local file-backed `KvStore` for artifact IO, not a production async filesystem backend. Local timings include file reads, hashing, validation and search. OS page cache is uncontrolled. Cache-disabled does not mean a cold disk. Linux `VmHWM` includes importer/oracle memory in those commands, so it is not serving RSS. Fresh `lookup` avoids retaining CSV. Tests use synthetic City/Country data and in-memory fault injection. They cover deterministic exports, boundaries/gaps, unsupported codes, safe output, inventory tampering, manifest-last publication, identical replay, resuming after every uncertain write, conflict/read-back failures and missing/corrupt serving visibility without writes. Run optional-backend compilation and tests with `--all-features`; it does not contact services. Real stock-celld, DynamoDB Local, serving-grant denial, production-size 16/64 KiB measurements and hosted IAM qualification still require operator runs. Earlier [prototype measurements](../../docs/superpowers/plans/2026-11-05-kv-geo-prototype-results.md) describe the old `p1` experiment, not backend evidence for this implementation. + +## Spin publication + +The [separate Spin operator loader](../geo-spin-loader/README.md) publishes the same +verified binary artifact through ordinary Spin KV APIs. It reuses the `publisher` +library feature, without enabling native celld/AWS backends. The serving component +only enables the portable reader; it does not import this operator library or CSV. diff --git a/examples/geo-kv-prototype/src/lib.rs b/examples/geo-kv-prototype/src/lib.rs new file mode 100644 index 00000000..cacfd704 --- /dev/null +++ b/examples/geo-kv-prototype/src/lib.rs @@ -0,0 +1,4 @@ +//! Shared artifact validation and immutable publication for operator tooling. +pub mod index; +pub mod publication; +pub mod store; diff --git a/examples/geo-kv-prototype/src/main.rs b/examples/geo-kv-prototype/src/main.rs index ff7b5b24..90b5a30a 100644 --- a/examples/geo-kv-prototype/src/main.rs +++ b/examples/geo-kv-prototype/src/main.rs @@ -1,9 +1,7 @@ #[cfg(any(feature = "celld", feature = "dynamodb"))] mod backend; mod import; -mod index; -mod publication; -mod store; +use geo_kv_prototype::{index, publication, store}; use std::{fs, net::IpAddr, path::Path, sync::Arc, time::Instant}; diff --git a/examples/geo-kv-prototype/src/publication.rs b/examples/geo-kv-prototype/src/publication.rs index fa937ee4..a69954a3 100644 --- a/examples/geo-kv-prototype/src/publication.rs +++ b/examples/geo-kv-prototype/src/publication.rs @@ -8,7 +8,7 @@ use anyhow::{Context, Result, ensure}; use async_trait::async_trait; use bytes::Bytes; use edgezero_core::key_value_store::{KvError, KvHandle, KvPage, KvStore}; -#[cfg(any(test, feature = "celld", feature = "dynamodb"))] +#[cfg(any(test, feature = "publisher", feature = "celld", feature = "dynamodb"))] use serde::Serialize; use crate::{ @@ -19,7 +19,7 @@ use crate::{ pub struct Artifact { pub receipt: Receipt, pub inventory: Vec, - #[cfg(any(test, feature = "celld", feature = "dynamodb"))] + #[cfg(any(test, feature = "publisher", feature = "celld", feature = "dynamodb"))] kv: KvHandle, } @@ -128,13 +128,13 @@ impl Artifact { Ok(Self { receipt, inventory, - #[cfg(any(test, feature = "celld", feature = "dynamodb"))] + #[cfg(any(test, feature = "publisher", feature = "celld", feature = "dynamodb"))] kv, }) } } -#[cfg(any(test, feature = "celld", feature = "dynamodb"))] +#[cfg(any(test, feature = "publisher", feature = "celld", feature = "dynamodb"))] #[derive(Debug, Default, Serialize)] pub struct PublishReport { pub objects: usize, @@ -142,7 +142,7 @@ pub struct PublishReport { pub identical: usize, } -#[cfg(any(test, feature = "celld", feature = "dynamodb"))] +#[cfg(any(test, feature = "publisher", feature = "celld", feature = "dynamodb"))] pub async fn publish(artifact: &Artifact, remote: &KvHandle) -> Result { let mut report = PublishReport::default(); // Inventory ordering is not trusted. Only the manifest is a publication marker. diff --git a/examples/geo-spin-loader/.gitignore b/examples/geo-spin-loader/.gitignore new file mode 100644 index 00000000..afd7ace2 --- /dev/null +++ b/examples/geo-spin-loader/.gitignore @@ -0,0 +1,3 @@ +/__pycache__/ +/artifact/ +/.spin/ diff --git a/examples/geo-spin-loader/Cargo.lock b/examples/geo-spin-loader/Cargo.lock new file mode 100644 index 00000000..f24f6df8 --- /dev/null +++ b/examples/geo-spin-loader/Cargo.lock @@ -0,0 +1,1622 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "adler2" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "alloc-no-stdlib" +version = "2.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc7bb162ec39d46ab1ca8c77bf72e890535becd1751bb45f64c597edb4c8c6b3" + +[[package]] +name = "alloc-stdlib" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e76a019e91224d279006ff972f1e984179a6e9feb050adba6ce8274aef23195" +dependencies = [ + "alloc-no-stdlib", +] + +[[package]] +name = "anyhow" +version = "1.0.104" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470" + +[[package]] +name = "async-compression" +version = "0.4.43" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3976abdc8fe7d1133d43d304afd42abdf5bc3e1319d263d223bde07b5efc4be8" +dependencies = [ + "compression-codecs", + "compression-core", + "futures-io", + "pin-project-lite", +] + +[[package]] +name = "async-stream" +version = "0.3.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b5a71a6f37880a80d1d7f19efd781e4b5de42c88f0722cc13bcb6cc2cfe8476" +dependencies = [ + "async-stream-impl", + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "async-stream-impl" +version = "0.3.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c7c24de15d275a1ecfd47a380fb4d5ec9bfe0933f309ed5e705b775596a3574d" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "async-trait" +version = "0.1.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "base16ct" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd307490d624467aa6f74b0eabb77633d1f758a7b25f12bceb0b22e08d9726f6" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "block-buffer" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa" +dependencies = [ + "hybrid-array", +] + +[[package]] +name = "brotli" +version = "8.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5cc91aac060a7a1e25823bdccbfb6af1875b88f17c6daac97894eed8207166b3" +dependencies = [ + "alloc-no-stdlib", + "alloc-stdlib", + "brotli-decompressor", +] + +[[package]] +name = "brotli-decompressor" +version = "5.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5962523e1b92ce1b5e793d9169b9943eece10d39f62550bc04bb605d75b94924" +dependencies = [ + "alloc-no-stdlib", + "alloc-stdlib", +] + +[[package]] +name = "bumpalo" +version = "3.20.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "87a0cf66fd1eb2fb7b822cb78370d82303750809bc6ba855f3f58e517d3238db" + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "compression-codecs" +version = "0.4.38" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf" +dependencies = [ + "brotli", + "compression-core", + "flate2", + "memchr", +] + +[[package]] +name = "compression-core" +version = "0.4.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789" + +[[package]] +name = "const-oid" +version = "0.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "be95d4a884358a21a199689323c29e9256b4a1b315e22f183d155422041d3a9a" + +[[package]] +name = "cpufeatures" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566" +dependencies = [ + "libc", +] + +[[package]] +name = "crc32fast" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "crypto-common" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453" +dependencies = [ + "hybrid-array", +] + +[[package]] +name = "csv" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52cd9d68cf7efc6ddfaaee42e7288d3a99d613d4b50f76ce9827ae0c6e14f938" +dependencies = [ + "csv-core", + "itoa", + "ryu", + "serde_core", +] + +[[package]] +name = "csv-core" +version = "0.1.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "704a3c26996a80471189265814dbc2c257598b96b8a7feae2d31ace646bb9782" +dependencies = [ + "memchr", +] + +[[package]] +name = "darling" +version = "0.23.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "25ae13da2f202d56bd7f91c25fba009e7717a1e4a1cc98a76d844b65ae912e9d" +dependencies = [ + "darling_core", + "darling_macro", +] + +[[package]] +name = "darling_core" +version = "0.23.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9865a50f7c335f53564bb694ef660825eb8610e0a53d3e11bf1b0d3df31e03b0" +dependencies = [ + "ident_case", + "proc-macro2", + "quote", + "strsim", + "syn 2.0.119", +] + +[[package]] +name = "darling_macro" +version = "0.23.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d" +dependencies = [ + "darling_core", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "digest" +version = "0.11.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2" +dependencies = [ + "block-buffer", + "const-oid", + "crypto-common", +] + +[[package]] +name = "displaydoc" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "edgezero-adapter-spin" +version = "0.1.0" +dependencies = [ + "anyhow", + "async-stream", + "async-trait", + "bytes", + "edgezero-core", + "fern", + "futures", + "futures-util", + "log", + "serde", + "serde_json", + "spin-sdk", + "subtle", + "thiserror", +] + +[[package]] +name = "edgezero-core" +version = "0.1.0" +dependencies = [ + "adler2", + "alloc-no-stdlib", + "alloc-stdlib", + "anyhow", + "async-compression", + "async-stream", + "async-trait", + "base16ct", + "brotli", + "brotli-decompressor", + "bytes", + "compression-codecs", + "compression-core", + "crc32fast", + "edgezero-macros", + "flate2", + "futures", + "futures-util", + "http", + "http-body", + "log", + "matchit", + "miniz_oxide", + "ryu", + "serde", + "serde_json", + "serde_path_to_error", + "serde_urlencoded", + "sha2", + "simd-adler32", + "thiserror", + "toml", + "tower-service", + "tracing", + "url", + "validator", + "web-time", +] + +[[package]] +name = "edgezero-macros" +version = "0.1.0" +dependencies = [ + "log", + "proc-macro2", + "quote", + "serde", + "serde_json", + "syn 3.0.10", + "toml", + "validator", +] + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "errno" +version = "0.3.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e35d6e78f4cebb90e51d543db8fe41528851d6deeef6ef21ebd4bfdc1e784776" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "fastrand" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223" + +[[package]] +name = "fern" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4316185f709b23713e41e3195f90edef7fb00c3ed4adc79769cf09cc762a3b29" +dependencies = [ + "log", +] + +[[package]] +name = "flate2" +version = "1.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c" +dependencies = [ + "crc32fast", + "miniz_oxide", +] + +[[package]] +name = "foldhash" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "futures" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3" +dependencies = [ + "futures-channel", + "futures-core", + "futures-executor", + "futures-io", + "futures-sink", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-channel" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4" +dependencies = [ + "futures-core", + "futures-sink", +] + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-executor" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed" + +[[package]] +name = "futures-macro" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "futures-sink" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-channel", + "futures-core", + "futures-io", + "futures-macro", + "futures-sink", + "futures-task", + "memchr", + "pin-project-lite", + "slab", +] + +[[package]] +name = "geo-kv-prototype" +version = "0.0.0" +dependencies = [ + "anyhow", + "async-trait", + "bytes", + "csv", + "edgezero-core", + "futures", + "ipnet", + "serde", + "serde_json", + "sha2", + "tempfile", +] + +[[package]] +name = "geo-spin-loader" +version = "0.0.0" +dependencies = [ + "anyhow", + "edgezero-adapter-spin", + "edgezero-core", + "geo-kv-prototype", + "serde_json", + "spin-sdk", + "subtle", +] + +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "libc", + "r-efi", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" +dependencies = [ + "foldhash", +] + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "http" +version = "1.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425" +dependencies = [ + "bytes", + "itoa", +] + +[[package]] +name = "http-body" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c" +dependencies = [ + "bytes", + "http", +] + +[[package]] +name = "http-body-util" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "pin-project-lite", +] + +[[package]] +name = "hybrid-array" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27f864f10dfb56725ce5ce5472bc52252c8f93a4ab86327122cebf62c5f59a17" +dependencies = [ + "typenum", +] + +[[package]] +name = "icu_collections" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe090a42a0d3140fed8c63263ed1fecc02422cb2f4bfe55cd8de2de1b8e105dd" +dependencies = [ + "displaydoc", + "potential_utf", + "utf8_iter", + "yoke", + "zerofrom", + "zerovec", +] + +[[package]] +name = "icu_locale_core" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "25d29b57c17c6528d0dc4c2141cfa2d08200465acb537a3909c8b9b8a4a984c0" +dependencies = [ + "displaydoc", + "litemap", + "tinystr", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_normalizer" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "404a3b8c486f205c87fe7f23ab6894d84a4ad76d6e4671ae1981ba7def87c599" +dependencies = [ + "icu_collections", + "icu_normalizer_data", + "icu_properties", + "icu_provider", + "smallvec", + "zerovec", +] + +[[package]] +name = "icu_normalizer_data" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20f0088bfb7441f7a37fa0c9e20cb1e9cba1cac6b9ce8cd2a6dc44294f8e8cbc" + +[[package]] +name = "icu_properties" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ea83d991c56158f7cf898bf86436c1dfe7c07ee82fe88951f2695c9f37a379f" +dependencies = [ + "displaydoc", + "icu_collections", + "icu_locale_core", + "icu_properties_data", + "icu_provider", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_properties_data" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b98f29af82d02b163fe50161388350e743bb3107cc8e8c2f7314cb505faddfcf" + +[[package]] +name = "icu_provider" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "413099315636c588ee8f011190b329b971a09a8fae9d157e01dcae8379468514" +dependencies = [ + "displaydoc", + "icu_locale_core", + "writeable", + "yoke", + "zerofrom", + "zerotrie", + "zerovec", +] + +[[package]] +name = "id-arena" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954" + +[[package]] +name = "ident_case" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39" + +[[package]] +name = "idna" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de" +dependencies = [ + "idna_adapter", + "smallvec", + "utf8_iter", +] + +[[package]] +name = "idna_adapter" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714" +dependencies = [ + "icu_normalizer", + "icu_properties", +] + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown", + "serde", + "serde_core", +] + +[[package]] +name = "ipnet" +version = "2.12.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0" +dependencies = [ + "serde", +] + +[[package]] +name = "itoa" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4" + +[[package]] +name = "js-sys" +version = "0.3.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + +[[package]] +name = "leb128fmt" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2" + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "linux-raw-sys" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" + +[[package]] +name = "litemap" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" + +[[package]] +name = "log" +version = "0.4.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c" + +[[package]] +name = "matchit" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8863b587001c1b9a8a4e36008cebc6b3612cb1226fe2de94858e06092687b608" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "miniz_oxide" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "potential_utf" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661" +dependencies = [ + "zerovec", +] + +[[package]] +name = "prettyplease" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2bfe0f4c752e450fc2faf62654f1c134747922825d5b04ca717b8874f41a40c0" +dependencies = [ + "proc-macro2", + "syn 3.0.10", +] + +[[package]] +name = "proc-macro-error-attr3" +version = "3.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e564d14133360e1ae169ffde5da25881b5fa47261665b8e5713c212c27799da" +dependencies = [ + "proc-macro2", + "quote", +] + +[[package]] +name = "proc-macro-error3" +version = "3.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f0d4471b3436c22106b21913b1dda531558918ae9b7ec55d58aa84b43552233" +dependencies = [ + "proc-macro-error-attr3", + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "regex" +version = "1.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9807af0e638c12e753aa1b4e601791bf2a8f71274023c8bbeec12fc149950857" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41d60ef07df457506a0a1a2073112eb4aae5733dbd2813c3da77d1b0fd441158" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d902046e6a28a1e4c3cab97258a0ce11e994903f01c2d97a9447a0b3df85f4f6" + +[[package]] +name = "rustix" +version = "1.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa" +dependencies = [ + "bitflags", + "errno", + "libc", + "linux-raw-sys", + "windows-sys", +] + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "semver" +version = "1.0.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "serde_json" +version = "1.0.150" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_path_to_error" +version = "0.1.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457" +dependencies = [ + "itoa", + "serde", + "serde_core", +] + +[[package]] +name = "serde_spanned" +version = "1.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c187e0a369471c550af028cba56d4f4fa2a489ad28151ae95a4d340a2a8b782" +dependencies = [ + "serde_core", +] + +[[package]] +name = "serde_urlencoded" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd" +dependencies = [ + "form_urlencoded", + "itoa", + "ryu", + "serde", +] + +[[package]] +name = "sha2" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d7069beb7d6ac7b9acd1039986e73443f24234f41074da099d6f994ac9ad19" +dependencies = [ + "cfg-if", + "cpufeatures", + "digest", +] + +[[package]] +name = "simd-adler32" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214" + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.16.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3244542535d5de959d90ec55d1b5ff0fd2bb7b1310223907d5f11932847f7b59" + +[[package]] +name = "spin-macro" +version = "8.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "45fefea15ed93ab2b6830a0249ce7cae2300202f569e013e12d39f3fba519ecc" +dependencies = [ + "proc-macro2", + "quote", + "syn 1.0.109", +] + +[[package]] +name = "spin-sdk" +version = "8.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9df1f876031b7906a9e802a8bbadf599a423f49adacde532535c6270dc4f11a1" +dependencies = [ + "anyhow", + "bytes", + "futures", + "http", + "http-body", + "http-body-util", + "spin-macro", + "thiserror", + "wasip3", +] + +[[package]] +name = "stable_deref_trait" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "subtle" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" + +[[package]] +name = "syn" +version = "1.0.109" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "synstructure" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "tempfile" +version = "3.27.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" +dependencies = [ + "fastrand", + "getrandom", + "once_cell", + "rustix", + "windows-sys", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "tinystr" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "abc840c238154d58f9e86b2792261edfde565a17696e1cda1a449de27979801a" +dependencies = [ + "displaydoc", + "zerovec", +] + +[[package]] +name = "toml" +version = "1.2.1+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d5755c51863cdac711f1956baf8eb9588e060755f7d3c4c979e70ea1e1f32cd7" +dependencies = [ + "indexmap", + "serde_core", + "serde_spanned", + "toml_datetime", + "toml_parser", + "toml_writer", + "winnow", +] + +[[package]] +name = "toml_datetime" +version = "1.1.3+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "173f25c883cd2176a2d8212155638c0a60d484a9d84546d270866f40f56b6e49" +dependencies = [ + "serde_core", +] + +[[package]] +name = "toml_parser" +version = "1.1.5+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c" +dependencies = [ + "winnow", +] + +[[package]] +name = "toml_writer" +version = "1.2.0+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "009dbb7700f11c55ef83aebbe4c0e9cf1f1ac0844bd8d6f00dc38f302026e13a" + +[[package]] +name = "tower-service" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3" + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "pin-project-lite", + "tracing-attributes", + "tracing-core", +] + +[[package]] +name = "tracing-attributes" +version = "0.1.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", +] + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "url" +version = "2.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", + "serde", +] + +[[package]] +name = "utf8_iter" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af3bd9d3e571c26fcce9d033b87ea5ab061b8d2ffe9b7a5675d810d68f03edf0" +dependencies = [ + "utf_types", +] + +[[package]] +name = "utf_types" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a3b425286980a367278453f3b6d28cdcb134b574e5a35824a6ff5eebad50bb6" + +[[package]] +name = "validator" +version = "0.21.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3d68c6633c483df6780cc5277a417c7c2d1bceee2649d06c8ab6b0fd2dd3c81" +dependencies = [ + "idna", + "regex", + "serde", + "serde_derive", + "serde_json", + "url", + "validator_derive", +] + +[[package]] +name = "validator_derive" +version = "0.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240e4b81c20a1d6d50d1d7265c658dfbd204e8b9ac4d80f3c931f39462196335" +dependencies = [ + "darling", + "proc-macro-error3", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "wasip3" +version = "0.10.0+wasi-0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1657e9f48c63d6c3f143f70d5c6e2be7d463371a7af1ed939a5b83d3ca080d0" +dependencies = [ + "bytes", + "http", + "http-body", + "thiserror", + "wit-bindgen", +] + +[[package]] +name = "wasm-bindgen" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c" +dependencies = [ + "cfg-if", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 3.0.10", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "wasm-encoder" +version = "0.262.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4495a6f85dd94c411c749303efcbc5defade0b0cbdbc0541495241ab917a9b5a" +dependencies = [ + "leb128fmt", + "wasmparser", +] + +[[package]] +name = "wasm-metadata" +version = "0.262.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c86ff6668190d9fb70372b306b4f9fe8930f0e2f57ce72e4922bf2f117900949" +dependencies = [ + "anyhow", + "indexmap", + "wasm-encoder", + "wasmparser", +] + +[[package]] +name = "wasmparser" +version = "0.262.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "974d643b125b272607e2fff8012ea14a8328acd7621e4bafa7afb32500052b1b" +dependencies = [ + "bitflags", + "hashbrown", + "indexmap", + "semver", +] + +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "winnow" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8c3b93199df0ab874cdf0c6a94f0a0dc3423fe41f1cafb62b8bd7b1deb277aef" + +[[package]] +name = "wit-bindgen" +version = "0.63.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b85a987ab61d365382d25c7d47e26edd48941b3bf6e3fbf76eff918bc71dab06" +dependencies = [ + "bitflags", + "futures", + "wit-bindgen-rust-macro", +] + +[[package]] +name = "wit-bindgen-core" +version = "0.63.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "775e122e390603abfacd548027016cd0113a6e2bf2f8ce6bdd3658b013456ea8" +dependencies = [ + "anyhow", + "heck", + "wit-parser", +] + +[[package]] +name = "wit-bindgen-rust" +version = "0.63.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "84e26e13b9d972026778d2ffb7985736de116026fdc8d9464f966e12df2eb240" +dependencies = [ + "anyhow", + "heck", + "indexmap", + "prettyplease", + "syn 3.0.10", + "wasm-metadata", + "wit-bindgen-core", + "wit-component", +] + +[[package]] +name = "wit-bindgen-rust-macro" +version = "0.63.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "16a008a0d6b4840677326beb4edbeb210a2f1b7d0183fb7cc33f466b90fd7fb6" +dependencies = [ + "anyhow", + "prettyplease", + "proc-macro2", + "quote", + "syn 3.0.10", + "wit-bindgen-core", + "wit-bindgen-rust", +] + +[[package]] +name = "wit-component" +version = "0.262.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "078def49fdb49cab405c3006e05793b3fdaf7069126ba6b9c97d01ec8c98fe4c" +dependencies = [ + "anyhow", + "bitflags", + "indexmap", + "log", + "serde", + "serde_derive", + "serde_json", + "wasm-encoder", + "wasm-metadata", + "wasmparser", + "wit-parser", +] + +[[package]] +name = "wit-parser" +version = "0.262.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00f0dc051466ffe46787721fca3d088536f158ae400be044f1b1c386ba9397ad" +dependencies = [ + "anyhow", + "hashbrown", + "id-arena", + "indexmap", + "log", + "semver", + "serde", + "serde_derive", + "serde_json", + "unicode-ident", + "wasmparser", +] + +[[package]] +name = "writeable" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" + +[[package]] +name = "yoke" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "417ef3fcf6c300b7dbd25c85531a746931c02ad536f3cf4786ed1e88223340b3" +dependencies = [ + "stable_deref_trait", + "yoke-derive", + "zerofrom", +] + +[[package]] +name = "yoke-derive" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", + "synstructure", +] + +[[package]] +name = "zerofrom" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" +dependencies = [ + "zerofrom-derive", +] + +[[package]] +name = "zerofrom-derive" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", + "synstructure", +] + +[[package]] +name = "zerotrie" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f" +dependencies = [ + "displaydoc", + "yoke", + "zerofrom", +] + +[[package]] +name = "zerovec" +version = "0.11.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f58a2799cfe9a1670c7ea8edbd52ef8edb93cb37a7f83bf31ba9e35d9dae6a40" +dependencies = [ + "yoke", + "zerofrom", + "zerovec-derive", +] + +[[package]] +name = "zerovec-derive" +version = "0.11.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3743ddbf47738d929cd1ae2e199d40d0162979dfe31aef8ae646d2bf00bf97a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/examples/geo-spin-loader/Cargo.toml b/examples/geo-spin-loader/Cargo.toml new file mode 100644 index 00000000..be6ce218 --- /dev/null +++ b/examples/geo-spin-loader/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "geo-spin-loader" +version = "0.0.0" +edition = "2024" +publish = false +[workspace] +[lib] +crate-type = ["cdylib", "rlib"] +[dependencies] +anyhow = "1" +edgezero-core = { path = "../../crates/edgezero-core", default-features = false } +edgezero-adapter-spin = { path = "../../crates/edgezero-adapter-spin", features = ["spin"] } +geo-kv-prototype = { path = "../geo-kv-prototype", features = ["publisher"] } +serde_json = "1" +spin-sdk = { version = "=8.0.0", default-features = false, features = ["http"] } +subtle = "2" diff --git a/examples/geo-spin-loader/README.md b/examples/geo-spin-loader/README.md new file mode 100644 index 00000000..525c6d11 --- /dev/null +++ b/examples/geo-spin-loader/README.md @@ -0,0 +1,89 @@ +# Publish a pinned geo dataset into Spin KV + +This separate operator application reuses the KV geo tool's artifact validation, +immutable publication and full remote-tree verification. It is never part of the +serving application. It requires Python 3.11+, Rust with `wasm32-wasip2`, and Spin +4.1.0. The runner supports macOS/Linux and invokes the installed Spin executable; +it neither provisions resources nor deploys an app. + +Build the loader from the repository root: + +```sh +cargo build --locked --release --manifest-path examples/geo-spin-loader/Cargo.toml \ + --target wasm32-wasip2 +cargo test --locked --manifest-path examples/geo-spin-loader/Cargo.toml +python3 -m unittest discover -s examples/geo-spin-loader -p test_load.py +``` + +First [build and verify a permitted geo artifact](../geo-kv-prototype/README.md). +Keep licensed CSV, derived artifacts, inventories, credentials and runtime databases +outside Git and release images. The loader stages an owned temporary artifact copy +inside its application directory because Spin only maps files from that directory. +The guest reads the mounted `/artifact`; the runner removes its temporary copy, +manifest, logs and state on exit. Account for this temporary disk usage and the +host's temporary-storage retention policy. + +Create an explicit Spin runtime configuration outside Git. For local file-backed +storage, use an absolute path shared by loader and serving: + +```toml +[key_value_store.geo_runtime] +type = "spin" +path = "/srv/edgezero/geography.db" +``` + +Create the parent directory and ensure the process has access. Supply the same +configuration file, exact named store and backend credentials to both applications. +A relative path or two implicit `.spin` directories may load an entirely different +database. Stop local SQLite serving during publication. External Redis, CosmosDB +and DynamoDB backing are configured through Spin's supported runtime configuration; +local tests do not qualify their credentials, propagation, quotas or permissions. +Do not populate Spin's SQLite tables directly: their format is not a stable API. + +```sh +python3 examples/geo-spin-loader/load.py \ + --spin spin \ + --artifact "$GEO_ARTIFACT" \ + --runtime-config "$SPIN_RUNTIME_CONFIG" \ + --store geo_runtime +``` + +`--spin` accepts a PATH command or an executable path. `--wasm` overrides the built +component path. The runner creates a loopback-only component manifest with the +selected store permission, generates an ephemeral credential, and supplies it through +Spin's environment-backed variable provider. Its POST sends that credential from +process memory. No credential appears in arguments, source, reports or logs. The +listener is not an origin upload endpoint; do not add it to a public Spin manifest. +Readiness defaults to 30 seconds, total publication to 600 seconds; finite positive +`--readiness-timeout` and `--publication-timeout` overrides are supported. A watchdog +stops the owned runtime when the publication window expires, even if a response keeps +sending bytes. Success, failure, interruption and timeout stop and reap the child. + +The loader authenticates before reading artifacts. It validates inventory closure +and hashes before opening the remote store, skips byte-identical objects, rejects +conflicts, writes absent objects, reads each write back, publishes the manifest last, +and verifies the complete remote tree. The report contains counts and the exact +`@` pin. On an interrupted or uncertain write, rerun the +same artifact: publication is resumable. A single operator must own each generation; +read-before-write is not a distributed lock. There is no overwrite repair, active +pointer or automatic serving fallback. + +Configuration, startup/transport, authentication, publication and deadline failures +have fixed diagnostic categories. Raw SDK errors and secrets are not printed. Use +the offline artifact verifier to diagnose input failures and supported backend +operator tooling to inspect permissions/conflicts. Publication may leave validated +partial objects on failure; do not select the pin until successful verification. + +After loading, configure the [Spin serving geo selection](../../docs/guide/adapters/spin.md#geographic-context-from-a-pinned-kv-dataset) +and pass the same runtime configuration to `spin up`. Serving must declare physical +store `geo_runtime` and map logical `geo` through +`EDGEZERO__STORES__KV__GEO__NAME=geo_runtime`. Verify through the actual serving +identity/path before selecting the pin across the fleet. Rollback requires a +reverified, still-permitted previous generation. Retirement/deletion and data +licensing remain operator responsibilities. + +The component source is intentionally separate from the serving adapter. Loader +authentication tests and runner tests cover duplicate/wrong credentials, executable +resolution and actual child cleanup on success, startup timeout, publication timeout +and continuously arriving responses. Existing publisher tests cover artifact +validation, replay, conflict, uncertain writes, readback and manifest ordering. diff --git a/examples/geo-spin-loader/load.py b/examples/geo-spin-loader/load.py new file mode 100644 index 00000000..1857dd09 --- /dev/null +++ b/examples/geo-spin-loader/load.py @@ -0,0 +1,160 @@ +#!/usr/bin/env python3 +"""Run a separate, authenticated loopback publisher and always stop its runtime.""" +import argparse +import json +import math +import os +from pathlib import Path +import secrets +import signal +import shutil +import socket +import subprocess +import tempfile +import threading +import time +import tomllib +import urllib.request + + +def publish(spin, wasm, artifact, runtime_config, store, readiness_timeout=30, publication_timeout=600): + executable = shutil.which(spin) + if executable is None: + raise ValueError("Spin executable not found") + spin = str(Path(executable).resolve()) + wasm, artifact, runtime_config = (Path(value).resolve() for value in (wasm, artifact, runtime_config)) + if not wasm.is_file() or not artifact.is_dir(): + raise ValueError("build the loader and supply an artifact directory") + if not all(math.isfinite(value) and value > 0 for value in (readiness_timeout, publication_timeout)): + raise ValueError("deadlines must be finite and positive") + config = tomllib.loads(runtime_config.read_text()) + binding = config.get("key_value_store", {}).get(store) + if not binding: + raise ValueError("runtime configuration must explicitly define the selected store") + if binding.get("type") == "spin" and not Path(binding.get("path", "")).is_absolute(): + raise ValueError("local Spin storage requires an absolute database path") + with socket.socket() as listener: + listener.bind(("127.0.0.1", 0)) + port = listener.getsockname()[1] + token = secrets.token_hex(32) + with tempfile.TemporaryDirectory(prefix="geo-spin-loader-") as raw: + root = Path(raw) + # Spin only maps files within its application directory. Stage an owned copy. + shutil.copytree(artifact, root / "artifact") + manifest = root / "spin.toml" + quote = json.dumps + manifest.write_text(f'''spin_manifest_version = 2 +[application] +name = "geo-spin-loader" +version = "0.0.0" +[variables] +loader_token = {{ required = true, secret = true }} +loader_store = {{ required = true }} +[[trigger.http]] +route = "/..." +component = "loader" +[component.loader] +source = {quote(str(wasm))} +files = [{{ source = "artifact", destination = "/artifact" }}] +key_value_stores = [{quote(store)}] +[component.loader.variables] +loader_token = "{{{{ loader_token }}}}" +loader_store = "{{{{ loader_store }}}}" +''') + env = dict(os.environ, SPIN_VARIABLE_LOADER_TOKEN=token, SPIN_VARIABLE_LOADER_STORE=store) + process = None + timer = None + expired = threading.Event() + with (root / "runtime.log").open("wb") as log: + try: + process = subprocess.Popen( + [spin, "up", "--from", str(manifest), "--listen", f"127.0.0.1:{port}", + "--runtime-config-file", str(runtime_config)], + cwd=root, env=env, stdout=log, stderr=subprocess.STDOUT, + ) + ready_by = time.monotonic() + readiness_timeout + while True: + if process.poll() is not None: + raise OSError("loader runtime exited before readiness") + if time.monotonic() >= ready_by: + raise TimeoutError("loader readiness deadline exceeded") + try: + with socket.create_connection(("127.0.0.1", port), timeout=0.1): + break + except OSError: + time.sleep(0.025) + def expire(): + expired.set() + if process.poll() is None: + try: + process.kill() + except ProcessLookupError: + pass + timer = threading.Timer(publication_timeout, expire) + timer.daemon = True + timer.start() + request = urllib.request.Request( + f"http://127.0.0.1:{port}/publish", data=b"", method="POST", + headers={"x-edgezero-loader-token": token}, + ) + # The secret stays in process memory/environment, never argv or a log. + opener = urllib.request.build_opener(urllib.request.ProxyHandler({})) + with opener.open(request, timeout=publication_timeout) as response: + payload = response.read(4097) + if len(payload) > 4096: + raise OSError("invalid publication report") + if expired.is_set(): + raise TimeoutError("publication deadline exceeded") + return json.loads(payload) + except Exception: + if expired.is_set(): + raise TimeoutError("publication deadline exceeded") from None + raise + finally: + if timer is not None: + timer.cancel() + timer.join() + if process is not None: + try: + process.terminate() + except ProcessLookupError: + pass + try: + process.wait(timeout=5) + except subprocess.TimeoutExpired: + process.kill() + process.wait() + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--spin", default="spin") + parser.add_argument("--wasm", type=Path, default=Path(__file__).parent / "target/wasm32-wasip2/release/geo_spin_loader.wasm") + parser.add_argument("--artifact", type=Path, required=True) + parser.add_argument("--runtime-config", type=Path, required=True) + parser.add_argument("--store", required=True) + parser.add_argument("--readiness-timeout", type=float, default=30) + parser.add_argument("--publication-timeout", type=float, default=600) + args = parser.parse_args() + signal.signal(signal.SIGTERM, lambda *_: (_ for _ in ()).throw(KeyboardInterrupt())) + try: + report = publish(args.spin, args.wasm, args.artifact, args.runtime_config, args.store, + args.readiness_timeout, args.publication_timeout) + print(json.dumps(report, sort_keys=True)) + except KeyboardInterrupt: + raise SystemExit(130) from None + except TimeoutError: + parser.exit(1, "loader readiness or publication deadline exceeded\n") + except urllib.error.HTTPError as error: + category = "authentication rejected" if error.code == 401 else "artifact publication or verification rejected" + parser.exit(1, f"loader: {category}\n") + except ValueError: + parser.exit(1, "invalid loader configuration or publication report\n") + except OSError: + parser.exit(1, "loader runtime startup or transport failed\n") + except Exception: + parser.exit(1, "dataset publication failed\n") + + +if __name__ == "__main__": + main() diff --git a/examples/geo-spin-loader/spin.toml b/examples/geo-spin-loader/spin.toml new file mode 100644 index 00000000..0ab8490e --- /dev/null +++ b/examples/geo-spin-loader/spin.toml @@ -0,0 +1,19 @@ +# Reference manual manifest. Prefer load.py, which generates an isolated manifest, +# stages the artifact, supplies variables and enforces listener/deadline cleanup. +spin_manifest_version = 2 +[application] +name = "geo-spin-loader" +version = "0.0.0" +[variables] +loader_token = { required = true, secret = true } +loader_store = { default = "geo_runtime" } +[[trigger.http]] +route = "/..." +component = "loader" +[component.loader] +source = "target/wasm32-wasip2/release/geo_spin_loader.wasm" +files = [{ source = "artifact", destination = "/artifact" }] +key_value_stores = ["geo_runtime"] +[component.loader.variables] +loader_token = "{{ loader_token }}" +loader_store = "{{ loader_store }}" diff --git a/examples/geo-spin-loader/src/lib.rs b/examples/geo-spin-loader/src/lib.rs new file mode 100644 index 00000000..e9d25339 --- /dev/null +++ b/examples/geo-spin-loader/src/lib.rs @@ -0,0 +1,112 @@ +//! Separate operator component; never include this route in a serving application. +#[cfg(any(test, all(target_arch = "wasm32", target_os = "wasi")))] +use edgezero_core::http::HeaderMap; +#[cfg(any(test, all(target_arch = "wasm32", target_os = "wasi")))] +use subtle::ConstantTimeEq as _; + +#[cfg(any(test, all(target_arch = "wasm32", target_os = "wasi")))] +fn authenticated(headers: &HeaderMap, expected: &[u8]) -> bool { + let valid = + |value: &[u8]| (32..=128).contains(&value.len()) && value.iter().all(u8::is_ascii_graphic); + let mut values = headers.get_all("x-edgezero-loader-token").iter(); + values.next().is_some_and(|value| { + values.next().is_none() + && valid(value.as_bytes()) + && valid(expected) + && bool::from(value.as_bytes().ct_eq(expected)) + }) +} + +#[cfg(all(target_arch = "wasm32", target_os = "wasi"))] +mod component { + use super::authenticated; + use edgezero_core::app::Hooks; + use edgezero_core::context::RequestContext; + use edgezero_core::http::response_builder; + use edgezero_core::http::{Response, StatusCode}; + use edgezero_core::key_value_store::KvHandle; + use edgezero_core::router::RouterService; + use edgezero_core::{Body, EdgeError, action}; + use geo_kv_prototype::publication::{Artifact, publish, verify}; + use std::{path::Path, sync::Arc}; + + struct Loader; + impl Hooks for Loader { + fn routes() -> Result { + Ok(RouterService::builder().post("/publish", load).build()) + } + } + fn response(status: StatusCode, body: String) -> Result { + response_builder() + .status(status) + .header("content-type", "application/json") + .header("cache-control", "no-store") + .body(Body::from(body)) + .map_err(EdgeError::internal) + } + #[action] + async fn load(ctx: RequestContext) -> Result { + let expected = spin_sdk::variables::get("loader_token").await; + if !expected + .as_ref() + .is_ok_and(|value| authenticated(ctx.headers(), value.as_bytes())) + { + return response( + StatusCode::UNAUTHORIZED, + "{\"error\":\"unauthorized\"}".into(), + ); + } + let result = async { + let artifact = Artifact::open(Path::new("/artifact")).await?; + let label = spin_sdk::variables::get("loader_store").await?; + let store = edgezero_adapter_spin::key_value_store::SpinKvStore::open(&label).await?; + let kv = KvHandle::new(Arc::new(store)); + let report = publish(&artifact, &kv).await?; + verify(&artifact, kv).await?; + Ok::<_, anyhow::Error>(serde_json::json!({ + "objects": report.objects, "written": report.written, "identical": report.identical, + "pin": format!("{}@{}", artifact.receipt.manifest_key.split('/').nth(2).unwrap_or(""), geo_kv_prototype::index::hex(&artifact.receipt.manifest_hash)), + })) + }.await; + match result { + Ok(report) => response(StatusCode::OK, report.to_string()), + Err(_) => response( + StatusCode::INTERNAL_SERVER_ERROR, + "{\"error\":\"publication failed\"}".into(), + ), + } + } + #[spin_sdk::http_service] + async fn handle( + req: spin_sdk::http::Request, + ) -> anyhow::Result { + edgezero_adapter_spin::run_app::(req).await + } +} + +#[cfg(test)] +mod tests { + use super::*; + use edgezero_core::http::HeaderValue; + #[test] + fn loader_requires_one_valid_credential() { + let token = b"0123456789abcdef0123456789abcdef"; + let mut headers = HeaderMap::new(); + assert!(!authenticated(&headers, token)); + headers.insert( + "x-edgezero-loader-token", + HeaderValue::from_bytes(token).unwrap(), + ); + assert!(authenticated(&headers, token)); + assert!(!authenticated( + &headers, + b"ffffffffffffffffffffffffffffffff" + )); + assert!(!authenticated(&headers, b"short")); + headers.append( + "x-edgezero-loader-token", + HeaderValue::from_bytes(token).unwrap(), + ); + assert!(!authenticated(&headers, token)); + } +} diff --git a/examples/geo-spin-loader/test_load.py b/examples/geo-spin-loader/test_load.py new file mode 100644 index 00000000..a7eccdfc --- /dev/null +++ b/examples/geo-spin-loader/test_load.py @@ -0,0 +1,84 @@ +import importlib.util +import os +from pathlib import Path +import tempfile +import unittest +from unittest.mock import patch + +spec = importlib.util.spec_from_file_location("geo_load", Path(__file__).with_name("load.py")) +loader = importlib.util.module_from_spec(spec) +spec.loader.exec_module(loader) + +FAKE_SPIN = '''#!/usr/bin/env python3 +import http.server, json, os, sys, time +from pathlib import Path +Path(os.environ["GEO_TEST_PID"]).write_text(str(os.getpid())) +mode = os.environ["GEO_TEST_MODE"] +if mode == "readiness": + time.sleep(60) +listen = sys.argv[sys.argv.index("--listen") + 1] +class Handler(http.server.BaseHTTPRequestHandler): + def do_POST(self): + if mode == "publication": time.sleep(60) + if mode == "drip": + self.send_response(200); self.send_header("Content-Length", "24"); self.end_headers() + for _ in range(24): + self.wfile.write(b" "); self.wfile.flush(); time.sleep(0.1) + return + expected = os.environ["SPIN_VARIABLE_LOADER_TOKEN"] + if self.headers.get("x-edgezero-loader-token") != expected: + self.send_response(401); self.end_headers(); return + payload = json.dumps({"objects":1,"written":1,"identical":0,"pin":"test"}).encode() + self.send_response(200); self.send_header("Content-Length", str(len(payload))) + self.end_headers(); self.wfile.write(payload) + def log_message(self, *_): pass +http.server.HTTPServer(("127.0.0.1", int(listen.split(":")[1])), Handler).serve_forever() +''' + +class RunnerTests(unittest.TestCase): + def run_case(self, mode): + with tempfile.TemporaryDirectory() as raw: + root = Path(raw) + fake = root / "spin" + fake.write_text(FAKE_SPIN) + fake.chmod(0o700) + wasm = root / "loader.wasm" + wasm.write_bytes(b"test") + artifact = root / "artifact" + artifact.mkdir() + config = root / "runtime.toml" + config.write_text(f'[key_value_store.geo]\ntype="spin"\npath="{root}/db"\n') + pid = root / "pid" + old = {key: os.environ.get(key) for key in ["GEO_TEST_MODE", "GEO_TEST_PID"]} + os.environ.update(GEO_TEST_MODE=mode, GEO_TEST_PID=str(pid)) + spawned = [] + original_popen = loader.subprocess.Popen + def start(*args, **kwargs): + child = original_popen(*args, **kwargs) + spawned.append(child) + return child + try: + with patch.object(loader.subprocess, "Popen", side_effect=start): + self.check_result(mode, fake, wasm, artifact, config) + self.assertEqual(len(spawned), 1) + self.assertIsNotNone(spawned[0].returncode, "runner must reap its child") + with self.assertRaises(ProcessLookupError): + os.kill(spawned[0].pid, 0) + finally: + for key, value in old.items(): + if value is None: os.environ.pop(key, None) + else: os.environ[key] = value + + def check_result(self, mode, fake, wasm, artifact, config): + if mode in ("success", "relative"): + self.assertEqual(loader.publish(os.path.relpath(fake) if mode == "relative" else str(fake), wasm, artifact, config, "geo", 2, 2)["objects"], 1) + else: + with self.assertRaises((TimeoutError, OSError)): + loader.publish(str(fake), wasm, artifact, config, "geo", 0.4 if mode == "readiness" else 2, 0.4) + def test_relative_executable_survives_temporary_cwd(self): self.run_case("relative") + def test_success_stops_child(self): self.run_case("success") + def test_readiness_timeout_stops_child(self): self.run_case("readiness") + def test_publication_timeout_stops_child(self): self.run_case("publication") + def test_total_deadline_stops_a_dripping_response(self): self.run_case("drip") + +if __name__ == "__main__": unittest.main() From ec0b912b98e8cea88b637a30452c6f061be7c7f5 Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Wed, 18 Nov 2026 20:08:51 +0530 Subject: [PATCH 4/4] ci: allow standalone Spin loader lifecycle tests --- .github/actions/deploy-core/tests/run.sh | 69 +++++++++++++++++++++--- 1 file changed, 63 insertions(+), 6 deletions(-) diff --git a/.github/actions/deploy-core/tests/run.sh b/.github/actions/deploy-core/tests/run.sh index 8cf5e952..80d93fa1 100755 --- a/.github/actions/deploy-core/tests/run.sh +++ b/.github/actions/deploy-core/tests/run.sh @@ -897,6 +897,66 @@ test_workspace_isolation() { assert_succeeds "cleanup refuses a workspace outside RUNNER_TEMP" test -d "$outside" } +# The standalone Spin operator's lifecycle suite uses Python, outside deployment +# action tooling. Admit only its exact file-backed unittest command in test.yml; +# inline programs, other workflows, installers and appended commands stay banned. +filter_loader_unit_tests() { + local allowed_workflow="$1" embedded_language=py"thon" + local approved_command="${embedded_language}3 -m unittest discover -s examples/geo-spin-loader -p test_load.py" + local entry remainder candidate_command + while IFS= read -r entry; do + if [[ "$entry" == "$allowed_workflow":* ]]; then + remainder=${entry#"$allowed_workflow":} + candidate_command=${remainder#*:} + candidate_command=${candidate_command#"${candidate_command%%[![:space:]]*}"} + if [[ "$candidate_command" == "$approved_command" ]]; then + continue + fi + fi + printf '%s\n' "$entry" + done +} + +unapproved_ci_commands() { + local allowed_workflow="$1" embedded_language=py"thon" + shift + local command_pattern="(^|[[:space:]|;&])(${embedded_language}3?|pip3?|pipx)([[:space:]]|$)" + grep -REn --include='*.sh' --include='*.yml' -E "$command_pattern" "$@" | + grep -vE ':[0-9]+:[[:space:]]*#' | + filter_loader_unit_tests "$allowed_workflow" || true +} + +test_standalone_loader_ci_tool_exception() { + section "standalone loader unittest command exception" + local fixture="$WORK_DIR/ci-tool-policy" embedded_language=py"thon" installer=pi"p3" heredoc_marker=P"Y" + local approved_command="${embedded_language}3 -m unittest discover -s examples/geo-spin-loader -p test_load.py" + local variant actual + mkdir -p "$fixture" + printf ' %s\n' "$approved_command" > "$fixture/test.yml" + actual=$(unapproved_ci_commands "$fixture/test.yml" "$fixture") + assert_equals "exact standalone lifecycle command is admitted" "" "$actual" + for variant in \ + "$approved_command --failfast" \ + "$approved_command; true" \ + "$approved_command && true" \ + "$approved_command # appended comment" \ + "${embedded_language}3 -c pass" \ + "${embedded_language}3 - <<'${heredoc_marker}'" \ + "$installer install package"; do + printf ' %s\n' "$variant" > "$fixture/test.yml" + actual=$(unapproved_ci_commands "$fixture/test.yml" "$fixture") + assert_equals "non-approved command remains rejected: $variant" "$fixture/test.yml:1: $variant" "$actual" + done + printf ' %s\n' "$approved_command" > "$fixture/test.yml" + printf ' %s\n' "$approved_command" > "$fixture/other.yml" + actual=$(unapproved_ci_commands "$fixture/test.yml" "$fixture") + assert_equals "another workflow cannot use the exception" "$fixture/other.yml:1: $approved_command" "$actual" + rm "$fixture/other.yml" + printf ' %s\n' "$approved_command" > "$fixture/action.sh" + actual=$(unapproved_ci_commands "$fixture/test.yml" "$fixture") + assert_equals "action scripts cannot use the exception" "$fixture/action.sh:1: $approved_command" "$actual" +} + test_no_inline_action_scripts() { section "actions use script files, never inline run:" # Every composite `run:` must invoke a `.sh` file — no inline shell in YAML, which @@ -913,12 +973,8 @@ test_no_inline_action_scripts() { bad=$(grep -REn --include='*.sh' -E "$embedded_python_pattern" "$ACTIONS_DIR" || true) assert_equals "action shell scripts contain no embedded Python programs" "" "$bad" - local command_pattern="(^|[[:space:]|;&])(${embedded_language}3?|pip3?|pipx)([[:space:]]|$)" - bad=$( - grep -REn --include='*.sh' --include='*.yml' -E "$command_pattern" \ - "$ACTIONS_DIR" "$REPO_ROOT/.github/workflows" "$REPO_ROOT/scripts/run_coverage.sh" | - grep -vE ':[0-9]+:[[:space:]]*#' || true - ) + bad=$(unapproved_ci_commands "$REPO_ROOT/.github/workflows/test.yml" \ + "$ACTIONS_DIR" "$REPO_ROOT/.github/workflows" "$REPO_ROOT/scripts/run_coverage.sh") assert_equals "action and CI tooling use only approved shell tools" "" "$bad" } @@ -3802,6 +3858,7 @@ main() { test_workspace_isolation test_workspace_step_scrub test_no_inline_action_scripts + test_standalone_loader_ci_tool_exception test_deploy_args_prepend test_lifecycle_helpers test_capture_previous