diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index fbaf01b02..0bb94c86a 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -188,6 +188,15 @@ jobs: if: matrix.suite == 'workspace' run: bash scripts/check_native_store_dependency_contract.sh + - name: Check portable record providers on wasm targets + if: matrix.suite == 'workspace' + run: | + for target in wasm32-wasip1 wasm32-unknown-unknown wasm32-wasip2; do + cargo check --offline --locked -p edgezero-store-aws --no-default-features --features dynamodb-records-portable --target "$target" + cargo check --offline --locked -p edgezero-store-celld --no-default-features --features portable-records --target "$target" + done + cargo check --offline --locked -p edgezero-adapter-fastly --features fastly,aws-dynamodb-records,celld-records --target wasm32-wasip1 + - name: Geo dependency isolation run: bash scripts/check_geo_dependency_contract.sh @@ -321,7 +330,7 @@ jobs: - name: Native provider integration runner tests if: matrix.suite == 'cli' - run: node --test scripts/native_aws_test_admin.test.mjs scripts/run_native_aws_integration.test.mjs scripts/run_native_celld_integration.test.mjs scripts/run_celld_store_fleet_proof.test.mjs services/celld-store/test/*.test.mjs + run: node --test scripts/native_aws_test_admin.test.mjs scripts/run_native_aws_integration.test.mjs scripts/run_native_celld_integration.test.mjs scripts/fetch_official_celld.test.mjs scripts/run_celld_store_fleet_proof.test.mjs services/celld-store/test/*.test.mjs - name: Generated native AWS independent service contracts if: matrix.suite == 'cli' @@ -628,3 +637,108 @@ jobs: include-hidden-files: true if-no-files-found: ignore retention-days: 14 + + # Required check: "Portable record contracts (Fastly)". Portable DynamoDB and celld + # providers through the canonical Fastly path in pinned Viceroy, against DynamoDB + # Local and official celld 0.6.3 behind TLS, plus real-service native interop. + portable-record-contracts: + name: Portable record contracts (Fastly) + runs-on: ubuntu-latest + env: + VICEROY_REVISION: a69d982d1d95e13c0fc9f92683b9118639bb4b04 + VICEROY_LOCK_SHA256: d642d177081f42aec75d25c0d1124c013d3abcb081886251420a90e9c53c1a2a + VICEROY_PATCH_SHA256: 42ff805147e003e0bec6ec190a5e72cab2ef445582940818c056f2718162663d + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + + - name: Cache Cargo dependencies + uses: actions/cache@v5 + with: + path: | + ~/.cargo/bin/ + ~/.cargo/registry/index/ + ~/.cargo/registry/cache/ + ~/.cargo/git/db/ + target/ + crates/edgezero-test-harness/fixtures/reusable-app/target/ + crates/edgezero-test-harness/target/ + key: ${{ runner.os }}-cargo-portable-records-v1-${{ hashFiles('**/Cargo.lock', '.tool-versions') }} + restore-keys: | + ${{ runner.os }}-cargo-portable-records-v1- + + - name: Retrieve tool versions + id: versions + shell: bash + run: | + echo "rust=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT" + echo "node=$(grep '^nodejs ' .tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT" + + - name: Set up Rust tool chain + uses: actions-rust-lang/setup-rust-toolchain@v1 + with: + cache: "false" + toolchain: ${{ steps.versions.outputs.rust }} + target: wasm32-wasip1 + + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version: ${{ steps.versions.outputs.node }} + + - name: Fetch dependencies (locked) + run: | + cargo fetch --locked + cargo fetch --locked --manifest-path crates/edgezero-test-harness/Cargo.toml + cargo fetch --locked --manifest-path crates/edgezero-test-harness/fixtures/reusable-app/Cargo.toml + + - name: Resolve Viceroy version + id: viceroy-version + shell: bash + run: bash scripts/ci_viceroy.sh keys + + - name: Cache pinned stock Viceroy + uses: actions/cache@v5 + with: + path: ${{ runner.temp }}/viceroy-stock + key: viceroy-stock-v1-${{ runner.os }}-${{ runner.arch }}-${{ steps.viceroy-version.outputs.stock-key }} + + - name: Setup Viceroy + run: bash scripts/ci_viceroy.sh stock + + - name: Cache isolated Viceroy readiness build + uses: actions/cache@v5 + with: + path: ${{ runner.temp }}/viceroy-readiness + key: viceroy-readiness-v1-${{ runner.os }}-${{ runner.arch }}-${{ steps.viceroy-version.outputs.repair-key }} + + - name: Build isolated Viceroy readiness repair + id: viceroy-repair + shell: bash + run: bash scripts/ci_viceroy.sh repair + + - name: Provision official celld 0.6.3 + id: celld + shell: bash + run: echo "binary=$(node scripts/fetch_official_celld.mjs "$RUNNER_TEMP/celld")" >> "$GITHUB_OUTPUT" + + - name: Run portable record contracts + env: + VICEROY_BIN: ${{ steps.viceroy-repair.outputs.executable }} + CELLD_BIN: ${{ steps.celld.outputs.binary }} + run: | + openssl version + docker version --format '{{.Server.Version}}' + CARGO_NET_OFFLINE=true node scripts/run_portable_record_contract.mjs \ + --output "$GITHUB_WORKSPACE/.runs/portable-record-contracts" + + - name: Preserve portable record evidence + if: always() + uses: actions/upload-artifact@v4 + with: + name: portable-record-contract-evidence + path: .runs/portable-record-contracts/ + include-hidden-files: true + if-no-files-found: ignore + retention-days: 14 diff --git a/Cargo.lock b/Cargo.lock index 42cf5e676..2d84d6e32 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1171,10 +1171,13 @@ version = "0.1.0" dependencies = [ "base16ct", "edgezero-core", + "edgezero-store-aws", + "edgezero-store-celld", "serde", "serde_json", "sha2 0.11.1", "tempfile", + "thiserror 2.0.21", "toml", "walkdir", ] @@ -1265,6 +1268,8 @@ dependencies = [ "ctor", "edgezero-adapter", "edgezero-core", + "edgezero-store-aws", + "edgezero-store-celld", "fastly", "fastly-shared", "fastly-sys", @@ -1325,6 +1330,8 @@ dependencies = [ "edgezero-adapter-fastly", "edgezero-adapter-spin", "edgezero-core", + "edgezero-store-aws", + "edgezero-store-celld", "futures", "handlebars", "httparse", @@ -1338,7 +1345,9 @@ dependencies = [ "syn 3.0.9", "tempfile", "thiserror 2.0.21", + "tokio", "toml", + "toml_edit", "url", "validator", "walkdir", @@ -1413,12 +1422,15 @@ version = "0.1.0" dependencies = [ "async-trait", "aws-config", + "aws-credential-types", "aws-sdk-dynamodb", "aws-sdk-secretsmanager", + "aws-sigv4", "aws-smithy-runtime-api", "aws-types", "base64", "bytes", + "edgezero-adapter-axum", "edgezero-core", "futures", "futures-util", @@ -1431,6 +1443,7 @@ dependencies = [ "tokio", "toml", "url", + "web-time", ] [[package]] @@ -1440,6 +1453,7 @@ dependencies = [ "async-trait", "base64", "bytes", + "edgezero-adapter-axum", "edgezero-core", "futures-util", "getrandom 0.4.2", diff --git a/Cargo.toml b/Cargo.toml index 3f5831727..22da4e1ba 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -44,6 +44,8 @@ async-trait = "0.1" aws-config = { version = "=1.12.0", default-features = false, features = ["default-https-client", "rt-tokio", "credentials-process", "sso"] } aws-sdk-dynamodb = { version = "=1.120.0", default-features = false, features = ["default-https-client", "rt-tokio"] } aws-sdk-secretsmanager = { version = "=1.120.0", default-features = false, features = ["default-https-client", "rt-tokio"] } +aws-credential-types = "=1.3.0" +aws-sigv4 = { version = "=1.6.0", default-features = false, features = ["sign-http", "http1"] } # Preserve the pinned behavior version in fresh warnings-denied consumers. aws-smithy-runtime-api = { version = "=1.19.0", default-features = false, features = ["client"] } # aws-config 1.12 uses smithy-schema 0.2; aws-types 1.7 crosses that type boundary. diff --git a/crates/edgezero-adapter-axum/Cargo.toml b/crates/edgezero-adapter-axum/Cargo.toml index 27626db40..5a5056546 100644 --- a/crates/edgezero-adapter-axum/Cargo.toml +++ b/crates/edgezero-adapter-axum/Cargo.toml @@ -30,7 +30,13 @@ axum = [ "dep:reqwest", "dep:redb", ] -native-bindings = ["dep:toml", "dep:edgezero-store-aws", "dep:edgezero-store-celld"] +native-bindings = [ + "dep:toml", + "dep:edgezero-adapter", + "edgezero-adapter/store-bindings", + "dep:edgezero-store-aws", + "dep:edgezero-store-celld", +] aws-appconfig-agent = ["axum", "edgezero-store-aws/appconfig-agent"] aws-secrets-manager = ["axum", "edgezero-store-aws/secrets-manager"] aws-stores = ["aws-appconfig-agent", "aws-secrets-manager"] @@ -50,9 +56,7 @@ cli = [ test-utils = ["axum", "edgezero-core/test-utils", "dep:validator"] [dependencies] -edgezero-adapter = { path = "../edgezero-adapter", optional = true, features = [ - "cli", -] } +edgezero-adapter = { path = "../edgezero-adapter", optional = true } edgezero-core = { path = "../edgezero-core" } anyhow = { workspace = true } async-trait = { workspace = true } @@ -123,6 +127,8 @@ async-trait = { workspace = true } axum = { workspace = true, features = ["macros"] } edgezero-adapter-cloudflare = { path = "../edgezero-adapter-cloudflare", default-features = false } edgezero-core = { path = "../edgezero-core", features = ["test-utils", "geo-kv-build"] } +edgezero-store-aws = { workspace = true, features = ["dynamodb-records-portable", "dynamodb-records"] } +edgezero-store-celld = { workspace = true, features = ["portable-records", "records"] } flate2 = { workspace = true } http-body = { workspace = true } httparse = { workspace = true } diff --git a/crates/edgezero-adapter-axum/src/dev_server.rs b/crates/edgezero-adapter-axum/src/dev_server.rs index 08dfac472..b0d175ca8 100644 --- a/crates/edgezero-adapter-axum/src/dev_server.rs +++ b/crates/edgezero-adapter-axum/src/dev_server.rs @@ -4772,7 +4772,10 @@ mod record_preparation_tests { .unwrap(); record_plan.kv.insert( "first", - NativeStoreSource::BuiltIn(NativeKvSource::DynamoDbRecords(settings)), + NativeStoreSource::BuiltIn(NativeKvSource::DynamoDbRecords { + settings, + pinned: None, + }), ); assert!( block_on(build_production_stores_with_records( diff --git a/crates/edgezero-adapter-axum/src/geo.rs b/crates/edgezero-adapter-axum/src/geo.rs index 2d5ccaa22..c5ca4216f 100644 --- a/crates/edgezero-adapter-axum/src/geo.rs +++ b/crates/edgezero-adapter-axum/src/geo.rs @@ -485,7 +485,7 @@ impl NativeGeoPlan { .map_err(|_error| NativeGeoConfigError::InvalidSelection)? } Some(NativeStoreSource::BuiltIn( - NativeKvSource::DynamoDbRecords(_) + NativeKvSource::DynamoDbRecords { .. } | NativeKvSource::CelldRecords { .. }, )) => return Err(NativeGeoConfigError::InvalidSelection), Some( diff --git a/crates/edgezero-adapter-axum/src/native_bindings.rs b/crates/edgezero-adapter-axum/src/native_bindings.rs index b237fa926..e891d186b 100644 --- a/crates/edgezero-adapter-axum/src/native_bindings.rs +++ b/crates/edgezero-adapter-axum/src/native_bindings.rs @@ -15,15 +15,16 @@ use std::io::Read as _; use std::os::unix::fs::OpenOptionsExt as _; use std::path::{Path, PathBuf}; +use edgezero_adapter::store_bindings::{ + BindingLimits, ConfigBinding, KvBinding, SecretBinding, StoreBindingsDocument, + StoreBindingsError, +}; use edgezero_core::app::{StoreMetadata, StoresMetadata}; use edgezero_core::env_config::EnvConfig; use edgezero_core::manifest::{ManifestStores, StoreDeclaration}; use edgezero_core::secret_store::MAX_NAME_LEN; -use edgezero_store_aws::settings::{ - AppConfigAgentSettings, AwsPreparationLimits, DynamoDbKvSettings, SecretsManagerSettings, -}; -use edgezero_store_celld::settings::{CelldKvSettings, CelldPreparationLimits}; -use serde::Deserialize; +use edgezero_store_aws::settings::{AwsPreparationLimits, DynamoDbKvLimits}; +use edgezero_store_celld::settings::CelldPreparationLimits; /// Closed bootstrap failures. File, TOML and provider inputs never become source chains. #[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)] @@ -98,35 +99,16 @@ pub struct NativeProviderCapabilities { pub celld_records: bool, } -/// Strict configuration dispatch. Provider-specific fields are validated by AWS settings. -#[derive(Clone, Debug, Deserialize)] -#[serde(tag = "provider", deny_unknown_fields)] -pub enum NativeConfigBinding { - #[serde(rename = "aws-appconfig-agent")] - AppConfigAgent(AppConfigAgentSettings), -} +/// Strict configuration dispatch, shared with every adapter's bindings document. +pub type NativeConfigBinding = ConfigBinding; -/// Strict KV dispatch. The physical namespace is independent of the declared ID. -#[derive(Clone, Debug, Deserialize)] -#[serde(tag = "provider", deny_unknown_fields)] -pub enum NativeKvBinding { - #[serde(rename = "aws-dynamodb")] - DynamoDb(DynamoDbKvSettings), - #[serde(rename = "aws-dynamodb-records")] - DynamoDbRecords(DynamoDbKvSettings), - #[serde(rename = "celld-records")] - CelldRecords(CelldKvSettings), - #[serde(rename = "celld-kv")] - Celld(CelldKvSettings), -} +/// Strict KV dispatch, shared with every adapter's bindings document. Native record +/// bindings keep the SDK credential chain and `token_env`; they reject `credentials`, +/// `token_secret` and the `DynamoDB` `endpoint`, and verify any `pinned` identity. +pub type NativeKvBinding = KvBinding; -/// Strict secret dispatch. No arbitrary remote names or per-request discovery. -#[derive(Clone, Debug, Deserialize)] -#[serde(tag = "provider", deny_unknown_fields)] -pub enum NativeSecretBinding { - #[serde(rename = "aws-secrets-manager")] - SecretsManager(SecretsManagerSettings), -} +/// Strict secret dispatch, shared with every adapter's bindings document. +pub type NativeSecretBinding = SecretBinding; /// Independent explicit preparation policy sources. Same-provider sources cannot compete. #[derive(Clone, Copy, Debug, Default)] @@ -142,25 +124,10 @@ pub struct NativePreparationPolicies { pub celld: CelldPreparationLimits, } -#[derive(Clone, Debug, Default, Deserialize)] -#[serde(deny_unknown_fields)] -struct LimitsTable { - aws: Option, - celld: Option, -} - /// Version 1 native document. Logical IDs and lookup keys remain case-sensitive. -#[derive(Clone, Deserialize)] -#[serde(deny_unknown_fields)] +#[derive(Clone)] pub struct NativeStoreBindings { - version: u32, - #[serde(default)] - config: BTreeMap, - #[serde(default)] - secrets: BTreeMap, - #[serde(default)] - kv: BTreeMap, - limits: Option, + document: StoreBindingsDocument, } impl fmt::Debug for NativeStoreBindings { @@ -180,11 +147,13 @@ impl NativeStoreBindings { secrets: BTreeMap, ) -> Self { Self { - version: 1, - config, - secrets, - kv: BTreeMap::new(), - limits: None, + document: StoreBindingsDocument { + config, + kv: BTreeMap::new(), + limits: None, + secrets, + version: 1, + }, } } @@ -228,8 +197,20 @@ impl NativeStoreBindings { if input.len() > limits.max_file_bytes { return Err(NativeBindingsError::SizeLimit); } - let bindings: Self = - toml::from_str(input).map_err(|_error| NativeBindingsError::Malformed)?; + let bindings = Self { + document: StoreBindingsDocument::parse(input, limits.max_file_bytes).map_err( + |category| match category { + StoreBindingsError::SizeLimit => NativeBindingsError::SizeLimit, + StoreBindingsError::Invalid + | StoreBindingsError::Malformed + | StoreBindingsError::MissingCredentials + | StoreBindingsError::MissingPin + | StoreBindingsError::NotCompiled + | StoreBindingsError::Undeclared + | StoreBindingsError::Unsupported => NativeBindingsError::Malformed, + }, + )?, + }; bindings.validate_with_policies(limits, policies)?; Ok(bindings) } @@ -336,21 +317,22 @@ impl NativeStoreBindings { explicit: NativePreparationPolicySources, ) -> Result { limits.validate()?; - if self.version != 1 { + if self.document.version != 1 { return Err(NativeBindingsError::Invalid); } if self + .document .config .len() - .checked_add(self.secrets.len()) - .and_then(|count| count.checked_add(self.kv.len())) + .checked_add(self.document.secrets.len()) + .and_then(|count| count.checked_add(self.document.kv.len())) .ok_or(NativeBindingsError::SizeLimit)? > limits.max_explicit_ids { return Err(NativeBindingsError::SizeLimit); } - let file_aws = self.limits.as_ref().and_then(|table| table.aws); - let file_celld = self.limits.as_ref().and_then(|table| table.celld); + let file_aws = self.document.limits.as_ref().and_then(|table| table.aws); + let file_celld = self.document.limits.as_ref().and_then(|table| table.celld); if (file_aws.is_some() && explicit.aws.is_some()) || (file_celld.is_some() && explicit.celld.is_some()) { @@ -370,32 +352,48 @@ impl NativeStoreBindings { .map_err(|_category| NativeBindingsError::Invalid)?; let mut aws_mappings = 0_u64; let mut celld_mappings = 0_u64; - for binding in self.kv.values() { + for binding in self.document.kv.values() { let counter = match binding { - NativeKvBinding::DynamoDb(settings) - | NativeKvBinding::DynamoDbRecords(settings) => { + NativeKvBinding::DynamoDb(settings) => { settings .validate() .map_err(|_category| NativeBindingsError::Invalid)?; &mut aws_mappings } - NativeKvBinding::Celld(settings) | NativeKvBinding::CelldRecords(settings) => { + // Native keeps the SDK credential chain and endpoint resolution. + NativeKvBinding::DynamoDbRecords(settings) => { + if settings.credentials.is_some() || settings.endpoint.is_some() { + return Err(NativeBindingsError::Invalid); + } + settings + .validate(DynamoDbKvLimits::default()) + .map_err(|_category| NativeBindingsError::Invalid)?; + &mut aws_mappings + } + NativeKvBinding::Celld(settings) => { settings .validate() .map_err(|_category| NativeBindingsError::Invalid)?; &mut celld_mappings } + // Native keeps `token_env`; `native_settings` rejects a `token_secret`. + NativeKvBinding::CelldRecords(settings) => { + settings + .native_settings() + .map_err(|_category| NativeBindingsError::Invalid)?; + &mut celld_mappings + } }; charge_mappings(counter, 1)?; } - for binding in self.config.values() { + for binding in self.document.config.values() { let NativeConfigBinding::AppConfigAgent(settings) = binding; settings .validate() .map_err(|_category| NativeBindingsError::Invalid)?; charge_mappings(&mut aws_mappings, settings.documents.len())?; } - for binding in self.secrets.values() { + for binding in self.document.secrets.values() { let NativeSecretBinding::SecretsManager(settings) = binding; settings .validate() @@ -414,21 +412,21 @@ impl NativeStoreBindings { #[inline] #[must_use] pub fn config(&self) -> &BTreeMap { - &self.config + &self.document.config } /// Explicit live KV bindings. #[inline] #[must_use] pub fn kv(&self) -> &BTreeMap { - &self.kv + &self.document.kv } /// Adds KV bindings without changing the original config/secrets constructor. #[inline] #[must_use] pub fn with_kv(mut self, kv: BTreeMap) -> Self { - self.kv = kv; + self.document.kv = kv; self } @@ -436,14 +434,17 @@ impl NativeStoreBindings { #[inline] #[must_use] pub fn secrets(&self) -> &BTreeMap { - &self.secrets + &self.document.secrets } /// Selects one typed remote limits policy; it does not merge policy sources. #[inline] #[must_use] pub fn with_aws_limits(mut self, limits: AwsPreparationLimits) -> Self { - self.limits.get_or_insert_with(LimitsTable::default).aws = Some(limits); + self.document + .limits + .get_or_insert_with(BindingLimits::default) + .aws = Some(limits); self } @@ -451,7 +452,10 @@ impl NativeStoreBindings { #[inline] #[must_use] pub fn with_celld_limits(mut self, limits: CelldPreparationLimits) -> Self { - self.limits.get_or_insert_with(LimitsTable::default).celld = Some(limits); + self.document + .limits + .get_or_insert_with(BindingLimits::default) + .celld = Some(limits); self } } @@ -653,22 +657,28 @@ impl<'declarations> NativeSourceSelection<'declarations> { config: resolve( declarations.config, &supplied.config, - bindings.config.keys(), + bindings.document.config.keys(), env, "config", )?, - kv: resolve(declarations.kv, &supplied.kv, bindings.kv.keys(), env, "kv")?, + kv: resolve( + declarations.kv, + &supplied.kv, + bindings.document.kv.keys(), + env, + "kv", + )?, secrets: resolve( declarations.secrets, &supplied.secrets, - bindings.secrets.keys(), + bindings.document.secrets.keys(), env, "secrets", )?, }; - if (!bindings.config.is_empty() && !capabilities.appconfig_agent) - || (!bindings.secrets.is_empty() && !capabilities.secrets_manager) - || bindings.kv.values().any(|binding| match binding { + if (!bindings.document.config.is_empty() && !capabilities.appconfig_agent) + || (!bindings.document.secrets.is_empty() && !capabilities.secrets_manager) + || bindings.document.kv.values().any(|binding| match binding { NativeKvBinding::DynamoDb(_) => !capabilities.dynamodb, NativeKvBinding::DynamoDbRecords(_) => !capabilities.dynamodb_records, NativeKvBinding::Celld(_) => !capabilities.celld_kv, @@ -869,6 +879,30 @@ mod tests { Ok(()) } + #[test] + fn native_record_bindings_keep_native_sources_and_accept_pins() + -> Result<(), NativeBindingsError> { + let limits = NativeBindingsLimits::default(); + let dynamodb = "version=1\n[kv.state]\nprovider='aws-dynamodb-records'\nregion='us-east-1'\ntable='edgezero-kv'\nnamespace='records'\npinned={ table_arn='arn:aws:dynamodb:us-east-1:111122223333:table/edgezero-kv' }\n"; + let celld = "version=1\n[kv.state]\nprovider='celld-records'\nendpoint='https://celld.example.net'\nstore='state'\npinned={ instance='AAAAAAAAAAAAAAAAAAAAAA' }\n[kv.state.access]\nmode='authenticated'\ntoken_env='CELLD_TOKEN'\n"; + NativeStoreBindings::parse(dynamodb, limits)?; + NativeStoreBindings::parse(celld, limits)?; + for portable_only in [ + format!("{dynamodb}credentials={{ secrets='stores' }}\n"), + format!("{dynamodb}endpoint='http://127.0.0.1:8000'\n"), + celld.replace( + "token_env='CELLD_TOKEN'", + "token_secret={ secrets='stores' }", + ), + ] { + assert_eq!( + NativeStoreBindings::parse(&portable_only, limits).err(), + Some(NativeBindingsError::Invalid) + ); + } + Ok(()) + } + #[test] fn celld_schema_is_structural_strict_and_settings_only() -> Result<(), NativeBindingsError> { let limits = NativeBindingsLimits::default(); diff --git a/crates/edgezero-adapter-axum/src/native_stores.rs b/crates/edgezero-adapter-axum/src/native_stores.rs index 7f87db8f9..200162681 100644 --- a/crates/edgezero-adapter-axum/src/native_stores.rs +++ b/crates/edgezero-adapter-axum/src/native_stores.rs @@ -34,12 +34,15 @@ use edgezero_store_aws::AwsPreparation; feature = "aws-dynamodb" )))] use edgezero_store_aws::settings::AwsPreparationLimits; -use edgezero_store_aws::settings::{AgentAccessToken, AppConfigAgentSettings, DynamoDbKvSettings}; +use edgezero_store_aws::settings::{ + AgentAccessToken, AppConfigAgentSettings, DynamoDbKvLimits, DynamoDbKvSettings, + DynamoDbPinnedIdentity, +}; #[cfg(feature = "celld-kv")] use edgezero_store_celld::CelldPreparation; #[cfg(not(feature = "celld-kv"))] use edgezero_store_celld::settings::CelldPreparationLimits; -use edgezero_store_celld::settings::{CelldAccessToken, CelldKvSettings}; +use edgezero_store_celld::settings::{CelldAccessToken, CelldKvSettings, CelldPinnedIdentity}; use crate::config_store_limits::ConfigStoreLimits; use crate::native_bindings::{ @@ -87,10 +90,14 @@ pub(crate) enum NativeConfigSource { pub(crate) enum NativeKvSource { DynamoDb(DynamoDbKvSettings), - DynamoDbRecords(DynamoDbKvSettings), + DynamoDbRecords { + settings: DynamoDbKvSettings, + pinned: Option, + }, CelldRecords { settings: CelldKvSettings, token: Option, + pinned: Option, }, Celld { settings: CelldKvSettings, @@ -389,7 +396,9 @@ impl NativeSourcePlan { "raw binding does not support declared records", )); } - NativeStoreSource::BuiltIn(NativeKvSource::DynamoDbRecords(settings)) => { + NativeStoreSource::BuiltIn(NativeKvSource::DynamoDbRecords { + settings, .. + }) => { if layout.is_none() { return Err(failure( "kv", @@ -480,7 +489,7 @@ impl NativeSourcePlan { matches!( source, NativeStoreSource::BuiltIn( - NativeKvSource::DynamoDb(_) | NativeKvSource::DynamoDbRecords(_) + NativeKvSource::DynamoDb(_) | NativeKvSource::DynamoDbRecords { .. } ) ) }) || self @@ -535,27 +544,35 @@ fn native_kv_source( ) -> anyhow::Result { match binding { NativeKvBinding::DynamoDb(settings) => Ok(NativeKvSource::DynamoDb(settings.clone())), - NativeKvBinding::DynamoDbRecords(settings) => { - Ok(NativeKvSource::DynamoDbRecords(settings.clone())) + NativeKvBinding::DynamoDbRecords(settings) => Ok(NativeKvSource::DynamoDbRecords { + settings: settings.kv_settings(DynamoDbKvLimits::default()), + pinned: settings.pinned.clone(), + }), + NativeKvBinding::Celld(settings) => { + let token = settings + .access + .token_env() + .map(|name| options.celld_token(name)) + .transpose()?; + Ok(NativeKvSource::Celld { + settings: settings.clone(), + token, + }) } - NativeKvBinding::Celld(settings) | NativeKvBinding::CelldRecords(settings) => { + NativeKvBinding::CelldRecords(records) => { + let settings = records + .native_settings() + .map_err(|category| failure("kv", "bindings", &category.to_string()))?; let token = settings .access .token_env() .map(|name| options.celld_token(name)) .transpose()?; - let cloned_settings = settings.clone(); - if matches!(binding, NativeKvBinding::CelldRecords(_)) { - Ok(NativeKvSource::CelldRecords { - settings: cloned_settings, - token, - }) - } else { - Ok(NativeKvSource::Celld { - settings: cloned_settings, - token, - }) - } + Ok(NativeKvSource::CelldRecords { + settings, + token, + pinned: records.pinned.clone(), + }) } } } @@ -680,7 +697,7 @@ impl NativePreparationSessions { declared_layout: Option<&RecordLayout>, ) -> anyhow::Result { match builtin { - NativeKvSource::DynamoDbRecords(settings) => { + NativeKvSource::DynamoDbRecords { settings, pinned } => { let layout = declared_layout.ok_or_else(|| failure("kv", id, "record layout required"))?; #[cfg(feature = "aws-dynamodb-records")] @@ -688,17 +705,25 @@ impl NativePreparationSessions { self.aws .as_mut() .ok_or_else(|| failure("kv", id, "invalid preparation session"))? - .prepare_dynamodb_records(&settings, layout) + .prepare_dynamodb_records_pinned(&settings, layout, pinned.as_ref()) .await .map_err(|category| failure("kv", id, &category.to_string())) } #[cfg(not(feature = "aws-dynamodb-records"))] { - let _: (DynamoDbKvSettings, &RecordLayout) = (settings, layout); + let _: ( + DynamoDbKvSettings, + Option, + &RecordLayout, + ) = (settings, pinned, layout); Err(failure("kv", id, "record provider not compiled")) } } - NativeKvSource::CelldRecords { settings, token } => { + NativeKvSource::CelldRecords { + settings, + token, + pinned, + } => { let layout = declared_layout.ok_or_else(|| failure("kv", id, "record layout required"))?; #[cfg(feature = "celld-records")] @@ -706,14 +731,23 @@ impl NativePreparationSessions { self.celld .as_mut() .ok_or_else(|| failure("kv", id, "invalid preparation session"))? - .prepare_record_store(&settings, layout, token.as_ref()) + .prepare_record_store_pinned( + &settings, + layout, + token.as_ref(), + pinned.as_ref(), + ) .await .map_err(|category| failure("kv", id, &category.to_string())) } #[cfg(not(feature = "celld-records"))] { - let _: (CelldKvSettings, &RecordLayout, Option) = - (settings, layout, token); + let _: ( + CelldKvSettings, + &RecordLayout, + Option, + Option, + ) = (settings, layout, token, pinned); Err(failure("kv", id, "record provider not compiled")) } } diff --git a/crates/edgezero-adapter-axum/src/run_options.rs b/crates/edgezero-adapter-axum/src/run_options.rs index 6b30c605a..01fe4c325 100644 --- a/crates/edgezero-adapter-axum/src/run_options.rs +++ b/crates/edgezero-adapter-axum/src/run_options.rs @@ -12,7 +12,7 @@ use edgezero_core::app::{Hooks, StoresMetadata}; use edgezero_core::env_config::EnvConfig; use edgezero_core::manifest::BakedManifest; use edgezero_store_aws::settings::{AgentAccessToken, AwsPreparationLimits}; -use edgezero_store_celld::settings::{CelldAccessToken, CelldPreparationLimits}; +use edgezero_store_celld::settings::{CelldAccessToken, CelldPreparationLimits, CelldRecordAccess}; use log::LevelFilter; use crate::diagnostics::NativeDiagnosticsHandle; @@ -221,10 +221,15 @@ impl AxumRunOptions { } } for binding in document.kv().values() { - if let NativeKvBinding::Celld(settings) | NativeKvBinding::CelldRecords(settings) = - binding - && let Some(name) = settings.access.token_env() - { + let token_env = match binding { + NativeKvBinding::Celld(settings) => settings.access.token_env(), + NativeKvBinding::CelldRecords(settings) => match &settings.access { + CelldRecordAccess::Authenticated { token_env, .. } => token_env.as_deref(), + CelldRecordAccess::TrustedNetwork { .. } => None, + }, + NativeKvBinding::DynamoDb(_) | NativeKvBinding::DynamoDbRecords(_) => None, + }; + if let Some(name) = token_env { names.entry(name.to_owned()).or_default().1 = true; } } diff --git a/crates/edgezero-adapter-axum/tests/portable_interop.rs b/crates/edgezero-adapter-axum/tests/portable_interop.rs new file mode 100644 index 000000000..0118f0916 --- /dev/null +++ b/crates/edgezero-adapter-axum/tests/portable_interop.rs @@ -0,0 +1,399 @@ +//! Real services only, ignored by default. Run `scripts/run_portable_record_contract.mjs`. +//! `EDGEZERO_PORTABLE_RECORDS_BINDINGS` names the CLI-pinned TOML document containing +//! `dynamodb_records` and `celld_records`. It supplies endpoints, table, namespace, +//! store alias and pinned table/instance identities. `AWS_ENDPOINT_URL_DYNAMODB` must +//! equal the document endpoint; `AWS_REGION=us-east-1` and `AWS_ACCESS_KEY_ID` / +//! `AWS_SECRET_ACCESS_KEY` supply fake Local credentials. `KV__CELLD_RECORDS__CELLD_TOKEN` +//! supplies the authenticated celld token. `SSL_CERT_FILE` names the TLS test CA. +//! Both native reqwest and `AxumOutboundClient` use reqwest's rustls platform verifier, +//! which loads rustls-native-certs on Linux and honors `SSL_CERT_FILE` at client creation. +//! The rejection case runs in a separate process with an unrelated `SSL_CERT_FILE`. +//! No verifier is disabled. The native seed test deliberately leaves `native/seed` +//! for the Viceroy suite to read and delete. All other writes use unique prefixes. + +#![cfg(all(not(target_arch = "wasm32"), feature = "axum"))] +#![expect( + clippy::arbitrary_source_item_ordering, + reason = "keep service setup, shared assertions and ignored entry points together" +)] + +#[cfg(test)] +mod tests { + use std::collections::BTreeSet; + use std::env; + use std::fs; + use std::process; + use std::sync::Arc; + use std::time::{SystemTime, UNIX_EPOCH}; + + use edgezero_adapter_axum::outbound::AxumOutboundClient; + use edgezero_adapter_axum::outbound_executor::AxumOutboundExecutor; + use edgezero_core::key_value_store::{KvError, KvHandle}; + use edgezero_core::outbound::HttpClient; + use edgezero_core::record_store::{ + RecordKeyLayout, RecordLayout, RecordWrite, RecordWriteMode, RecordWriteOutcome, + }; + use edgezero_core::secret_store::{InMemorySecretStore, SecretHandle}; + use edgezero_core::store_registry::BoundSecretStore; + use edgezero_core::time::MonotonicClock; + use edgezero_store_aws::AwsPreparation; + use edgezero_store_aws::portable_dynamodb::PreparedDynamoDbRecords; + use edgezero_store_aws::settings::{ + AwsPreparationLimits, DynamoDbKvLimits, DynamoDbRecordsSettings, + }; + use edgezero_store_celld::CelldPreparation; + use edgezero_store_celld::portable::PreparedCelldRecords; + use edgezero_store_celld::settings::{ + CelldAccess, CelldAccessToken, CelldKvSettings, CelldPreparationLimits, + CelldRecordsSettings, + }; + use serde::de::DeserializeOwned; + + struct Groups; + impl RecordKeyLayout for Groups { + fn id(&self) -> &'static str { + "fastly-record-contract" + } + fn version(&self) -> u32 { + 1 + } + fn validate(&self) -> Result<(), KvError> { + Ok(()) + } + fn partition_prefix<'key>(&self, key: &'key str) -> Result<&'key str, KvError> { + key.find('/') + .filter(|index| *index > 0 && index.saturating_add(1) < key.len()) + .and_then(|index| key.get(..=index)) + .ok_or_else(|| KvError::Validation("expected group/remainder".to_owned())) + } + fn validate_partition(&self, prefix: &str) -> Result<(), KvError> { + if prefix.len() > 1 && prefix.ends_with('/') && prefix.matches('/').count() == 1 { + Ok(()) + } else { + Err(KvError::Validation("expected group/".to_owned())) + } + } + } + + fn layout() -> RecordLayout { + RecordLayout::new(Groups).unwrap() + } + + fn binding(id: &str) -> T + where + T: DeserializeOwned, + { + let path = + env::var("EDGEZERO_PORTABLE_RECORDS_BINDINGS").expect("pinned bindings required"); + let document: toml::Value = toml::from_str(&fs::read_to_string(path).unwrap()).unwrap(); + let mut entry = document["kv"][id].clone(); + entry.as_table_mut().unwrap().remove("provider"); + entry + .try_into() + .unwrap_or_else(|_| panic!("invalid {id} binding")) + } + + fn secrets() -> BoundSecretStore { + let entries = [ + ( + "KV__DYNAMODB_RECORDS__AWS_ACCESS_KEY_ID", + "AWS_ACCESS_KEY_ID", + ), + ( + "KV__DYNAMODB_RECORDS__AWS_SECRET_ACCESS_KEY", + "AWS_SECRET_ACCESS_KEY", + ), + ( + "KV__CELLD_RECORDS__CELLD_TOKEN", + "KV__CELLD_RECORDS__CELLD_TOKEN", + ), + ] + .map(|(key, variable)| { + ( + format!("stores/{key}"), + env::var(variable).expect("fixture credential required"), + ) + }); + BoundSecretStore::new( + SecretHandle::new(Arc::new(InMemorySecretStore::new(entries))), + "stores".to_owned(), + ) + } + + fn client(executor: &AxumOutboundExecutor) -> HttpClient { + HttpClient::with_client(AxumOutboundClient::try_new(executor.handle()).unwrap()) + } + + async fn dynamodb(executor: &AxumOutboundExecutor) -> (KvHandle, KvHandle) { + let settings: DynamoDbRecordsSettings = binding("dynamodb_records"); + assert_eq!( + env::var("AWS_ENDPOINT_URL_DYNAMODB").unwrap(), + settings.endpoint.as_ref().unwrap().as_str() + ); + let mut preparation = + AwsPreparation::new(MonotonicClock::default(), AwsPreparationLimits::default()) + .unwrap(); + let native = preparation + .prepare_dynamodb_records_pinned( + &settings.kv_settings(DynamoDbKvLimits::default()), + &layout(), + settings.pinned.as_ref(), + ) + .await + .unwrap(); + let portable = + PreparedDynamoDbRecords::new("dynamodb_records", &settings, &layout(), secrets()) + .unwrap(); + ( + native, + KvHandle::new(Arc::new(portable.bind(client(executor)))), + ) + } + + fn celld_settings() -> (CelldRecordsSettings, CelldKvSettings, CelldAccessToken) { + let settings: CelldRecordsSettings = binding("celld_records"); + assert!(settings.endpoint.starts_with("https://127.0.0.1:")); + let native = CelldKvSettings { + endpoint: settings.endpoint.clone(), + store: settings.store.clone(), + access: CelldAccess::Authenticated { + token_env: "KV__CELLD_RECORDS__CELLD_TOKEN".to_owned(), + }, + }; + let token = + CelldAccessToken::new(env::var("KV__CELLD_RECORDS__CELLD_TOKEN").unwrap()).unwrap(); + (settings, native, token) + } + + async fn celld(executor: &AxumOutboundExecutor) -> (KvHandle, KvHandle) { + let (settings, native_settings, token) = celld_settings(); + let mut preparation = + CelldPreparation::new(MonotonicClock::default(), CelldPreparationLimits::default()) + .unwrap(); + let native = preparation + .prepare_record_store_pinned( + &native_settings, + &layout(), + Some(&token), + settings.pinned.as_ref(), + ) + .await + .unwrap(); + let portable = + PreparedCelldRecords::new("celld_records", &settings, &layout(), secrets()).unwrap(); + ( + native, + KvHandle::new(Arc::new(portable.bind(client(executor)))), + ) + } + + fn write(body: &[u8], mode: RecordWriteMode) -> RecordWrite<'_> { + RecordWrite { + body, + metadata: Some("interop m\u{e9}tadata"), + ttl: None, + mode, + } + } + + async fn interop(native: &KvHandle, portable: &KvHandle, scan: bool) { + let prefix = format!( + "interop-{}-{}/", + process::id(), + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_nanos() + ); + let keys: Vec<_> = ["native", "portable", "third"] + .map(|suffix| format!("{prefix}{suffix}")) + .into(); + let first = native.require_records().unwrap(); + let second = portable.require_records().unwrap(); + round_trip(native, portable, &keys[0], b"native\0\xff").await; + round_trip(portable, native, &keys[1], b"portable\0\xff").await; + assert_eq!( + first + .insert(&keys[2], write(b"third", RecordWriteMode::Add)) + .await + .unwrap(), + RecordWriteOutcome::Written + ); + cursors(native, portable, &prefix, &keys, scan).await; + for key in &keys { + first.delete(key).await.unwrap(); + assert!(second.lookup(key).await.unwrap().is_none()); + } + } + + async fn round_trip(writer_kv: &KvHandle, reader_kv: &KvHandle, key: &str, body: &[u8]) { + let writer = writer_kv.require_records().unwrap(); + let reader = reader_kv.require_records().unwrap(); + assert_eq!( + writer + .insert(key, write(body, RecordWriteMode::Add)) + .await + .unwrap(), + RecordWriteOutcome::Written + ); + let row = reader.lookup(key).await.unwrap().unwrap(); + assert_eq!(row.body.as_ref(), body); + assert_eq!(row.metadata.as_deref(), Some("interop m\u{e9}tadata")); + assert_eq!( + reader.lookup(key).await.unwrap().unwrap().generation, + writer.lookup(key).await.unwrap().unwrap().generation + ); + assert_eq!( + reader + .insert( + key, + write(b"cas", RecordWriteMode::IfGenerationMatch(row.generation)) + ) + .await + .unwrap(), + RecordWriteOutcome::Written + ); + assert_eq!( + writer + .insert( + key, + write(b"stale", RecordWriteMode::IfGenerationMatch(row.generation)) + ) + .await + .unwrap(), + RecordWriteOutcome::PreconditionFailed + ); + assert_eq!( + writer.lookup(key).await.unwrap().unwrap().body.as_ref(), + b"cas" + ); + assert_eq!( + writer_kv.get_bytes(key).await.unwrap().unwrap().as_ref(), + b"cas" + ); + assert_eq!( + reader_kv.get_bytes(key).await.unwrap().unwrap().as_ref(), + b"cas" + ); + } + + async fn cursors( + native: &KvHandle, + portable: &KvHandle, + prefix: &str, + keys: &[String], + scan: bool, + ) { + let first = native.require_records().unwrap(); + let second = portable.require_records().unwrap(); + // Begin in either transport, continue in the other, including allocator-only pages. + for (start, continuation) in [(&first, &second), (&second, &first)] { + let partition = start.partition(prefix).unwrap(); + let page = start.list_partition(&partition, None, 1).await.unwrap(); + assert!(page.cursor.is_some()); + let mut found: BTreeSet<_> = page.keys.into_iter().collect(); + let mut cursor = page.cursor; + let mut seen = BTreeSet::new(); + while let Some(after) = cursor { + assert!(seen.insert(after.clone()), "repeated partition cursor"); + let next = continuation + .list_partition(&partition, Some(&after), 1) + .await + .unwrap(); + found.extend(next.keys); + cursor = next.cursor; + } + assert_eq!(found, keys.iter().cloned().collect()); + } + if scan { + for (start, continuation) in [(native, portable), (portable, native)] { + let page = start.list_keys_page(prefix, None, 1).await.unwrap(); + assert!(page.cursor.is_some()); + let mut found: BTreeSet<_> = page.keys.into_iter().collect(); + let mut cursor = page.cursor; + let mut seen = BTreeSet::new(); + while let Some(after) = cursor { + assert!(seen.insert(after.clone()), "repeated Scan cursor"); + let next = continuation + .list_keys_page(prefix, Some(&after), 1) + .await + .unwrap(); + found.extend(next.keys); + cursor = next.cursor; + } + assert_eq!(found, keys.iter().cloned().collect()); + } + } + } + + #[tokio::test(flavor = "current_thread")] + #[ignore = "requires pinned bindings and real DynamoDB Local; run portable orchestrator"] + async fn portable_dynamodb_real_service_interop() { + let mut executor = AxumOutboundExecutor::new(); + let (native, portable) = dynamodb(&executor).await; + executor.run_until(interop(&native, &portable, true)).await; + } + + #[tokio::test(flavor = "current_thread")] + #[ignore = "requires pinned bindings and authenticated HTTPS stock celld; run portable orchestrator"] + async fn portable_celld_real_service_interop() { + let mut executor = AxumOutboundExecutor::new(); + let (native, portable) = celld(&executor).await; + executor.run_until(interop(&native, &portable, false)).await; + } + + #[tokio::test(flavor = "current_thread")] + #[ignore = "requires an unrelated SSL_CERT_FILE and real celld TLS endpoint"] + async fn portable_celld_rejects_untrusted_certificate() { + let mut executor = AxumOutboundExecutor::new(); + let (settings, native_settings, token) = celld_settings(); + let mut preparation = + CelldPreparation::new(MonotonicClock::default(), CelldPreparationLimits::default()) + .unwrap(); + preparation + .prepare_record_store_pinned( + &native_settings, + &layout(), + Some(&token), + settings.pinned.as_ref(), + ) + .await + .unwrap_err(); + let portable = + PreparedCelldRecords::new("celld_records", &settings, &layout(), secrets()).unwrap(); + let store = KvHandle::new(Arc::new(portable.bind(client(&executor)))); + executor + .run_until(async { + assert!(matches!( + store.require_records().unwrap().lookup("native/seed").await, + Err(KvError::Unavailable) + )); + }) + .await; + } + + #[tokio::test(flavor = "current_thread")] + #[ignore = "writes native/seed for the portable Viceroy suite to consume and delete"] + async fn portable_native_seed_rows() { + let executor = AxumOutboundExecutor::new(); + for (native, _) in [dynamodb(&executor).await, celld(&executor).await] { + assert_eq!( + native + .require_records() + .unwrap() + .insert( + "native/seed", + RecordWrite { + body: b"native-seed", + metadata: Some("native"), + ttl: None, + mode: RecordWriteMode::Add, + } + ) + .await + .unwrap(), + RecordWriteOutcome::Written + ); + } + } +} diff --git a/crates/edgezero-adapter-fastly/Cargo.toml b/crates/edgezero-adapter-fastly/Cargo.toml index cebf83272..4ba04680d 100644 --- a/crates/edgezero-adapter-fastly/Cargo.toml +++ b/crates/edgezero-adapter-fastly/Cargo.toml @@ -19,15 +19,33 @@ cli = [ "dep:toml_edit", "dep:walkdir", ] -fastly = ["dep:fastly", "dep:fastly-shared", "dep:fastly-sys", "dep:log-fastly"] +fastly = [ + "dep:fastly", + "dep:fastly-shared", + "dep:fastly-sys", + "dep:log-fastly", + "dep:edgezero-adapter", + "edgezero-adapter/store-bindings", +] +# Portable record providers. The bindings document selects them per KV ID at runtime. +aws-dynamodb-records = [ + "fastly", + "dep:edgezero-store-aws", + "edgezero-store-aws/dynamodb-records-portable", +] +celld-records = [ + "fastly", + "dep:edgezero-store-celld", + "edgezero-store-celld/portable-records", +] test-utils = ["edgezero-core/test-utils"] [dependencies] anyhow = { workspace = true } edgezero-core = { path = "../edgezero-core" } -edgezero-adapter = { path = "../edgezero-adapter", optional = true, features = [ - "cli", -] } +edgezero-adapter = { path = "../edgezero-adapter", optional = true } +edgezero-store-aws = { workspace = true, optional = true } +edgezero-store-celld = { workspace = true, optional = true } async-stream = { workspace = true } async-trait = { workspace = true } brotli = { workspace = true } diff --git a/crates/edgezero-adapter-fastly/src/config_store.rs b/crates/edgezero-adapter-fastly/src/config_store.rs index 6f791cc62..005dbcee4 100644 --- a/crates/edgezero-adapter-fastly/src/config_store.rs +++ b/crates/edgezero-adapter-fastly/src/config_store.rs @@ -240,6 +240,18 @@ impl ConfigStore for FastlyConfigStore { } } +/// The optional portable store bindings document. A missing store or entry is `None`; +/// an unreadable, oversized or non-UTF-8 entry is an error, never a silent default. +pub(crate) fn portable_bindings_document( + store: &str, + entry: &str, +) -> Result, ConfigStoreError> { + let Some(opened) = FastlyConfigStore::try_open_optional(store)? else { + return Ok(None); + }; + opened.read_entry(entry, MAX_ENTRY_BYTES) +} + pub(crate) fn logging_level_override() -> Result, ManagedLoggerError> { let binding = FastlyConfigStore::try_open_optional("edgezero_logging") .map_err(|_error| ManagedLoggerError::ConfigurationUnavailable)?; diff --git a/crates/edgezero-adapter-fastly/src/lib.rs b/crates/edgezero-adapter-fastly/src/lib.rs index dc90b32e9..8fe0ccd39 100644 --- a/crates/edgezero-adapter-fastly/src/lib.rs +++ b/crates/edgezero-adapter-fastly/src/lib.rs @@ -30,6 +30,8 @@ pub mod logger; #[cfg(any(test, feature = "test-utils", feature = "fastly"))] pub mod outbound; #[cfg(feature = "fastly")] +mod portable_bindings; +#[cfg(feature = "fastly")] pub mod request; #[cfg(any(test, feature = "fastly"))] pub mod response; @@ -107,7 +109,11 @@ fn build_target_app() -> Result where A: Hooks, { - let app = App::build::(FASTLY_PLATFORM)?; + #[cfg_attr( + not(feature = "fastly"), + expect(unused_mut, reason = "only Fastly installs portable providers") + )] + let mut app = App::build::(FASTLY_PLATFORM)?; let metadata = A::stores().kv; if app .record_store_requirements() @@ -118,6 +124,8 @@ where KvError::Validation("record declaration uses an undeclared ID".to_owned()).into(), ); } + #[cfg(feature = "fastly")] + portable_bindings::install(&mut app, A::stores())?; Ok(app) } diff --git a/crates/edgezero-adapter-fastly/src/portable_bindings.rs b/crates/edgezero-adapter-fastly/src/portable_bindings.rs new file mode 100644 index 000000000..c55ee7e58 --- /dev/null +++ b/crates/edgezero-adapter-fastly/src/portable_bindings.rs @@ -0,0 +1,172 @@ +//! Per-KV-ID portable record providers selected by the runtime bindings document. +//! +//! The optional Config Store `edgezero_store_bindings`, entry `EDGEZERO__STORE_BINDINGS`, +//! holds the shared `version = 1` document. It is read once when the application is +//! built, with no network I/O and no secret reads. Each bound KV ID is then served by +//! its portable provider over the request's own `HttpClient`; every other declared ID +//! stays on Fastly KV. A document naming a provider this binary lacks fails assembly. +//! Nothing falls back to Fastly KV. + +#[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] +use std::collections::BTreeMap; +#[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] +use std::sync::Arc; + +#[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] +use edgezero_adapter::store_bindings::KvBinding; +use edgezero_adapter::store_bindings::{ + PORTABLE_BINDINGS_ENTRY, PORTABLE_BINDINGS_STORE, PortableDeclarations, + PortableRecordProviders, StoreBindingsDocument, +}; +use edgezero_core::app::{App, StoresMetadata}; +use edgezero_core::error::EdgeError; +use edgezero_core::key_value_store::{KvError, KvHandle}; +use edgezero_core::outbound::HttpClient; +#[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] +use edgezero_core::secret_store::SecretHandle; +#[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] +use edgezero_core::store_registry::BoundSecretStore; +#[cfg(feature = "aws-dynamodb-records")] +use edgezero_store_aws::portable_dynamodb::PreparedDynamoDbRecords; +#[cfg(feature = "celld-records")] +use edgezero_store_celld::portable::PreparedCelldRecords; + +use crate::config_store::portable_bindings_document; +#[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] +use crate::secret_store::FastlySecretStore; + +/// The Fastly Config Store entry value cap: 8,000 Unicode scalars of up to 4 bytes. +const MAX_DOCUMENT_BYTES: usize = 32_000; + +/// Record providers compiled into this binary. +const COMPILED: PortableRecordProviders = PortableRecordProviders { + celld: cfg!(feature = "celld-records"), + dynamodb: cfg!(feature = "aws-dynamodb-records"), +}; + +/// One bound KV ID's prepared provider. Settings and pins only; no request state. +#[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] +enum Prepared { + #[cfg(feature = "celld-records")] + Celld(PreparedCelldRecords), + #[cfg(feature = "aws-dynamodb-records")] + DynamoDb(PreparedDynamoDbRecords), +} + +/// Prepared providers for every bound KV ID, retained on the application. +#[derive(Clone)] +pub(crate) struct PortableProviders { + #[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] + by_id: Arc>, +} + +impl PortableProviders { + /// A request-bound store for `id` over the request's effective client, if bound. + #[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] + pub(crate) fn bind(&self, id: &str, client: &HttpClient) -> Option { + Some(match self.by_id.get(id)? { + #[cfg(feature = "celld-records")] + Prepared::Celld(provider) => KvHandle::new(Arc::new(provider.bind(client.clone()))), + #[cfg(feature = "aws-dynamodb-records")] + Prepared::DynamoDb(provider) => KvHandle::new(Arc::new(provider.bind(client.clone()))), + }) + } + + /// Without portable providers no ID is ever bound. + #[cfg(not(any(feature = "aws-dynamodb-records", feature = "celld-records")))] + #[expect( + clippy::unused_self, + reason = "keep one binding call site whether or not providers are compiled" + )] + pub(crate) const fn bind(&self, _id: &str, _client: &HttpClient) -> Option { + None + } +} + +/// Reads and validates the bindings document and installs the prepared providers. +/// +/// A missing store or entry means every declared KV ID stays on Fastly KV. +/// +/// # Errors +/// Returns a typed validation error for an unreadable, malformed or unsupported +/// document, an undeclared or unlayouted ID, or a provider this binary lacks. +pub(crate) fn install(app: &mut App, stores: StoresMetadata) -> Result<(), EdgeError> { + let Some(text) = portable_bindings_document(PORTABLE_BINDINGS_STORE, PORTABLE_BINDINGS_ENTRY) + .map_err(|_error| failure("store bindings unavailable"))? + else { + return Ok(()); + }; + let document = StoreBindingsDocument::parse(&text, MAX_DOCUMENT_BYTES) + .map_err(|category| failure(&category.to_string()))?; + document + .validate_portable( + &PortableDeclarations { + kv: stores.kv.map_or(&[][..], |meta| meta.ids), + secrets: stores.secrets.map_or(&[][..], |meta| meta.ids), + }, + COMPILED, + ) + .map_err(|category| failure(&category.to_string()))?; + #[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] + { + let providers = prepare(app, &document)?; + if !providers.by_id.is_empty() { + app.insert_state(providers); + } + } + // Validation rejects every KV binding when no portable provider is compiled. + #[cfg(not(any(feature = "aws-dynamodb-records", feature = "celld-records")))] + let _: (&mut App, StoreBindingsDocument) = (app, document); + Ok(()) +} + +#[cfg(any(feature = "aws-dynamodb-records", feature = "celld-records"))] +fn prepare(app: &App, document: &StoreBindingsDocument) -> Result { + let secrets = |logical: &str| { + BoundSecretStore::new( + SecretHandle::new(Arc::new(FastlySecretStore)), + logical.to_owned(), + ) + }; + let mut by_id = BTreeMap::new(); + for (id, binding) in &document.kv { + let layout = app + .record_store_requirements() + .get(id) + .ok_or_else(|| failure("record binding requires an application layout"))?; + let prepared = match binding { + #[cfg(feature = "aws-dynamodb-records")] + KvBinding::DynamoDbRecords(settings) => { + let logical = settings + .credentials + .as_ref() + .map(|reference| reference.secrets.as_str()) + .ok_or_else(|| failure("missing credentials reference"))?; + Prepared::DynamoDb( + PreparedDynamoDbRecords::new(id, settings, layout, secrets(logical)) + .map_err(|category| failure(&category.to_string()))?, + ) + } + #[cfg(feature = "celld-records")] + KvBinding::CelldRecords(settings) => { + let logical = settings + .token_secret() + .ok_or_else(|| failure("missing token reference"))?; + Prepared::Celld( + PreparedCelldRecords::new(id, settings, layout, secrets(logical)) + .map_err(|category| failure(&category.to_string()))?, + ) + } + // Portable validation already rejected native-only and uncompiled providers. + _ => return Err(failure("provider unsupported on this target")), + }; + by_id.insert(id.clone(), prepared); + } + Ok(PortableProviders { + by_id: Arc::new(by_id), + }) +} + +fn failure(category: &str) -> EdgeError { + KvError::Validation(format!("store bindings: {category}")).into() +} diff --git a/crates/edgezero-adapter-fastly/src/request.rs b/crates/edgezero-adapter-fastly/src/request.rs index cfa1d9f6d..22379c1fc 100644 --- a/crates/edgezero-adapter-fastly/src/request.rs +++ b/crates/edgezero-adapter-fastly/src/request.rs @@ -53,6 +53,7 @@ use crate::key_value_store::FastlyKvStore; use crate::lifecycle::with_callback; use crate::outbound::drive_callback; use crate::outbound::{FastlyOutboundClient, native_time}; +use crate::portable_bindings::PortableProviders; use crate::response::{parse_uri, send_egress_response}; use crate::secret_store::FastlySecretStore; @@ -91,6 +92,8 @@ impl RecentStringSet { struct Stores { config_registry: Option, config_store: Option, + /// Canonical KV metadata, bound once the request's effective `HttpClient` exists. + deferred_kv: Option, kv: Option, kv_registry: Option, secret_registry: Option, @@ -487,7 +490,7 @@ where fn dispatch_with_handles( app: &App, mut req: FastlyRequest, - stores: Stores, + mut stores: Stores, request_start: MonotonicInstant, prepare: Prepare, ) -> Result @@ -508,6 +511,22 @@ where ) })?; head_request.extensions_mut().extend(scratch); + if let Some(metadata) = stores.deferred_kv.take() { + // Portable providers use the same client as `ctx.http_client()`, including one a + // preparation hook supplied. Conversion always inserts one; the fallback keeps a + // bound ID on its portable provider rather than silently on Fastly KV. + let client = head_request + .extensions() + .get::() + .cloned() + .unwrap_or_else(|| outbound_client(app.monotonic_clock())); + stores.kv_registry = build_kv_registry_with_records( + Some(metadata), + app.record_store_requirements(), + app.state::() + .map(|providers| (providers, &client)), + ); + } let outcome = dispatch_ingress_reader( app, head_request, @@ -713,8 +732,6 @@ where with_callback(|| { init_fastly_abi(); let request_start = app.monotonic_now(); - let kv_registry = - build_kv_registry_with_records(stores.kv, app.record_store_requirements()); let config_registry = build_config_registry(stores.config); let secret_registry = build_secret_registry(stores.secrets); let outcome = dispatch_with_handles( @@ -722,7 +739,7 @@ where req, Stores { config_registry, - kv_registry, + deferred_kv: stores.kv, secret_registry, ..Default::default() }, @@ -799,23 +816,31 @@ fn synthesise_store_registries( #[cfg(test)] fn build_kv_registry(kv_meta: Option) -> Option { - build_kv_registry_with_records(kv_meta, &edgezero_core::RecordStoreRequirements::new()) + build_kv_registry_with_records( + kv_meta, + &edgezero_core::RecordStoreRequirements::new(), + None, + ) } +/// Bound IDs use their portable provider over `portable`'s client; every other +/// declared ID stays on Fastly KV. fn build_kv_registry_with_records( kv_meta: Option, requirements: &edgezero_core::RecordStoreRequirements, + portable: Option<(&PortableProviders, &HttpClient)>, ) -> Option { let meta = kv_meta?; let mut by_id: BTreeMap = BTreeMap::new(); for id in meta.ids { - by_id.insert( - (*id).to_owned(), + let bound = portable.and_then(|(providers, client)| providers.bind(id, client)); + let handle = bound.unwrap_or_else(|| { KvHandle::new(Arc::new(match requirements.get(*id) { Some(layout) => FastlyKvStore::declared_records(id, layout.clone()), None => FastlyKvStore::declared(id), - })), - ); + })) + }); + by_id.insert((*id).to_owned(), handle); } let default_id = meta.default.to_owned(); StoreRegistry::from_parts(by_id, default_id) @@ -1340,6 +1365,7 @@ mod synthesis_tests { ids: &["record_binding_not_opened", "ordinary_binding_not_opened"], }), &requirements, + None, ) .unwrap(); registry diff --git a/crates/edgezero-adapter-fastly/src/templates/Cargo.toml.hbs b/crates/edgezero-adapter-fastly/src/templates/Cargo.toml.hbs index d442b4e2d..8c5a5472c 100644 --- a/crates/edgezero-adapter-fastly/src/templates/Cargo.toml.hbs +++ b/crates/edgezero-adapter-fastly/src/templates/Cargo.toml.hbs @@ -17,6 +17,9 @@ path = "src/main.rs" [features] default = [] fastly = ["edgezero-adapter-fastly/fastly"] +# Portable record providers, selected per KV ID by the runtime bindings document. +aws-dynamodb-records = ["edgezero-adapter-fastly/aws-dynamodb-records"] +celld-records = ["edgezero-adapter-fastly/celld-records"] [dependencies] {{proj_core}} = { path = "../{{proj_core}}" } diff --git a/crates/edgezero-adapter-fastly/src/templates/fastly.toml.hbs b/crates/edgezero-adapter-fastly/src/templates/fastly.toml.hbs index e3ccb4414..d58d8a17a 100644 --- a/crates/edgezero-adapter-fastly/src/templates/fastly.toml.hbs +++ b/crates/edgezero-adapter-fastly/src/templates/fastly.toml.hbs @@ -8,5 +8,5 @@ service_id = "" [local_server] [scripts] - build = "cargo build --profile release --target wasm32-wasip1" + build = "cargo build --profile release --target wasm32-wasip1 ${EDGEZERO_BUILD_FEATURES:+--features \"$EDGEZERO_BUILD_FEATURES\"}" diff --git a/crates/edgezero-adapter/Cargo.toml b/crates/edgezero-adapter/Cargo.toml index c1dd41ffe..1f2d85fd5 100644 --- a/crates/edgezero-adapter/Cargo.toml +++ b/crates/edgezero-adapter/Cargo.toml @@ -13,9 +13,20 @@ workspace = true [features] default = [] cli = ["dep:base16ct", "dep:serde", "dep:serde_json", "dep:sha2", "dep:toml", "dep:walkdir"] +# The shared `version = 1` store bindings document. Settings only, every target. +store-bindings = [ + "dep:edgezero-store-aws", + "dep:edgezero-store-celld", + "dep:serde", + "dep:thiserror", + "dep:toml", +] [dependencies] edgezero-core = { workspace = true } +edgezero-store-aws = { workspace = true, optional = true } +edgezero-store-celld = { workspace = true, optional = true } +thiserror = { workspace = true, optional = true } toml = { workspace = true, optional = true } serde = { workspace = true, optional = true } serde_json = { workspace = true, optional = true } diff --git a/crates/edgezero-adapter/src/lib.rs b/crates/edgezero-adapter/src/lib.rs index 441f85160..971f39b7f 100644 --- a/crates/edgezero-adapter/src/lib.rs +++ b/crates/edgezero-adapter/src/lib.rs @@ -7,3 +7,6 @@ pub mod cli_support; #[cfg(feature = "cli")] pub mod release; + +#[cfg(feature = "store-bindings")] +pub mod store_bindings; diff --git a/crates/edgezero-adapter/src/store_bindings.rs b/crates/edgezero-adapter/src/store_bindings.rs new file mode 100644 index 000000000..1bb910cde --- /dev/null +++ b/crates/edgezero-adapter/src/store_bindings.rs @@ -0,0 +1,327 @@ +//! The strict `version = 1` store bindings document, shared by every adapter. +//! +//! This module only parses and validates settings. It performs no I/O, reads no +//! secret and constructs no provider. Axum reads the document from the file named by +//! `EDGEZERO__STORE_BINDINGS_FILE`; Fastly reads it from the Config Store +//! `edgezero_store_bindings`, entry `EDGEZERO__STORE_BINDINGS`. + +use std::collections::BTreeMap; +use std::fmt; + +use edgezero_store_aws::settings::{ + AppConfigAgentSettings, AwsPreparationLimits, DynamoDbKvLimits, DynamoDbKvSettings, + DynamoDbRecordsSettings, SecretsManagerSettings, +}; +use edgezero_store_celld::settings::{ + CelldKvSettings, CelldPreparationLimits, CelldRecordsSettings, +}; +use serde::Deserialize; + +/// Config Store name that holds a portable target's bindings document. +pub const PORTABLE_BINDINGS_STORE: &str = "edgezero_store_bindings"; +/// Config Store entry that holds a portable target's bindings document. +pub const PORTABLE_BINDINGS_ENTRY: &str = "EDGEZERO__STORE_BINDINGS"; + +/// Closed document failures. Never carries document text or settings. +#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)] +pub enum StoreBindingsError { + #[error("invalid store bindings")] + Invalid, + #[error("malformed store bindings")] + Malformed, + #[error("portable binding has no credentials reference")] + MissingCredentials, + #[error("portable binding has no pinned identity")] + MissingPin, + #[error("provider not compiled")] + NotCompiled, + #[error("store bindings size limit")] + SizeLimit, + #[error("undeclared binding")] + Undeclared, + #[error("provider unsupported on this target")] + Unsupported, +} + +/// Strict KV provider dispatch. The physical namespace is independent of the declared ID. +#[derive(Clone, Debug, Deserialize)] +#[serde(tag = "provider", deny_unknown_fields)] +pub enum KvBinding { + #[serde(rename = "celld-kv")] + Celld(CelldKvSettings), + #[serde(rename = "celld-records")] + CelldRecords(CelldRecordsSettings), + #[serde(rename = "aws-dynamodb")] + DynamoDb(DynamoDbKvSettings), + #[serde(rename = "aws-dynamodb-records")] + DynamoDbRecords(DynamoDbRecordsSettings), +} + +/// Strict configuration dispatch. Provider-specific fields are validated by AWS settings. +#[derive(Clone, Debug, Deserialize)] +#[serde(tag = "provider", deny_unknown_fields)] +pub enum ConfigBinding { + #[serde(rename = "aws-appconfig-agent")] + AppConfigAgent(AppConfigAgentSettings), +} + +/// Strict secret dispatch. No arbitrary remote names or per-request discovery. +#[derive(Clone, Debug, Deserialize)] +#[serde(tag = "provider", deny_unknown_fields)] +pub enum SecretBinding { + #[serde(rename = "aws-secrets-manager")] + SecretsManager(SecretsManagerSettings), +} + +/// Document-level native preparation limits. +#[derive(Clone, Debug, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct BindingLimits { + pub aws: Option, + pub celld: Option, +} + +/// One parsed `version = 1` document. Logical IDs and lookup keys are case-sensitive. +#[derive(Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct StoreBindingsDocument { + #[serde(default)] + pub config: BTreeMap, + #[serde(default)] + pub kv: BTreeMap, + pub limits: Option, + #[serde(default)] + pub secrets: BTreeMap, + pub version: u32, +} + +impl fmt::Debug for StoreBindingsDocument { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("StoreBindingsDocument") + .finish_non_exhaustive() + } +} + +/// Portable record providers compiled into a target binary. +#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] +pub struct PortableRecordProviders { + pub celld: bool, + pub dynamodb: bool, +} + +/// Declared logical IDs a portable document may reference. +#[derive(Clone, Copy, Debug)] +pub struct PortableDeclarations<'ids> { + pub kv: &'ids [&'ids str], + pub secrets: &'ids [&'ids str], +} + +impl StoreBindingsDocument { + /// Parses strict TOML under a trusted byte cap, before any validation. + /// + /// # Errors + /// Returns [`StoreBindingsError::SizeLimit`] above `max_bytes` and + /// [`StoreBindingsError::Malformed`] for any TOML or schema error. + #[inline] + pub fn parse(input: &str, max_bytes: usize) -> Result { + if input.len() > max_bytes { + return Err(StoreBindingsError::SizeLimit); + } + toml::from_str(input).map_err(|_error| StoreBindingsError::Malformed) + } + + /// Offline checks for a portable target such as Fastly. No secret reads and no I/O. + /// + /// Only `aws-dynamodb-records` and `celld-records` KV bindings are accepted. Each needs + /// its pinned identity and a declared logical secrets reference. KV IDs must be declared + /// and match `[a-z0-9_]`. Native-only sections and providers fail; nothing falls back. + /// + /// # Errors + /// Returns the first closed category that applies. + #[inline] + pub fn validate_portable( + &self, + declarations: &PortableDeclarations<'_>, + compiled: PortableRecordProviders, + ) -> Result<(), StoreBindingsError> { + if self.version != 1 { + return Err(StoreBindingsError::Invalid); + } + if !self.config.is_empty() || !self.secrets.is_empty() || self.limits.is_some() { + return Err(StoreBindingsError::Unsupported); + } + for (id, binding) in &self.kv { + if !declarations.kv.contains(&id.as_str()) { + return Err(StoreBindingsError::Undeclared); + } + if !valid_portable_id(id) { + return Err(StoreBindingsError::Invalid); + } + let secrets = match binding { + KvBinding::DynamoDb(_) | KvBinding::Celld(_) => { + return Err(StoreBindingsError::Unsupported); + } + KvBinding::DynamoDbRecords(settings) => { + if !compiled.dynamodb { + return Err(StoreBindingsError::NotCompiled); + } + settings + .validate(DynamoDbKvLimits::PORTABLE) + .and_then(|()| settings.portable_endpoint()) + .map_err(|_category| StoreBindingsError::Invalid)?; + if settings.pinned.is_none() { + return Err(StoreBindingsError::MissingPin); + } + settings + .credentials + .as_ref() + .map(|reference| reference.secrets.as_str()) + } + KvBinding::CelldRecords(settings) => { + if !compiled.celld { + return Err(StoreBindingsError::NotCompiled); + } + settings + .portable_endpoint() + .map_err(|_category| StoreBindingsError::Invalid)?; + if settings.pinned.is_none() { + return Err(StoreBindingsError::MissingPin); + } + settings.token_secret() + } + }; + let secrets_id = secrets.ok_or(StoreBindingsError::MissingCredentials)?; + if !declarations.secrets.contains(&secrets_id) { + return Err(StoreBindingsError::Undeclared); + } + } + Ok(()) + } +} + +/// Lowercase ASCII, digits and underscore, so uppercased secret key names cannot collide. +#[inline] +#[must_use] +pub fn valid_portable_id(id: &str) -> bool { + !id.is_empty() + && id + .bytes() + .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_') +} + +#[cfg(test)] +mod tests { + use super::*; + + const DECLARED: PortableDeclarations<'static> = PortableDeclarations { + kv: &["identity", "sessions", "Upper"], + secrets: &["stores"], + }; + const BOTH: PortableRecordProviders = PortableRecordProviders { + celld: true, + dynamodb: true, + }; + + const DOCUMENT: &str = r#" +version = 1 + +[kv.identity] +provider = "aws-dynamodb-records" +region = "us-east-1" +table = "ts-identity" +namespace = "ts-prod/identity" +pinned = { table_arn = "arn:aws:dynamodb:us-east-1:111122223333:table/ts-identity", table_id = "id" } +credentials = { secrets = "stores" } + +[kv.sessions] +provider = "celld-records" +endpoint = "https://celld.example.net" +store = "sessions" +pinned = { instance = "AAAAAAAAAAAAAAAAAAAAAA" } +access = { mode = "authenticated", token_secret = { secrets = "stores" } } +"#; + + fn document(input: &str) -> StoreBindingsDocument { + StoreBindingsDocument::parse(input, 8_000).unwrap() + } + + #[test] + fn the_specified_document_validates_for_a_portable_target() { + document(DOCUMENT) + .validate_portable(&DECLARED, BOTH) + .unwrap(); + } + + #[test] + fn parsing_is_strict_and_capped() { + assert_eq!( + StoreBindingsDocument::parse(DOCUMENT, 10).unwrap_err(), + StoreBindingsError::SizeLimit + ); + for malformed in [ + "version = 1\nunknown = true", + "version = 1\n[kv.x]\nprovider = \"aws-dynamodb-records\"\nregion = \"us-east-1\"\ntable = \"ttt\"\nnamespace = \"n\"\nextra = 1", + "version = 1\n[kv.x]\nprovider = \"other\"", + ] { + assert_eq!( + StoreBindingsDocument::parse(malformed, 8_000).unwrap_err(), + StoreBindingsError::Malformed + ); + } + } + + #[test] + fn portable_validation_fails_closed_without_fallback() { + let cases = [ + (DOCUMENT.replace("version = 1", "version = 2"), StoreBindingsError::Invalid), + (format!("{DOCUMENT}\n[limits.celld]\noperation_timeout_ms = 10"), StoreBindingsError::Unsupported), + (DOCUMENT.replace("[kv.sessions]", "[kv.undeclared]"), StoreBindingsError::Undeclared), + (DOCUMENT.replace("[kv.sessions]", "[kv.Upper]"), StoreBindingsError::Invalid), + (DOCUMENT.replace("pinned = { instance = \"AAAAAAAAAAAAAAAAAAAAAA\" }\n", ""), StoreBindingsError::MissingPin), + (DOCUMENT.replace("credentials = { secrets = \"stores\" }\n", ""), StoreBindingsError::MissingCredentials), + (DOCUMENT.replace("credentials = { secrets = \"stores\" }", "credentials = { secrets = \"other\" }"), StoreBindingsError::Undeclared), + (DOCUMENT.replace("https://celld.example.net", "http://celld.example.net"), StoreBindingsError::Invalid), + ( + DOCUMENT.replace( + "access = { mode = \"authenticated\", token_secret = { secrets = \"stores\" } }", + "access = { mode = \"trusted-network\" }", + ), + StoreBindingsError::Invalid, + ), + ( + DOCUMENT.replace("token_secret = { secrets = \"stores\" }", "token_env = \"TOKEN\""), + StoreBindingsError::Invalid, + ), + ( + DOCUMENT.replace("provider = \"celld-records\"", "provider = \"celld-kv\"") + .replace("pinned = { instance = \"AAAAAAAAAAAAAAAAAAAAAA\" }\n", "") + .replace("token_secret = { secrets = \"stores\" }", "token_env = \"TOKEN\""), + StoreBindingsError::Unsupported, + ), + ]; + for (input, expected) in cases { + assert_eq!( + document(&input).validate_portable(&DECLARED, BOTH), + Err(expected), + "{input}" + ); + } + let dynamodb_only = PortableRecordProviders { + celld: false, + dynamodb: true, + }; + assert_eq!( + document(DOCUMENT).validate_portable(&DECLARED, dynamodb_only), + Err(StoreBindingsError::NotCompiled) + ); + } + + #[test] + fn portable_ids_cannot_collide_after_uppercasing() { + assert!(valid_portable_id("identity_2")); + for id in ["", "Identity", "id-entity", "id.entity", "id\u{e9}"] { + assert!(!valid_portable_id(id)); + } + } +} diff --git a/crates/edgezero-cli/Cargo.toml b/crates/edgezero-cli/Cargo.toml index f74c6c851..74212a512 100644 --- a/crates/edgezero-cli/Cargo.toml +++ b/crates/edgezero-cli/Cargo.toml @@ -22,6 +22,8 @@ required-features = ["nested-app-config-check"] [dependencies] edgezero-core = { workspace = true } edgezero-adapter = { path = "../edgezero-adapter" } +edgezero-store-aws = { workspace = true, optional = true } +edgezero-store-celld = { workspace = true, optional = true } edgezero-adapter-axum = { workspace = true, features = ["cli", "native-bindings"], optional = true } edgezero-adapter-cloudflare = { workspace = true, features = ["cli"], optional = true } edgezero-adapter-fastly = { workspace = true, features = ["cli"], optional = true } @@ -38,6 +40,9 @@ simple_logger = { workspace = true } serde_json = { workspace = true} thiserror = { workspace = true } toml = { workspace = true } +toml_edit = { workspace = true, optional = true } +tokio = { workspace = true, optional = true } +tempfile = { workspace = true, optional = true } validator = { workspace = true } proc-macro2 = { workspace = true, features = ["span-locations"], optional = true } syn = { workspace = true, optional = true } @@ -55,12 +60,14 @@ url = { workspace = true } [features] default = [ + "bindings-pin", "cli", "edgezero-adapter-axum", "edgezero-adapter-fastly", "edgezero-adapter-cloudflare", "edgezero-adapter-spin", ] -cli = ["dep:clap", "dep:handlebars", "edgezero-adapter/cli"] +bindings-pin = ["cli", "dep:edgezero-store-aws", "edgezero-store-aws/dynamodb-records", "dep:edgezero-store-celld", "edgezero-store-celld/records", "dep:tokio", "dep:toml_edit", "dep:tempfile"] +cli = ["dep:clap", "dep:handlebars", "edgezero-adapter/cli", "edgezero-adapter/store-bindings"] demo-example = ["dep:app-demo-core", "edgezero-adapter-axum", "edgezero-adapter-axum/axum"] nested-app-config-check = ["dep:proc-macro2", "dep:syn", "dep:walkdir"] diff --git a/crates/edgezero-cli/src/adapter.rs b/crates/edgezero-cli/src/adapter.rs index d9c0a029a..bc2d42ead 100644 --- a/crates/edgezero-cli/src/adapter.rs +++ b/crates/edgezero-cli/src/adapter.rs @@ -17,6 +17,9 @@ use std::path::Path; use std::process::{Command, Stdio}; use std::thread; +/// Comma-separated `[adapters..build] features` for provider-CLI builds. +const BUILD_FEATURES_VAR: &str = "EDGEZERO_BUILD_FEATURES"; + include!(concat!(env!("OUT_DIR"), "/linked_adapters.rs")); #[derive(Debug, Clone, Copy)] @@ -602,6 +605,13 @@ fn build_shell_command( None => shell_command(command, adapter_args, cwd), }; + // Axum receives manifest build features as Cargo arguments above. Adapters whose + // provider CLI runs the Cargo build, such as Fastly's `[scripts] build`, read them + // from this variable; the generated build scripts append `--features`. + if !adapter_name.eq_ignore_ascii_case("axum") && !manifest_features.is_empty() { + cmd.env(BUILD_FEATURES_VAR, manifest_features.join(",")); + } + // Precedence (high to low) for `EDGEZERO__ADAPTER__HOST/PORT` on the // subprocess: // 1. Parent env — propagated through std::process::Command's default @@ -854,8 +864,8 @@ mod tests { #[cfg(feature = "edgezero-adapter-axum")] use super::native_axum_cargo_command; use super::{ - AdapterDeployContext, ResolvedEnvironment, apply_environment, deploy, ensure_capabilities, - execute_runtime, + AdapterDeployContext, BUILD_FEATURES_VAR, ResolvedEnvironment, apply_environment, + build_shell_command, deploy, ensure_capabilities, execute_runtime, }; use crate::adapter::Action; use crate::manifest_source::resolve_runtime_from; @@ -870,7 +880,7 @@ mod tests { use std::env; use std::ffi::{OsStr, OsString}; use std::fs; - use std::path::PathBuf; + use std::path::{Path, PathBuf}; use std::process::Command; use std::sync::Mutex; use tempfile::tempdir; @@ -1110,6 +1120,38 @@ mod tests { assert!(has_var); } + #[test] + fn provider_cli_builds_receive_manifest_features_and_axum_does_not() { + let features = [ + "aws-dynamodb-records".to_owned(), + "celld-records".to_owned(), + ]; + let env_of = |adapter: &str, selected: &[String]| { + build_shell_command( + "true", + Path::new("."), + adapter, + Action::Build, + None, + (None, None), + &[], + selected, + ) + .expect("command") + .get_envs() + .find(|(key, _)| key.to_str() == Some(BUILD_FEATURES_VAR)) + .and_then(|(_, value)| value) + .and_then(OsStr::to_str) + .map(str::to_owned) + }; + assert_eq!( + env_of("fastly", &features).as_deref(), + Some("aws-dynamodb-records,celld-records") + ); + assert_eq!(env_of("fastly", &[]), None); + assert_eq!(env_of("axum", &features), None); + } + #[test] fn apply_environment_defers_to_parent_env_when_already_set() { // Manifest `[environment.variables].value` is a DEFAULT. diff --git a/crates/edgezero-cli/src/args.rs b/crates/edgezero-cli/src/args.rs index 0afcc344e..f4689b255 100644 --- a/crates/edgezero-cli/src/args.rs +++ b/crates/edgezero-cli/src/args.rs @@ -64,11 +64,13 @@ pub enum Command { /// Subcommands under `edgezero config …`. /// /// In the bundled `edgezero` binary, `push` and `diff` are stubs that -/// print a pointer to the downstream typed CLI and exit 2. `validate` -/// is the only subcommand that runs in-band here because it does not -/// require a typed app-config struct. +/// print a pointer to the downstream typed CLI and exit 2. `validate`, +/// `gc` and `bindings` run here without a typed app-config struct. #[derive(Subcommand, Debug)] pub enum ConfigCmd { + /// Prepare and pin the identities in a portable store bindings file. + #[command(subcommand)] + Bindings(BindingsCmd), /// Diff the typed `.toml` against the live config store. /// (Bundled `edgezero` stub — see after-help for the typed CLI.) #[command(after_help = STUB_POINTER_AFTER_HELP)] @@ -103,6 +105,25 @@ pub enum ConfigCmd { Validate(ConfigValidateArgs), } +/// Untyped store bindings commands, shared by bundled and generated CLIs. +#[derive(Subcommand, Debug)] +pub enum BindingsCmd { + /// Preflight all selected providers and update only their pinned identities. + Pin(BindingsPinArgs), +} + +/// Arguments for `config bindings pin`. No app-config type or upload is involved. +#[derive(clap::Args, Debug)] +#[non_exhaustive] +pub struct BindingsPinArgs { + /// Target adapter. Only `fastly` is currently supported. + #[arg(long, value_parser = ["fastly"])] + pub adapter: String, + /// Store bindings TOML file to update after every preflight succeeds. + #[arg(long)] + pub store_bindings: PathBuf, +} + /// Hidden catch-all argument sink for the bundled stub variants of /// `config push` and `config diff`. Absorbs any flags the user types /// so clap does not error before we can print the pointer text. @@ -615,7 +636,7 @@ impl Default for ConfigPushArgs { reason = "each bool is an independent Clap control; target toggles mirror Cargo feature flags" )] pub struct ConfigValidateArgs { - /// Select bindings-only native validation; must be `axum`. + /// Select bindings-only validation for `axum` or `fastly`. #[arg(long)] pub adapter: Option, /// Path to the typed app-config file (default: `.toml` @@ -630,7 +651,7 @@ pub struct ConfigValidateArgs { /// sees the values the runtime would. #[arg(long)] pub no_env: bool, - /// Explicit absolute native bindings file for bindings-only validation. + /// Bindings file for bindings-only validation. Axum requires an absolute path. #[arg(long)] pub store_bindings: Option, /// Strict mode: additionally check capability-aware completeness @@ -720,6 +741,7 @@ pub fn parse_duration_secs(raw: &str) -> Result { #[cfg(test)] mod tests { use super::*; + use clap::error::ErrorKind; /// Thin wrapper so `ConfigDiffArgs` (a `clap::Args`) can be /// tested via real clap parsing. `ConfigDiffArgs` is `#[non_exhaustive]` @@ -731,6 +753,42 @@ mod tests { args: ConfigDiffArgs, } + #[test] + fn bindings_pin_clap_surface_and_help_are_untyped_and_explicit() { + let parsed = Args::try_parse_from([ + "edgezero", + "config", + "bindings", + "pin", + "--adapter", + "fastly", + "--store-bindings", + "bindings.toml", + ]) + .unwrap(); + let Command::Config(ConfigCmd::Bindings(BindingsCmd::Pin(args))) = parsed.cmd else { + panic!("expected bindings pin"); + }; + assert_eq!(args.adapter, "fastly"); + assert_eq!(args.store_bindings, PathBuf::from("bindings.toml")); + for flags in [ + vec!["--adapter", "axum", "--store-bindings", "bindings.toml"], + vec!["--adapter", "fastly"], + vec!["--store-bindings", "bindings.toml"], + ] { + let mut invocation = vec!["edgezero", "config", "bindings", "pin"]; + invocation.extend(flags); + let _error = Args::try_parse_from(invocation).expect_err("invalid pin flags"); + } + let help = + Args::try_parse_from(["edgezero", "config", "bindings", "pin", "--help"]).unwrap_err(); + assert_eq!(help.kind(), ErrorKind::DisplayHelp); + let help_text = help.to_string(); + assert!(help_text.contains("Usage: edgezero config bindings pin --adapter --store-bindings ")); + assert!(help_text.contains("fastly")); + assert!(!help_text.contains(STUB_POINTER_AFTER_HELP)); + } + /// Parse `ConfigDiffArgs` from a CLI token slice via clap. fn parse_diff(tokens: &[&str]) -> ConfigDiffArgs { let mut full = vec!["bin"]; diff --git a/crates/edgezero-cli/src/bindings_pin.rs b/crates/edgezero-cli/src/bindings_pin.rs new file mode 100644 index 000000000..128239e95 --- /dev/null +++ b/crates/edgezero-cli/src/bindings_pin.rs @@ -0,0 +1,622 @@ +//! Untyped portable bindings preflight and capped file loading. + +#[cfg(feature = "bindings-pin")] +mod enabled { + use super::{check_portable_size, parse_portable_bindings, read_portable_bindings}; + use crate::args::BindingsPinArgs; + use edgezero_adapter::store_bindings::{KvBinding, StoreBindingsDocument, valid_portable_id}; + use edgezero_core::time::MonotonicClock; + use edgezero_store_aws::settings::{ + AwsPreparationLimits, DynamoDbKvLimits, DynamoDbPinnedIdentity, DynamoDbRecordsSettings, + }; + use edgezero_store_aws::{AwsPreparation, PreparationError as AwsPreparationError}; + use edgezero_store_celld::settings::{ + CelldAccessToken, CelldPinnedIdentity, CelldPreparationLimits, CelldRecordsSettings, + celld_token_key, + }; + use edgezero_store_celld::{CelldPreparation, PreparationError as CelldPreparationError}; + use std::collections::BTreeMap; + use std::env; + use std::fs; + use std::io::Write as _; + use std::path::Path; + use tokio::runtime::{Builder, Runtime}; + use toml_edit::{DocumentMut, InlineTable, Item, TableLike, value}; + + #[derive(Debug, thiserror::Error)] + enum PreflightFailed { + #[error(transparent)] + Aws(AwsPreparationError), + #[error(transparent)] + Celld(CelldPreparationError), + } + + trait Preflight { + fn celld( + &mut self, + settings: &CelldRecordsSettings, + token_env: &str, + token: &CelldAccessToken, + ) -> Result; + + fn dynamodb( + &mut self, + settings: &DynamoDbRecordsSettings, + ) -> Result; + } + + struct NativePreflight { + aws: AwsPreparation, + celld: CelldPreparation, + runtime: Runtime, + } + + impl NativePreflight { + fn new() -> Result { + let runtime = Builder::new_current_thread() + .enable_all() + .build() + .map_err(|_error| "failed to initialize pin preflight runtime".to_owned())?; + let clock = MonotonicClock::default(); + let aws = AwsPreparation::new(clock.clone(), AwsPreparationLimits::default()) + .map_err(|_error| "failed to initialize AWS preflight".to_owned())?; + let celld = CelldPreparation::new(clock, CelldPreparationLimits::default()) + .map_err(|_error| "failed to initialize celld preflight".to_owned())?; + Ok(Self { + aws, + celld, + runtime, + }) + } + } + + impl Preflight for NativePreflight { + fn celld( + &mut self, + settings: &CelldRecordsSettings, + token_env: &str, + token: &CelldAccessToken, + ) -> Result { + self.runtime + .block_on( + self.celld + .preflight_record_store(settings, token_env, token), + ) + .map_err(PreflightFailed::Celld) + } + + fn dynamodb( + &mut self, + settings: &DynamoDbRecordsSettings, + ) -> Result { + self.runtime + .block_on(self.aws.preflight_dynamodb_records(settings)) + .map(|identity| identity.pinned) + .map_err(PreflightFailed::Aws) + } + } + + pub(super) fn run(args: &BindingsPinArgs) -> Result<(), String> { + let ids = pin_file_with(&args.store_bindings, &mut NativePreflight::new()?, |key| { + env::var(key).ok() + })?; + for id in ids { + log::info!("[edgezero] pinned store binding {id}"); + } + Ok(()) + } + + fn validate_preflight_input(bindings: &StoreBindingsDocument) -> Result<(), String> { + if bindings.version != 1 + || !bindings.config.is_empty() + || !bindings.secrets.is_empty() + || bindings.limits.is_some() + { + return Err("bindings pin requires a portable version 1 KV document".to_owned()); + } + for (id, binding) in &bindings.kv { + if !valid_portable_id(id) { + return Err( + "portable binding IDs must contain only lowercase ASCII, digits and underscore" + .to_owned(), + ); + } + match binding { + KvBinding::DynamoDbRecords(settings) => { + settings + .validate(DynamoDbKvLimits::PORTABLE) + .and_then(|()| settings.portable_endpoint()) + .map_err(|_error| "invalid portable DynamoDB binding".to_owned())?; + if settings.credentials.is_none() { + return Err( + "portable DynamoDB binding requires a credentials reference".to_owned() + ); + } + } + KvBinding::CelldRecords(settings) => { + settings + .portable_endpoint() + .map_err(|_error| "invalid portable celld binding".to_owned())?; + } + KvBinding::DynamoDb(_) | KvBinding::Celld(_) => { + return Err("bindings pin supports only portable record providers".to_owned()); + } + } + } + Ok(()) + } + + fn pin_file_with( + path: &Path, + preflight: &mut impl Preflight, + mut env: impl FnMut(&str) -> Option, + ) -> Result, String> { + let input = read_portable_bindings(path)?; + let bindings = parse_portable_bindings(&input)?; + validate_preflight_input(&bindings)?; + let mut document = input + .parse::() + .map_err(|_error| "malformed store bindings".to_owned())?; + // Capture every token before the first network call, including when an + // earlier alphabetic binding would otherwise run an AWS preflight first. + let mut tokens = BTreeMap::new(); + for (id, binding) in &bindings.kv { + if matches!(binding, KvBinding::CelldRecords(_)) { + let key = celld_token_key(id); + let raw = env(&key) + .ok_or_else(|| format!("missing preflight token environment variable {key}"))?; + let token = CelldAccessToken::new(raw).map_err(|_error| { + format!("invalid preflight token environment variable {key}") + })?; + tokens.insert(id.as_str(), (key, token)); + } + } + let mut ids = Vec::new(); + for (id, binding) in &bindings.kv { + let pinned = document + .get_mut("kv") + .and_then(|kv| kv.get_mut(id)) + .and_then(Item::as_table_like_mut) + .ok_or_else(|| "invalid KV binding table".to_owned())? + .entry("pinned") + .or_insert_with(|| value(InlineTable::new())); + let pin_fields = pinned + .as_table_like_mut() + .ok_or_else(|| "invalid pinned identity table".to_owned())?; + let failed = |error: PreflightFailed| { + format!("preflight failed for store binding {id}: {error}") + }; + match binding { + KvBinding::DynamoDbRecords(settings) => { + let identity = preflight.dynamodb(settings).map_err(failed)?; + set_pin_field(pin_fields, "table_arn", identity.table_arn); + if let Some(table_id) = identity.table_id { + set_pin_field(pin_fields, "table_id", table_id); + } else { + pin_fields.remove("table_id"); + } + } + KvBinding::CelldRecords(settings) => { + let (key, token) = tokens + .get(id.as_str()) + .ok_or_else(|| "missing captured celld preflight token".to_owned())?; + let identity = preflight.celld(settings, key, token).map_err(failed)?; + set_pin_field(pin_fields, "instance", identity.instance); + } + KvBinding::DynamoDb(_) | KvBinding::Celld(_) => { + return Err("bindings pin supports only portable record providers".to_owned()); + } + } + ids.push(id.clone()); + } + let output = document.to_string(); + check_portable_size(&output)?; + let parent = path + .parent() + .filter(|parent| !parent.as_os_str().is_empty()) + .unwrap_or_else(|| Path::new(".")); + let mut temporary = tempfile::NamedTempFile::new_in(parent) + .map_err(|_error| "failed to stage pinned bindings".to_owned())?; + let permissions = fs::metadata(path) + .map_err(|_error| "failed to read bindings permissions".to_owned())? + .permissions(); + temporary + .as_file() + .set_permissions(permissions) + .map_err(|_error| "failed to preserve bindings permissions".to_owned())?; + temporary + .write_all(output.as_bytes()) + .map_err(|_error| "failed to stage pinned bindings".to_owned())?; + temporary + .persist(path) + .map_err(|_error| "failed to replace pinned bindings".to_owned())?; + Ok(ids) + } + + fn set_pin_field(table: &mut dyn TableLike, key: &str, content: String) { + let mut replacement = value(content); + if let Some(previous) = table.get(key).and_then(Item::as_value) + && let Some(next) = replacement.as_value_mut() + { + *next.decor_mut() = previous.decor().clone(); + } + table.insert(key, replacement); + } + + #[cfg(test)] + mod tests { + use super::*; + use crate::bindings_pin::MAX_BINDINGS_CHARS; + use edgezero_adapter::store_bindings::{PortableDeclarations, PortableRecordProviders}; + use std::path::PathBuf; + + const INPUT: &str = r#"# Deployment note stays at the top. +version = 1 # schema + +[kv.identity] # keep this +provider = "aws-dynamodb-records" +region = "us-east-1" +table = "identity-table" +namespace = "example/identity" +credentials = { secrets = "stores" } # runtime source, not AWS env +# Endpoint must remain absent. + +[kv.sessions] +provider = "celld-records" +endpoint = "https://unreachable.invalid" +store = "sessions" +access = { mode = "authenticated", token_secret = { secrets = "stores" } } # keep source +"#; + const TOKEN: &str = "a-preflight-secret-never-written-or-printed"; + + #[derive(Default)] + struct FakePreflight { + calls: Vec, + endpoint: Option, + fail_aws: bool, + fail_celld: bool, + table_id: Option, + } + + impl Preflight for FakePreflight { + fn celld( + &mut self, + _settings: &CelldRecordsSettings, + token_env: &str, + token: &CelldAccessToken, + ) -> Result { + if token_env != "KV__SESSIONS__CELLD_TOKEN" || token.expose() != TOKEN { + return Err(PreflightFailed::Celld(CelldPreparationError::Credentials)); + } + self.calls.push("celld".to_owned()); + if self.fail_celld { + return Err(PreflightFailed::Celld(CelldPreparationError::Forbidden)); + } + Ok(CelldPinnedIdentity { + instance: "AAAAAAAAAAAAAAAAAAAAAA".to_owned(), + }) + } + + fn dynamodb( + &mut self, + settings: &DynamoDbRecordsSettings, + ) -> Result { + if settings.endpoint != self.endpoint { + return Err(PreflightFailed::Aws(AwsPreparationError::InvalidEndpoint)); + } + self.calls.push("dynamodb".to_owned()); + if self.fail_aws { + return Err(PreflightFailed::Aws(AwsPreparationError::AccessDenied)); + } + Ok(DynamoDbPinnedIdentity { + table_arn: "arn:aws:dynamodb:us-east-1:111122223333:table/identity-table" + .to_owned(), + table_id: self.table_id.clone(), + }) + } + } + + fn pin_fixture( + input: &str, + preflight: &mut FakePreflight, + env: impl FnMut(&str) -> Option, + ) -> (tempfile::TempDir, PathBuf, Result, String>) { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("bindings.toml"); + fs::write(&path, input).unwrap(); + let result = pin_file_with(&path, preflight, env); + (directory, path, result) + } + + #[test] + fn bindings_pin_success_changes_only_pins_and_keeps_comments_and_sources() { + let mut preflight = FakePreflight::default(); + let (_directory, path, result) = pin_fixture(INPUT, &mut preflight, |key| { + assert_eq!(key, "KV__SESSIONS__CELLD_TOKEN"); + Some(TOKEN.to_owned()) + }); + let ids = result.unwrap(); + assert_eq!(ids, ["identity", "sessions"]); + assert_eq!(preflight.calls, ["dynamodb", "celld"]); + let output = fs::read_to_string(path).unwrap(); + let mut without_pins = output + .lines() + .filter(|line| !line.starts_with("pinned =")) + .collect::>() + .join("\n"); + without_pins.push('\n'); + assert_eq!(without_pins, INPUT); + assert!(!output.contains(TOKEN)); + assert!(!output.contains("table_id")); + assert!(!output.contains("KV__SESSIONS__CELLD_TOKEN")); + assert!(!ids.join(",").contains(TOKEN)); + let bindings = parse_portable_bindings(&output).unwrap(); + bindings + .validate_portable( + &PortableDeclarations { + kv: &["identity", "sessions"], + secrets: &["stores"], + }, + PortableRecordProviders { + celld: true, + dynamodb: true, + }, + ) + .unwrap(); + } + + #[test] + fn bindings_pin_late_failure_leaves_input_byte_for_byte_unchanged() { + let mut preflight = FakePreflight { + fail_celld: true, + ..FakePreflight::default() + }; + let (_directory, path, result) = + pin_fixture(INPUT, &mut preflight, |_key| Some(TOKEN.to_owned())); + assert_eq!(preflight.calls, ["dynamodb", "celld"]); + assert_eq!(fs::read_to_string(path).unwrap(), INPUT); + let error = result.unwrap_err(); + assert_eq!( + error, + "preflight failed for store binding sessions: forbidden" + ); + assert!(!error.contains(TOKEN)); + assert!(!error.contains("unreachable.invalid")); + } + + #[test] + fn bindings_pin_retains_the_closed_aws_failure_category() { + let mut preflight = FakePreflight { + fail_aws: true, + ..FakePreflight::default() + }; + let (_directory, path, result) = + pin_fixture(INPUT, &mut preflight, |_key| Some(TOKEN.to_owned())); + assert_eq!( + result.unwrap_err(), + "preflight failed for store binding identity: access denied" + ); + assert_eq!(preflight.calls, ["dynamodb"]); + assert_eq!(fs::read_to_string(path).unwrap(), INPUT); + } + + #[test] + fn bindings_pin_missing_or_invalid_token_fails_before_any_preflight() { + for token in [None, Some("invalid-secret".to_owned())] { + let mut preflight = FakePreflight::default(); + let (_directory, path, result) = + pin_fixture(INPUT, &mut preflight, |_key| token.clone()); + let error = result.unwrap_err(); + assert!(error.contains("KV__SESSIONS__CELLD_TOKEN")); + assert!(!error.contains("invalid-secret")); + assert!(preflight.calls.is_empty()); + assert_eq!(fs::read_to_string(path).unwrap(), INPUT); + } + } + + #[test] + fn bindings_pin_replaces_existing_pin_without_dropping_its_comment() { + let input = INPUT.replace( + "region =", + "pinned = { table_arn = 'old', table_id = 'old-id' } # preserve pin note\nregion =", + ); + let mut preflight = FakePreflight::default(); + let (_directory, path, result) = + pin_fixture(&input, &mut preflight, |_key| Some(TOKEN.to_owned())); + result.unwrap(); + let output = fs::read_to_string(path).unwrap(); + assert!(output.contains("# preserve pin note")); + assert!(!output.contains("old-id")); + assert!(!output.contains("table_id")); + assert!(output.contains("arn:aws:dynamodb:")); + } + + #[test] + fn bindings_pin_preserves_an_explicit_endpoint_and_exact_table_id() { + let endpoint = "http://127.0.0.1:18000"; + let input = INPUT.replace( + "region =", + &format!("endpoint = '{endpoint}' # custom endpoint\nregion ="), + ); + let mut preflight = FakePreflight { + endpoint: Some(endpoint.to_owned()), + table_id: Some("observed-table-id".to_owned()), + ..FakePreflight::default() + }; + let (_directory, path, result) = + pin_fixture(&input, &mut preflight, |_key| Some(TOKEN.to_owned())); + result.unwrap(); + let output = fs::read_to_string(path).unwrap(); + assert!(output.contains(&format!("endpoint = '{endpoint}' # custom endpoint"))); + let document = parse_portable_bindings(&output).unwrap(); + let KvBinding::DynamoDbRecords(settings) = document + .kv + .get("identity") + .expect("pinned DynamoDB binding") + else { + panic!("expected DynamoDB"); + }; + assert_eq!( + settings.pinned.as_ref().unwrap().table_id.as_deref(), + Some("observed-table-id") + ); + } + + #[test] + fn bindings_pin_preserves_table_form_pin_comments() { + let input = INPUT.replace( + "[kv.sessions]", + "[kv.identity.pinned] # table note\ntable_arn = 'old' # ARN note\n\n[kv.sessions]", + ); + let mut preflight = FakePreflight::default(); + let (_directory, path, result) = + pin_fixture(&input, &mut preflight, |_key| Some(TOKEN.to_owned())); + result.unwrap(); + let output = fs::read_to_string(path).unwrap(); + assert!(output.contains("[kv.identity.pinned] # table note")); + assert!(output.contains("# ARN note")); + assert!(output.contains("arn:aws:dynamodb:")); + } + + #[test] + fn bindings_pin_output_over_the_entry_limit_leaves_input_unchanged() { + let input = format!( + "{}#{}\n", + INPUT, + "x".repeat(MAX_BINDINGS_CHARS - INPUT.chars().count() - 2) + ); + let mut preflight = FakePreflight::default(); + let (_directory, path, result) = + pin_fixture(&input, &mut preflight, |_key| Some(TOKEN.to_owned())); + assert!(result.unwrap_err().contains("entry limit")); + assert_eq!(preflight.calls, ["dynamodb", "celld"]); + assert_eq!(fs::read_to_string(path).unwrap(), input); + } + + #[test] + fn bindings_pin_invalid_documents_never_preflight_or_change_the_file() { + for input in [ + INPUT.replace("version = 1", "version = 2"), + INPUT.replace("[kv.identity]", "[kv.Identity]"), + INPUT.replace("credentials = { secrets = \"stores\" }", ""), + INPUT.replace( + "mode = \"authenticated\", token_secret = { secrets = \"stores\" }", + "mode = \"trusted-network\"", + ), + INPUT.replace("aws-dynamodb-records", "aws-dynamodb"), + format!("{INPUT}\n[limits.aws]\npreparation_timeout_ms = 1"), + ] { + let mut preflight = FakePreflight::default(); + let (_directory, path, result) = + pin_fixture(&input, &mut preflight, |_key| panic!("no token read")); + let _error = result.expect_err("invalid document must fail"); + assert!(preflight.calls.is_empty()); + assert_eq!(fs::read_to_string(path).unwrap(), input); + } + } + } +} + +use crate::args::BindingsPinArgs; +use edgezero_adapter::store_bindings::StoreBindingsDocument; +use std::fs::File; +use std::io::Read as _; +use std::path::Path; + +// Fastly Config Store entries hold at most 8,000 characters. Bound the read +// before decoding UTF-8, allowing four bytes per character. +const MAX_BINDINGS_BYTES: u16 = 32_000; +const MAX_BINDINGS_CHARS: usize = 8_000; + +/// Preflight every selected binding and write only its pinned identity. +/// +/// # Errors +/// Returns a redacted error on unsupported targets, invalid files, missing +/// credentials, failed preflight or failed atomic replacement. Without the +/// `bindings-pin` feature this command reports that support is not compiled. +#[inline] +pub fn run_config_bindings_pin(args: &BindingsPinArgs) -> Result<(), String> { + if args.adapter != "fastly" { + return Err("bindings pin supports only `--adapter fastly`".to_owned()); + } + #[cfg(feature = "bindings-pin")] + { + enabled::run(args) + } + #[cfg(not(feature = "bindings-pin"))] + { + Err( + "bindings pin support is not compiled; rebuild the CLI with `--features bindings-pin`" + .to_owned(), + ) + } +} + +pub(crate) fn read_portable_bindings(path: &Path) -> Result { + let file = File::open(path).map_err(|_error| "failed to read store bindings".to_owned())?; + let mut bytes = Vec::new(); + file.take(u64::from(MAX_BINDINGS_BYTES) + 1) + .read_to_end(&mut bytes) + .map_err(|_error| "failed to read store bindings".to_owned())?; + let input = + String::from_utf8(bytes).map_err(|_error| "invalid store bindings UTF-8".to_owned())?; + check_portable_size(&input)?; + Ok(input) +} + +pub(crate) fn parse_portable_bindings(input: &str) -> Result { + check_portable_size(input)?; + StoreBindingsDocument::parse(input, usize::from(MAX_BINDINGS_BYTES)) + .map_err(|error| error.to_string()) +} + +fn check_portable_size(input: &str) -> Result<(), String> { + if input.len() > usize::from(MAX_BINDINGS_BYTES) || input.chars().count() > MAX_BINDINGS_CHARS { + return Err("store bindings exceed the Fastly Config Store entry limit".to_owned()); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::fs; + + #[cfg(not(feature = "bindings-pin"))] + #[test] + fn bindings_pin_feature_off_reports_support_not_compiled() { + let args = BindingsPinArgs { + adapter: "fastly".to_owned(), + store_bindings: "absent.toml".into(), + }; + assert!( + run_config_bindings_pin(&args) + .unwrap_err() + .contains("not compiled") + ); + } + + #[test] + fn bindings_pin_rejects_other_targets_before_any_file_access() { + let args = BindingsPinArgs { + adapter: "axum".to_owned(), + store_bindings: "absent.toml".into(), + }; + assert_eq!( + run_config_bindings_pin(&args).unwrap_err(), + "bindings pin supports only `--adapter fastly`" + ); + } + + #[test] + fn bindings_files_are_capped_and_malformed_input_is_redacted() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("bindings.toml"); + fs::write(&path, "#".repeat(MAX_BINDINGS_CHARS + 1)).unwrap(); + assert!(read_portable_bindings(&path).unwrap_err().contains("limit")); + assert_eq!( + parse_portable_bindings("not TOML with a secret").unwrap_err(), + "malformed store bindings" + ); + } +} diff --git a/crates/edgezero-cli/src/config.rs b/crates/edgezero-cli/src/config.rs index 099e4f277..84abe69e8 100644 --- a/crates/edgezero-cli/src/config.rs +++ b/crates/edgezero-cli/src/config.rs @@ -22,6 +22,7 @@ use crate::args::{ ConfigDiffArgs, ConfigGcArgs, ConfigPushArgs, ConfigValidateArgs, DiffFormat, parse_duration_secs, }; +use crate::bindings_pin::{parse_portable_bindings, read_portable_bindings}; use crate::diff::{collect_changes, render_json, render_structured}; use crate::{ensure_adapter_defined, manifest_variable_defaults}; use edgezero_adapter::registry::{ @@ -235,7 +236,7 @@ struct ResolvedTomlLeaf<'raw> { #[inline] pub fn run_config_validate(args: &ConfigValidateArgs) -> Result<(), String> { if args.store_bindings.is_some() || args.adapter.is_some() { - return run_native_bindings_validate(args); + return run_bindings_validate(args); } reject_target_controls_without_bindings(args)?; let ctx = load_validation_context(args)?; @@ -258,7 +259,7 @@ where C: DeserializeOwned + Validate + AppConfigMeta, { if args.store_bindings.is_some() || args.adapter.is_some() { - return run_native_bindings_validate(args); + return run_bindings_validate(args); } reject_target_controls_without_bindings(args)?; let ctx = load_validation_context(args)?; @@ -1586,6 +1587,84 @@ fn load_validated_native_bindings( Ok(bindings) } +fn run_bindings_validate(args: &ConfigValidateArgs) -> Result<(), String> { + if args + .adapter + .as_deref() + .is_some_and(|adapter| adapter.eq_ignore_ascii_case("fastly")) + { + return run_portable_bindings_validate(args); + } + run_native_bindings_validate(args) +} + +fn run_portable_bindings_validate(args: &ConfigValidateArgs) -> Result<(), String> { + use edgezero_adapter::store_bindings::{PortableDeclarations, PortableRecordProviders}; + + let path = args + .store_bindings + .as_deref() + .ok_or_else(|| "bindings-only validation requires `--store-bindings `".to_owned())?; + if args.app_config.is_some() { + return Err("`--app-config` cannot be used with bindings-only validation".to_owned()); + } + reject_target_controls_without_bindings(args)?; + let loader = ManifestLoader::from_path(&args.manifest) + .map_err(|_error| "failed to load application manifest".to_owned())?; + let manifest = loader.manifest(); + let (_name, adapter) = manifest + .adapter_entry("fastly") + .ok_or_else(|| "manifest does not declare the Fastly adapter".to_owned())?; + let kv = manifest + .stores + .kv + .as_ref() + .map_or_else(Vec::new, |declaration| { + declaration + .ids + .iter() + .map(String::as_str) + .collect::>() + }); + let secrets = manifest + .stores + .secrets + .as_ref() + .map_or_else(Vec::new, |declaration| { + declaration + .ids + .iter() + .map(String::as_str) + .collect::>() + }); + let compiled = PortableRecordProviders { + celld: adapter + .build + .features + .iter() + .any(|feature| feature == "celld-records"), + dynamodb: adapter + .build + .features + .iter() + .any(|feature| feature == "aws-dynamodb-records"), + }; + let input = read_portable_bindings(path)?; + parse_portable_bindings(&input)? + .validate_portable( + &PortableDeclarations { + kv: &kv, + secrets: &secrets, + }, + compiled, + ) + .map_err(|error| format!("invalid Fastly store bindings: {error}"))?; + log::info!( + "[edgezero] Fastly store bindings valid for declared IDs and build features (offline)" + ); + Ok(()) +} + /// Validate only a caller-selected native bindings file. This path intentionally /// does not load app TOML, ambient overlays, tokens, credentials, or deployment env. #[cfg(feature = "edgezero-adapter-axum")] @@ -2934,6 +3013,147 @@ default = "state" } } + const FASTLY_BINDINGS_MANIFEST: &str = r#" +[app] +name = "demo-app" +[adapters.fastly.adapter] +crate = "crates/demo-fastly" +[adapters.fastly.build] +features = ["aws-dynamodb-records", "celld-records"] +[stores.kv] +ids = ["identity", "sessions"] +default = "identity" +[stores.secrets] +ids = ["stores"] +"#; + + const FASTLY_BINDINGS: &str = r#"version = 1 +[kv.identity] +provider = "aws-dynamodb-records" +region = "us-east-1" +table = "identity-table" +namespace = "example/identity" +credentials = { secrets = "stores" } +pinned = { table_arn = "arn:aws:dynamodb:us-east-1:111122223333:table/identity-table" } +[kv.sessions] +provider = "celld-records" +endpoint = "https://unreachable.invalid" +store = "sessions" +access = { mode = "authenticated", token_secret = { secrets = "stores" } } +pinned = { instance = "AAAAAAAAAAAAAAAAAAAAAA" } +"#; + + #[test] + fn fastly_bindings_validation_is_offline_and_skips_typed_app_config() { + let (dir, manifest, app_config) = setup_project(FASTLY_BINDINGS_MANIFEST, "not TOML"); + fs::remove_file(app_config).unwrap(); + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + listener.set_nonblocking(true).unwrap(); + let address = listener.local_addr().unwrap(); + let bindings = dir.path().join("bindings.toml"); + let input = FASTLY_BINDINGS + .replace("https://unreachable.invalid", &format!("https://{address}")) + .replace( + "region =", + &format!("endpoint = 'http://{address}'\nregion ="), + ); + fs::write(&bindings, input).unwrap(); + let mut args = args_for(&manifest); + args.adapter = Some("fastly".to_owned()); + args.store_bindings = Some(bindings); + run_config_validate(&args).unwrap(); + run_config_validate_typed::(&args).unwrap(); + assert!(matches!(listener.accept(), Err(error) if error.kind() == ErrorKind::WouldBlock)); + assert!(!dir.path().join(".edgezero").exists()); + } + + #[test] + fn fastly_bindings_validation_rejects_pins_declarations_and_native_only_providers() { + let (dir, manifest, _app_config) = setup_project(FASTLY_BINDINGS_MANIFEST, "not TOML"); + let bindings = dir.path().join("bindings.toml"); + let mut args = args_for(&manifest); + args.adapter = Some("fastly".to_owned()); + args.store_bindings = Some(bindings.clone()); + for (input, expected) in [ + (FASTLY_BINDINGS.replace("pinned = { instance = \"AAAAAAAAAAAAAAAAAAAAAA\" }", ""), "no pinned identity"), + (FASTLY_BINDINGS.replace("secrets = \"stores\"", "secrets = \"other\""), "undeclared binding"), + (FASTLY_BINDINGS.replace("[kv.sessions]", "[kv.Sessions]"), "undeclared binding"), + (FASTLY_BINDINGS.replace("mode = \"authenticated\", token_secret = { secrets = \"stores\" }", "mode = \"trusted-network\""), "invalid store bindings"), + (FASTLY_BINDINGS.replace("aws-dynamodb-records", "aws-dynamodb").replace("credentials = { secrets = \"stores\" }", "").replace("pinned = { table_arn = \"arn:aws:dynamodb:us-east-1:111122223333:table/identity-table\" }", ""), "unsupported"), + ] { + fs::write(&bindings, input).unwrap(); + let error = run_config_validate(&args).unwrap_err(); + assert!(error.contains(expected), "{error}"); + assert!(!error.contains("unreachable.invalid")); + } + fs::write(&bindings, FASTLY_BINDINGS).unwrap(); + fs::write( + &manifest, + FASTLY_BINDINGS_MANIFEST.replace("ids = [\"stores\"]", "ids = [\"other\"]"), + ) + .unwrap(); + assert!( + run_config_validate(&args) + .unwrap_err() + .contains("undeclared binding") + ); + for feature in ["aws-dynamodb-records", "celld-records"] { + fs::write( + &manifest, + FASTLY_BINDINGS_MANIFEST.replace(feature, "unused"), + ) + .unwrap(); + assert!( + run_config_validate(&args) + .unwrap_err() + .contains("not compiled") + ); + } + fs::write( + &manifest, + FASTLY_BINDINGS_MANIFEST.replace("\"sessions\"", "\"Sessions\""), + ) + .unwrap(); + fs::write( + &bindings, + FASTLY_BINDINGS.replace("[kv.sessions]", "[kv.Sessions]"), + ) + .unwrap(); + assert!( + run_config_validate(&args) + .unwrap_err() + .contains("invalid store bindings") + ); + } + + #[test] + fn fastly_bindings_validation_rejects_app_config_and_native_target_overrides() { + let (dir, manifest, _app_config) = setup_project(FASTLY_BINDINGS_MANIFEST, "not TOML"); + let bindings = dir.path().join("bindings.toml"); + fs::write(&bindings, FASTLY_BINDINGS).unwrap(); + let mut args = args_for(&manifest); + args.adapter = Some("fastly".to_owned()); + assert!( + run_config_validate(&args) + .unwrap_err() + .contains("--store-bindings") + ); + args.store_bindings = Some(bindings); + args.app_config = Some("not-read.toml".into()); + assert!( + run_config_validate(&args) + .unwrap_err() + .contains("--app-config") + ); + args.app_config = None; + args.target_features = vec!["celld-records".to_owned()]; + assert!( + run_config_validate(&args) + .unwrap_err() + .contains("native target controls") + ); + } + #[cfg(feature = "edgezero-adapter-axum")] #[test] fn bindings_only_validation_does_not_require_app_toml() { diff --git a/crates/edgezero-cli/src/generator.rs b/crates/edgezero-cli/src/generator.rs index 329b3eb21..69432af47 100644 --- a/crates/edgezero-cli/src/generator.rs +++ b/crates/edgezero-cli/src/generator.rs @@ -2083,6 +2083,29 @@ git = "https://example.invalid/spin-sdk-test" } fn assert_generated_fastly_entrypoint(project_dir: &Path) { + let cargo = + fs::read_to_string(project_dir.join("crates/demo-app-adapter-fastly/Cargo.toml")) + .expect("read generated Fastly Cargo.toml"); + let parsed: toml::Value = + toml::from_str(&cargo).expect("parse generated Fastly Cargo.toml"); + let features = parsed + .get("features") + .and_then(toml::Value::as_table) + .expect("generated Fastly features"); + for feature in ["aws-dynamodb-records", "celld-records"] { + assert_eq!( + features.get(feature), + Some(&toml::Value::Array(vec![toml::Value::String(format!( + "edgezero-adapter-fastly/{feature}" + ))])), + "incorrect generated Fastly portable forwarding for {feature}", + ); + } + assert_eq!( + features.get("default"), + Some(&toml::Value::Array(Vec::new())), + "Fastly providers must be opt-in" + ); let entrypoint = fs::read_to_string(project_dir.join("crates/demo-app-adapter-fastly/src/main.rs")) .expect("read fastly main.rs"); @@ -2333,6 +2356,18 @@ git = "https://example.invalid/spin-sdk-test" "-cli/Cargo.toml must depend on -core (typed config lives there): {cargo}" ); + let parsed: toml::Value = toml::from_str(&cargo).expect("parse generated CLI Cargo.toml"); + assert_eq!( + parsed["features"]["bindings-pin"], + toml::Value::Array(vec![toml::Value::String( + "edgezero-cli/bindings-pin".to_owned() + )]) + ); + assert_eq!( + parsed["features"]["default"], + toml::Value::Array(vec![toml::Value::String("bindings-pin".to_owned())]) + ); + let main_path = project_dir.join("crates/demo-app-cli/src/main.rs"); let main = fs::read_to_string(&main_path).expect("read cli main.rs"); @@ -2342,6 +2377,7 @@ git = "https://example.invalid/spin-sdk-test" for import in [ "ActiveVersionArgs", "AuthArgs", + "BindingsCmd", "BuildArgs", "ConfigGcArgs", "ConfigPushArgs", @@ -2388,6 +2424,10 @@ git = "https://example.invalid/spin-sdk-test" ); } + assert!(main.contains("Bindings(BindingsCmd)")); + assert!(main.contains("DemoAppConfigCmd::Bindings(BindingsCmd::Pin(args))")); + assert!(main.contains("edgezero_cli::run_config_bindings_pin(&args)")); + // `config gc` reclaims leaked chunk entries. It is UNTYPED on purpose: // it inspects the store's physical entries, not the app-config struct, // so it takes `ConfigGcArgs` and dispatches to the untyped runner. A diff --git a/crates/edgezero-cli/src/lib.rs b/crates/edgezero-cli/src/lib.rs index a7f9297c3..4834695ed 100644 --- a/crates/edgezero-cli/src/lib.rs +++ b/crates/edgezero-cli/src/lib.rs @@ -24,6 +24,8 @@ mod adapter; #[cfg(feature = "cli")] mod auth; #[cfg(feature = "cli")] +mod bindings_pin; +#[cfg(feature = "cli")] mod config; #[cfg(all(feature = "cli", feature = "demo-example"))] mod demo_server; @@ -49,6 +51,8 @@ pub mod args; #[cfg(feature = "cli")] pub use auth::run_auth; #[cfg(feature = "cli")] +pub use bindings_pin::run_config_bindings_pin; +#[cfg(feature = "cli")] pub use config::{ DiffExit, run_config_diff_typed, run_config_gc, run_config_push, run_config_push_typed, run_config_validate, run_config_validate_typed, diff --git a/crates/edgezero-cli/src/main.rs b/crates/edgezero-cli/src/main.rs index 491c44929..62243b125 100644 --- a/crates/edgezero-cli/src/main.rs +++ b/crates/edgezero-cli/src/main.rs @@ -3,7 +3,7 @@ #[cfg(feature = "cli")] fn main() { use clap::Parser as _; - use edgezero_cli::args::{self, Args, Command, ConfigCmd}; + use edgezero_cli::args::{self, Args, BindingsCmd, Command, ConfigCmd}; use std::process; let cmd = Args::parse().cmd; @@ -34,6 +34,9 @@ fn main() { // `config gc` needs no typed app-config -- it reclaims unreferenced // chunk entries by inspecting the store -- so it runs in-band here. Command::Config(ConfigCmd::Gc(cmd_args)) => edgezero_cli::run_config_gc(&cmd_args), + Command::Config(ConfigCmd::Bindings(BindingsCmd::Pin(cmd_args))) => { + edgezero_cli::run_config_bindings_pin(&cmd_args) + } Command::Config(ConfigCmd::Validate(cmd_args)) => { edgezero_cli::run_config_validate(&cmd_args) } diff --git a/crates/edgezero-cli/src/templates/cli/Cargo.toml.hbs b/crates/edgezero-cli/src/templates/cli/Cargo.toml.hbs index 027e4c777..958157454 100644 --- a/crates/edgezero-cli/src/templates/cli/Cargo.toml.hbs +++ b/crates/edgezero-cli/src/templates/cli/Cargo.toml.hbs @@ -15,3 +15,7 @@ workspace = true {{{dep_edgezero_cli}}} clap = { workspace = true } log = { workspace = true } + +[features] +default = ["bindings-pin"] +bindings-pin = ["edgezero-cli/bindings-pin"] diff --git a/crates/edgezero-cli/src/templates/cli/src/main.rs.hbs b/crates/edgezero-cli/src/templates/cli/src/main.rs.hbs index 4f74d48ff..5a8106f5d 100644 --- a/crates/edgezero-cli/src/templates/cli/src/main.rs.hbs +++ b/crates/edgezero-cli/src/templates/cli/src/main.rs.hbs @@ -13,7 +13,7 @@ use clap::{Parser, Subcommand}; use edgezero_cli::DiffExit; use edgezero_cli::args::{ - ActiveVersionArgs, AuthArgs, BuildArgs, ConfigDiffArgs, ConfigGcArgs, ConfigPushArgs, + ActiveVersionArgs, AuthArgs, BindingsCmd, BuildArgs, ConfigDiffArgs, ConfigGcArgs, ConfigPushArgs, ConfigValidateArgs, DeployArgs, HealthcheckArgs, NewArgs, ProvisionArgs, RollbackArgs, ServeArgs, }; @@ -69,6 +69,9 @@ enum Cmd { /// path skips. #[derive(Subcommand, Debug)] enum {{NameUpperCamel}}ConfigCmd { + /// Preflight and pin portable store identities. No typed app-config is read. + #[command(subcommand)] + Bindings(BindingsCmd), /// Diff `{{name}}.toml` against the live (or local-emulator) config /// store and report changes. Exits 0 (no changes), 1 (changes with /// `--exit-code`), or 2 (unsupported / error). @@ -112,6 +115,9 @@ fn main() { // `gc` inspects the STORE, not the typed config, so it is not // parameterised over `{{NameUpperCamel}}Config`. Cmd::Config({{NameUpperCamel}}ConfigCmd::Gc(args)) => edgezero_cli::run_config_gc(&args), + Cmd::Config({{NameUpperCamel}}ConfigCmd::Bindings(BindingsCmd::Pin(args))) => { + edgezero_cli::run_config_bindings_pin(&args) + } Cmd::Config({{NameUpperCamel}}ConfigCmd::Push(args)) => { edgezero_cli::run_config_push_typed::<{{NameUpperCamel}}Config>(&args) } diff --git a/crates/edgezero-store-aws/Cargo.toml b/crates/edgezero-store-aws/Cargo.toml index 98fa13139..366d58927 100644 --- a/crates/edgezero-store-aws/Cargo.toml +++ b/crates/edgezero-store-aws/Cargo.toml @@ -16,25 +16,40 @@ snapshot-stores = ["dep:edgezero-core", "dep:bytes", "dep:async-trait", "dep:tok appconfig-agent = ["snapshot-stores", "dep:reqwest", "dep:futures-util"] secrets-manager = ["snapshot-stores", "dep:aws-config", "dep:aws-sdk-secretsmanager", "dep:aws-smithy-runtime-api", "dep:aws-types"] dynamodb-kv = ["snapshot-stores", "dep:aws-config", "dep:aws-sdk-dynamodb", "dep:aws-smithy-runtime-api", "dep:aws-types", "dep:serde_json"] -dynamodb-records = ["dynamodb-kv"] +dynamodb-records = ["dynamodb-kv", "record-core"] +# Shared record format, compiled for every target. Not a public selection. +record-core = ["dep:edgezero-core", "dep:bytes", "dep:async-trait", "dep:serde_json"] +# Portable DynamoDB record transport over EdgeZero outbound HTTP, for every target. +dynamodb-records-portable = [ + "record-core", + "dep:aws-credential-types", + "dep:aws-sigv4", + "dep:base64", + "dep:futures-util", + "futures-util/std", +] [dependencies] +async-trait = { workspace = true, optional = true } +aws-credential-types = { workspace = true, optional = true } +aws-sigv4 = { workspace = true, optional = true } +base64 = { workspace = true, optional = true } +bytes = { workspace = true, optional = true } +edgezero-core = { workspace = true, optional = true } +futures-util = { workspace = true, optional = true } percent-encoding = { workspace = true } serde = { workspace = true } +serde_json = { workspace = true, optional = true } thiserror = { workspace = true } url = { workspace = true } +web-time = { workspace = true } [target.'cfg(not(target_arch = "wasm32"))'.dependencies] -async-trait = { workspace = true, optional = true } aws-config = { workspace = true, optional = true } aws-sdk-secretsmanager = { workspace = true, optional = true } aws-sdk-dynamodb = { workspace = true, optional = true } aws-smithy-runtime-api = { workspace = true, optional = true } aws-types = { workspace = true, optional = true } -serde_json = { workspace = true, optional = true } -bytes = { workspace = true, optional = true } -edgezero-core = { workspace = true, optional = true } -futures-util = { workspace = true, optional = true } reqwest = { workspace = true, optional = true, features = ["stream"] } tokio = { workspace = true, optional = true } @@ -45,3 +60,9 @@ futures = { workspace = true } serde_json = { workspace = true } tempfile = { workspace = true } toml = { workspace = true } + +# A real native HttpClient for portable-transport and interop tests. The adapter +# depends on this crate; Cargo permits the cycle for dev-dependencies only. +[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies] +edgezero-adapter-axum = { workspace = true, features = ["axum"] } +tokio = { workspace = true } diff --git a/crates/edgezero-store-aws/src/dynamodb_kv.rs b/crates/edgezero-store-aws/src/dynamodb_kv.rs index 6076d9675..311a62939 100644 --- a/crates/edgezero-store-aws/src/dynamodb_kv.rs +++ b/crates/edgezero-store-aws/src/dynamodb_kv.rs @@ -78,16 +78,22 @@ impl AwsPreparation { &mut self, settings: &DynamoDbKvSettings, ) -> Result { - let store = self.prepare_dynamodb_store(settings).await?; + let store = self.prepare_dynamodb_store(settings, None).await?; Ok(KvHandle::new(Arc::new(store))) } + /// `endpoint` overrides SDK endpoint resolution. It is part of the client cache key. async fn prepare_dynamodb_store( &mut self, settings: &DynamoDbKvSettings, + endpoint: Option<&str>, ) -> Result { self.validate_dynamodb_mapping(settings)?; - let key = (settings.region.clone(), settings.limits); + let key = ( + settings.region.clone(), + settings.limits, + endpoint.map(str::to_owned), + ); let client = if let Some(client) = self.dynamodb_clients.get(&key) { client.clone() } else { @@ -98,17 +104,18 @@ impl AwsPreparation { .load() .await; self.check_deadline()?; - Ok::(Client::from_conf( - aws_sdk_dynamodb::Config::from(&shared) - .to_builder() - .region(Region::new(settings.region.clone())) - .retry_config(RetryConfig::standard().with_max_attempts(1)) - .timeout_config(timeout_policy( - settings.limits, - Duration::from_millis(settings.limits.operation_timeout_ms), - )) - .build(), - )) + let mut builder = aws_sdk_dynamodb::Config::from(&shared) + .to_builder() + .region(Region::new(settings.region.clone())) + .retry_config(RetryConfig::standard().with_max_attempts(1)) + .timeout_config(timeout_policy( + settings.limits, + Duration::from_millis(settings.limits.operation_timeout_ms), + )); + if let Some(url) = endpoint { + builder = builder.endpoint_url(url); + } + Ok::(Client::from_conf(builder.build())) }) .await; self.check_deadline()?; diff --git a/crates/edgezero-store-aws/src/dynamodb_records.rs b/crates/edgezero-store-aws/src/dynamodb_records.rs index 36d341c7a..538ae6e43 100644 --- a/crates/edgezero-store-aws/src/dynamodb_records.rs +++ b/crates/edgezero-store-aws/src/dynamodb_records.rs @@ -1,58 +1,59 @@ -//! Explicit partitioned record format. Allocators survive value deletion and TTL. +//! Native SDK transport for the explicit partitioned record format. +//! Allocators survive value deletion and TTL. The format lives in `records_core`. + +#![expect( + clippy::arbitrary_source_item_ordering, + reason = "keep preparation, the SDK transport and its conversions grouped" +)] use std::collections::HashMap; -use std::future::Future; use std::sync::Arc; -use std::time::{Duration, SystemTime, UNIX_EPOCH}; use async_trait::async_trait; +use aws_sdk_dynamodb::Client; +use aws_sdk_dynamodb::config::Builder; +use aws_sdk_dynamodb::config::retry::RetryConfig; use aws_sdk_dynamodb::error::{ProvideErrorMetadata, SdkError}; use aws_sdk_dynamodb::primitives::Blob; use aws_sdk_dynamodb::types::{AttributeValue, ReturnValue, TableDescription}; -use bytes::Bytes; -use edgezero_core::key_value_store::{KvError, KvHandle, KvPage, KvStore}; -use edgezero_core::time::Deadline; -use serde::{Deserialize, Serialize}; +#[cfg(test)] +use edgezero_core::key_value_store::KvError; +use edgezero_core::key_value_store::KvHandle; +use edgezero_core::record_store::RecordLayout; +use edgezero_core::time::{Deadline, MonotonicClock}; use tokio::time::timeout; -use super::{ - DynamoDbStore, MAX_CURSOR_BYTES, MAX_ITEM_BYTES, MAX_KEY_BYTES, MAX_PAGE_KEYS, - expiry_from_duration, invalid_input, read_unsigned, -}; +use super::{DynamoDbStore, timeout_policy}; use crate::PreparationError; use crate::preparation::AwsPreparation; -use crate::settings::DynamoDbKvSettings; -use edgezero_core::record_store::{ - Record, RecordBinding, RecordGeneration, RecordLayout, RecordPage, RecordPartition, - RecordWrite, RecordWriteMode, RecordWriteOutcome, +use crate::records_core::{ + Attr, Item, Operation, RecordCore, RecordScope, RecordTransport, Request, Response, + TransportError, record_binding, record_partition_base, +}; +#[cfg(test)] +use crate::records_core::{FORMAT, invalid_input, physical_key}; +use crate::settings::{ + DynamoDbKvLimits, DynamoDbKvSettings, DynamoDbPinnedIdentity, DynamoDbRecordIdentity, + DynamoDbRecordsSettings, }; -const FORMAT: &str = "edgezero-dynamodb-records-v1"; -const MAX_PARTITION_BYTES: usize = 2_048; +pub(super) use crate::settings::endpoint_identity; -struct DynamoDbRecordStore { - binding: RecordBinding, - inner: DynamoDbStore, - partition_base: String, -} +type DynamoDbRecordStore = RecordCore; -pub(super) struct PreparedRecordIdentity { - endpoint: String, - table_arn: Option, - table_id: Option, +/// The SDK client and fixed operation policy for one table. +pub(crate) struct NativeTransport { + client: Client, + clock: MonotonicClock, + limits: DynamoDbKvLimits, + table: String, } -#[derive(Deserialize, Serialize)] -#[serde(deny_unknown_fields)] -struct RecordCursor { - format: String, - layout_id: String, - layout_version: u32, - mode: String, - pk: String, - prefix: String, - scope: String, - sk: String, +/// Native preparation output bound into record scopes. +pub(crate) struct PreparedRecordIdentity { + pub endpoint: String, + pub table_arn: Option, + pub table_id: Option, } #[expect( @@ -74,21 +75,101 @@ impl AwsPreparation { &mut self, settings: &DynamoDbKvSettings, layout: &RecordLayout, + ) -> Result { + self.prepare_dynamodb_records_pinned(settings, layout, None) + .await + } + + /// Prepares like [`Self::prepare_dynamodb_records`], then requires the observed + /// table identity to equal `pinned` when one is supplied. + /// + /// # Errors + /// Returns [`PreparationError::PinnedIdentityMismatch`] when the table ARN or table + /// ID differs, and any preparation failure otherwise. + #[inline] + pub async fn prepare_dynamodb_records_pinned( + &mut self, + settings: &DynamoDbKvSettings, + layout: &RecordLayout, + pinned: Option<&DynamoDbPinnedIdentity>, ) -> Result { let partition_base = record_partition_base(settings, layout)?; - let inner = self.prepare_dynamodb_store(settings).await?; - Ok(KvHandle::new(Arc::new(DynamoDbRecordStore::new( + let inner = self.prepare_dynamodb_store(settings, None).await?; + Ok(KvHandle::new(Arc::new(pinned_store( inner, layout.clone(), partition_base, + pinned, )?))) } + + /// Offline preflight for a portable binding. Describes the table through the + /// binding's own endpoint, with the SDK credential chain, and returns the identity + /// to pin. It rejects every table native record preparation rejects and writes nothing. + /// + /// # Errors + /// Returns [`PreparationError::InvalidEndpoint`] when the endpoint the SDK used + /// differs from the one a portable transport would use, and any preparation failure. + #[inline] + pub async fn preflight_dynamodb_records( + &mut self, + settings: &DynamoDbRecordsSettings, + ) -> Result { + let endpoint = settings.portable_endpoint()?; + let address = settings.kv_settings(DynamoDbKvLimits::default()); + let inner = self + .prepare_dynamodb_store(&address, Some(&endpoint)) + .await?; + preflight_identity(&inner, &endpoint) + } +} + +/// Requires the observed table identity to equal `pinned` when one is supplied. +fn pinned_store( + inner: DynamoDbStore, + layout: RecordLayout, + partition_base: String, + pinned: Option<&DynamoDbPinnedIdentity>, +) -> Result { + if let Some(expected) = pinned + && observed_identity(&inner)?.pinned != *expected + { + return Err(PreparationError::PinnedIdentityMismatch); + } + DynamoDbRecordStore::new(inner, layout, partition_base) +} + +/// The identity to pin, if the SDK used exactly the endpoint a portable transport uses. +fn preflight_identity( + inner: &DynamoDbStore, + endpoint: &str, +) -> Result { + let identity = observed_identity(inner)?; + if identity.endpoint != endpoint { + return Err(PreparationError::InvalidEndpoint); + } + Ok(identity) +} + +fn observed_identity(inner: &DynamoDbStore) -> Result { + let identity = inner + .record_identity + .as_ref() + .ok_or(PreparationError::Malformed)?; + let table_arn = identity + .table_arn + .clone() + .filter(|arn| !arn.is_empty()) + .ok_or(PreparationError::Malformed)?; + Ok(DynamoDbRecordIdentity { + endpoint: identity.endpoint.clone(), + pinned: DynamoDbPinnedIdentity { + table_arn, + table_id: identity.table_id.clone(), + }, + }) } -#[expect( - clippy::arbitrary_source_item_ordering, - reason = "keep prepared identity, point operations and native pagination helpers grouped" -)] impl DynamoDbRecordStore { fn new( inner: DynamoDbStore, @@ -104,617 +185,200 @@ impl DynamoDbRecordStore { .as_deref() .filter(|arn| !arn.is_empty()) .ok_or(PreparationError::Malformed)?; - let scope = serde_json::to_string(&( - &identity.endpoint, - table_arn, - &identity.table_id, - &inner.region, - &inner.table, - &inner.namespace, - )) - .map_err(|_error| PreparationError::Malformed)?; - Ok(Self { - binding: RecordBinding { - layout, - scope, - format: FORMAT.to_owned(), - // Metadata may use the full configured payload budget when the - // body is empty. Inserts also enforce their combined byte size. - max_metadata_bytes: inner.limits.max_value_bytes, + let binding = record_binding( + inner.limits, + layout, + &RecordScope { + endpoint: &identity.endpoint, + namespace: &inner.namespace, + region: &inner.region, + table: &inner.table, + table_arn, + table_id: identity.table_id.as_deref(), }, - inner, + )?; + Ok(Self { + binding, + clock: inner.clock.clone(), + limits: inner.limits, partition_base, + transport: NativeTransport { + client: inner.client, + clock: inner.clock, + limits: inner.limits, + table: inner.table, + }, }) } +} - fn partition_key(&self, partition: &RecordPartition) -> Result { - if self.binding.layout.partition(partition.prefix())? != *partition { - return Err(invalid_input()); - } - let pk = format!("{}{}", self.partition_base, partition.prefix()); - if pk.len() > MAX_PARTITION_BYTES { - return Err(invalid_input()); - } - Ok(pk) - } - - fn key( - &self, - key: &str, - partition: &RecordPartition, - kind: &str, - ) -> Result, KvError> { - if self.binding.layout.resolve(key)? != *partition { - return Err(invalid_input()); - } - Ok(physical_key( - self.partition_key(partition)?, - format!("{kind}#{key}"), - )) +impl NativeTransport { + fn operation_policy(&self, deadline: Deadline) -> Result { + let budget = deadline + .remaining_at(self.clock.now()) + .filter(|remaining| !remaining.is_zero()) + .ok_or(TransportError::NotDispatched)?; + Ok(aws_sdk_dynamodb::Config::builder() + .retry_config(RetryConfig::standard().with_max_attempts(1)) + .timeout_config(timeout_policy(self.limits, budget))) } - async fn allocate( + async fn send( &self, - key: &str, - partition: &RecordPartition, - deadline: Deadline, - ) -> Result { - // Failure here cannot have changed a value row. An unobserved allocation - // is merely a gap, and is never represented as a successful value write. - self.inner - .bounded(deadline, async { + operation: Operation, + request: Request, + policy: Builder, + ) -> Result { + match operation { + Operation::Query | Operation::Scan => self.send_page(operation, request, policy).await, + Operation::DeleteItem | Operation::GetItem | Operation::PutItem => { + self.send_point(operation, request, policy).await + } + Operation::UpdateItem => { + let (names, values) = expression_maps(&request); let output = self - .inner .client .update_item() - .table_name(&self.inner.table) - .set_key(Some(self.key(key, partition, "g")?)) - .update_expression("SET #generation = if_not_exists(#generation, :zero) + :one") - .condition_expression( - "attribute_not_exists(#generation) OR #generation < :ceiling", - ) - .expression_attribute_names("#generation", "generation") - .expression_attribute_values(":zero", AttributeValue::N("0".to_owned())) - .expression_attribute_values(":one", AttributeValue::N("1".to_owned())) - .expression_attribute_values( - ":ceiling", - AttributeValue::N(u64::MAX.to_string()), + .table_name(&self.table) + .set_key(request.key.map(to_sdk_item)) + .set_update_expression(request.update_expression.map(str::to_owned)) + .set_condition_expression(request.condition_expression.map(str::to_owned)) + .set_expression_attribute_names(names) + .set_expression_attribute_values(values) + .set_return_values( + request + .return_updated_new + .then_some(ReturnValue::UpdatedNew), ) - .return_values(ReturnValue::UpdatedNew) .customize() - .config_override(self.inner.operation_policy(deadline)?) + .config_override(policy) .send() .await - .map_err(|_error| KvError::Unavailable)?; - let generation = output - .attributes - .as_ref() - .and_then(|attributes| attributes.get("generation")) - .and_then(|value| value.as_n().ok()) - .ok_or(KvError::Unavailable) - .and_then(|value| read_unsigned(value))?; - if generation == 0 { - return Err(KvError::Unavailable); - } - Ok(RecordGeneration::from_u64(generation)) - }) - .await - } - - async fn mutate( - &self, - deadline: Deadline, - operation: impl Future>, - ) -> Result { - let remaining = deadline - .remaining_at(self.inner.clock.now()) - .filter(|remaining| !remaining.is_zero()) - .ok_or(KvError::Unavailable)?; - let result = timeout(remaining, operation) - .await - .map_err(|_elapsed| KvError::MutationUncertain)?; - if deadline.is_expired_at(self.inner.clock.now()) { - return Err(KvError::MutationUncertain); - } - result - } - - async fn insert( - &self, - key: &str, - partition: &RecordPartition, - write: RecordWrite<'_>, - ) -> Result { - let deadline = self.inner.runtime_deadline()?; - let metadata = write.metadata.filter(|text| !text.is_empty()); - if write - .body - .len() - .checked_add(metadata.map_or(0, str::len)) - .is_none_or(|bytes| bytes > self.inner.limits.max_value_bytes) - { - return Err(invalid_input()); - } - let expiry = write - .ttl - .map(|ttl| { - let now = SystemTime::now() - .duration_since(UNIX_EPOCH) - .map_err(|_error| KvError::Unavailable)?; - // Native TTL is in seconds. Rounding up never shortens the requested TTL. - Ok::(expiry_from_duration(now, ttl)?.div_ceil(1_000)) - }) - .transpose()?; - let mut item = self.key(key, partition, "r")?; - item.insert("v".to_owned(), AttributeValue::B(Blob::new(write.body))); - item.insert("format".to_owned(), AttributeValue::S(FORMAT.to_owned())); - item.insert("kind".to_owned(), AttributeValue::S("r".to_owned())); - if let Some(text) = metadata { - item.insert("metadata".to_owned(), AttributeValue::S(text.to_owned())); - } - if let Some(expires) = expiry { - item.insert( - "ttl_epoch_s".to_owned(), - AttributeValue::N(expires.to_string()), - ); - } - // Include the maximum generation before allocation so oversized values - // never consume an allocator request. - item.insert( - "generation".to_owned(), - AttributeValue::N(u64::MAX.to_string()), - ); - validate_record_size(&item)?; - let generation = self.allocate(key, partition, deadline).await?; - item.insert( - "generation".to_owned(), - AttributeValue::N(generation.as_u64().to_string()), - ); - // Resolve the remaining policy before constructing the mutation future. - // Deadline exhaustion after allocation alone remains Unavailable. - let policy = self.inner.operation_policy(deadline)?; - let mut request = self - .inner - .client - .put_item() - .table_name(&self.inner.table) - .set_item(Some(item)); - match write.mode { - RecordWriteMode::Overwrite => {} - RecordWriteMode::Add => { - request = request - .condition_expression("attribute_not_exists(#pk)") - .expression_attribute_names("#pk", "pk"); - } - RecordWriteMode::IfGenerationMatch(expected) => { - request = request - .condition_expression("#generation = :expected") - .expression_attribute_names("#generation", "generation") - .expression_attribute_values( - ":expected", - AttributeValue::N(expected.as_u64().to_string()), - ); + .map_err(|error| transport_error(&error))?; + Ok(Response { + attributes: output.attributes.map(from_sdk_item), + ..Response::default() + }) } } - self.mutate(deadline, async { - match request.customize().config_override(policy).send().await { - Ok(_) => Ok(RecordWriteOutcome::Written), - Err(error) - if write.mode != RecordWriteMode::Overwrite - && error.as_service_error().is_some_and(|service| { - service.is_conditional_check_failed_exception() - }) => - { - Ok(RecordWriteOutcome::PreconditionFailed) - } - Err(error) => Err(mutation_error(&error)), - } - }) - .await } - async fn lookup( + async fn send_point( &self, - key: &str, - partition: &RecordPartition, - ) -> Result, KvError> { - let deadline = self.inner.runtime_deadline()?; - let expected = self.key(key, partition, "r")?; - self.inner - .bounded(deadline, async { - let output = self - .inner - .client - .get_item() - .table_name(&self.inner.table) - .set_key(Some(expected.clone())) - .consistent_read(true) - .customize() - .config_override(self.inner.operation_policy(deadline)?) - .send() - .await - .map_err(|_error| KvError::Unavailable)?; - output - .item - .map(|mut item| { - if expected - .iter() - .any(|(name, value)| item.get(name) != Some(value)) - { - return Err(KvError::Unavailable); - } - validate_value_kind(&item)?; - let generation = match item.remove("generation") { - Some(AttributeValue::N(value)) => { - RecordGeneration::from_u64(read_unsigned(&value)?) - } - _ => return Err(KvError::Unavailable), - }; - let metadata = match item.remove("metadata") { - None => None, - Some(AttributeValue::S(text)) - if text.len() <= self.inner.limits.max_value_bytes => - { - (!text.is_empty()).then_some(text) - } - _ => return Err(KvError::Unavailable), - }; - let body = match item.remove("v") { - Some(AttributeValue::B(body)) - if body.as_ref().len() <= self.inner.limits.max_value_bytes => - { - Bytes::from(body.into_inner()) - } - _ => return Err(KvError::Unavailable), - }; - if body - .len() - .checked_add(metadata.as_deref().map_or(0, str::len)) - .is_none_or(|bytes| bytes > self.inner.limits.max_value_bytes) - { - return Err(KvError::Unavailable); - } - // Check native TTL's shape but never impose a hard expiry filter. - if let Some(ttl) = item.get("ttl_epoch_s") { - let number = ttl.as_n().map_err(|_error| KvError::Unavailable)?; - read_unsigned(number)?; - } - Ok(Record { - body, - metadata, - generation, - }) - }) - .transpose() - }) - .await - } - - async fn delete_value(&self, key: &str, partition: &RecordPartition) -> Result<(), KvError> { - let deadline = self.inner.runtime_deadline()?; - let attributes = self.key(key, partition, "r")?; - let policy = self.inner.operation_policy(deadline)?; - self.mutate(deadline, async { - self.inner + operation: Operation, + request: Request, + policy: Builder, + ) -> Result { + let (names, values) = expression_maps(&request); + if operation == Operation::GetItem { + let output = self .client - .delete_item() - .table_name(&self.inner.table) - .set_key(Some(attributes)) + .get_item() + .table_name(&self.table) + .set_key(request.key.map(to_sdk_item)) + .set_consistent_read(request.consistent_read) .customize() .config_override(policy) .send() .await - .map_err(|error| mutation_error(&error))?; - Ok(()) - }) - .await - } - - fn decode_cursor( - &self, - mode: &str, - prefix: &str, - encoded: &str, - partition: Option<&RecordPartition>, - ) -> Result, KvError> { - if encoded.len() > MAX_CURSOR_BYTES { - return Err(invalid_input()); - } - let cursor: RecordCursor = - serde_json::from_str(encoded).map_err(|_error| invalid_input())?; - if cursor.format != FORMAT - || cursor.layout_id != self.binding.layout.id() - || cursor.layout_version != self.binding.layout.version() - || cursor.scope != self.binding.scope - || cursor.mode != mode - || cursor.prefix != prefix - { - return Err(invalid_input()); - } - let key = physical_key(cursor.pk, cursor.sk); - validate_position(&key).map_err(|_error| invalid_input())?; - if let Some(expected_partition) = partition - && key.get("pk") != Some(&AttributeValue::S(self.partition_key(expected_partition)?)) - { - return Err(invalid_input()); - } - Ok(key) - } - - fn next_cursor( - &self, - mode: &str, - prefix: &str, - after: Option<&HashMap>, - next_position: Option>, - partition: Option<&RecordPartition>, - ) -> Result, KvError> { - let Some(position) = next_position.filter(|candidate| !candidate.is_empty()) else { - return Ok(None); - }; - let (pk, sk) = validate_position(&position)?; - if after == Some(&position) { - return Err(KvError::Unavailable); - } - if let Some(expected_partition) = partition - && (pk != self.partition_key(expected_partition)? - || after - .and_then(|key| key.get("sk")) - .and_then(|value| value.as_s().ok()) - .is_some_and(|previous| sk <= previous.as_str())) - { - return Err(KvError::Unavailable); + .map_err(|error| transport_error(&error))?; + return Ok(Response { + item: output.item.map(from_sdk_item), + ..Response::default() + }); } - let encoded = serde_json::to_string(&RecordCursor { - format: FORMAT.to_owned(), - layout_id: self.binding.layout.id().to_owned(), - layout_version: self.binding.layout.version(), - mode: mode.to_owned(), - pk: pk.to_owned(), - prefix: prefix.to_owned(), - scope: self.binding.scope.clone(), - sk: sk.to_owned(), - }) - .map_err(|_error| KvError::Unavailable)?; - if encoded.len() > MAX_CURSOR_BYTES { - return Err(KvError::Unavailable); - } - Ok(Some(encoded)) - } - - fn listed_keys( - &self, - items: Vec>, - prefix: &str, - limit: usize, - partition: Option<&RecordPartition>, - ) -> Result, KvError> { - if items.len() > limit { - return Err(KvError::Unavailable); + if operation == Operation::PutItem { + self.client + .put_item() + .table_name(&self.table) + .set_item(request.item.map(to_sdk_item)) + .set_condition_expression(request.condition_expression.map(str::to_owned)) + .set_expression_attribute_names(names) + .set_expression_attribute_values(values) + .customize() + .config_override(policy) + .send() + .await + .map_err(|error| transport_error(&error))?; + return Ok(Response::default()); } - items - .into_iter() - .map(|item| { - validate_value_kind(&item)?; - let (pk, sk) = validate_position_item(&item)?; - let key = sk - .strip_prefix("r#") - .filter(|key| key.starts_with(prefix)) - .ok_or(KvError::Unavailable)?; - let resolved = self - .binding - .layout - .resolve(key) - .map_err(|_error| KvError::Unavailable)?; - if pk != self.partition_key(&resolved)? - || partition.is_some_and(|expected| expected != &resolved) - { - return Err(KvError::Unavailable); - } - Ok(key.to_owned()) - }) - .collect() + self.client + .delete_item() + .table_name(&self.table) + .set_key(request.key.map(to_sdk_item)) + .customize() + .config_override(policy) + .send() + .await + .map_err(|error| transport_error(&error))?; + Ok(Response::default()) } - async fn page( + async fn send_page( &self, - prefix: &str, - partition: Option<&RecordPartition>, - cursor: Option<&str>, - limit: usize, - ) -> Result { - let deadline = self.inner.runtime_deadline()?; - if prefix.len() > MAX_KEY_BYTES || prefix.chars().any(char::is_control) { - return Err(invalid_input()); - } - if limit == 0 || limit > MAX_PAGE_KEYS { - return Err(invalid_input()); + operation: Operation, + request: Request, + policy: Builder, + ) -> Result { + let (names, values) = expression_maps(&request); + if operation == Operation::Query { + let output = self + .client + .query() + .table_name(&self.table) + .set_consistent_read(request.consistent_read) + .set_scan_index_forward(request.scan_index_forward) + .set_limit(request.limit) + .set_key_condition_expression(request.key_condition_expression.map(str::to_owned)) + .set_filter_expression(request.filter_expression.map(str::to_owned)) + .set_projection_expression(request.projection_expression.map(str::to_owned)) + .set_expression_attribute_names(names) + .set_expression_attribute_values(values) + .set_exclusive_start_key(request.exclusive_start_key.map(to_sdk_item)) + .customize() + .config_override(policy) + .send() + .await + .map_err(|error| transport_error(&error))?; + return Ok(page_response(output.items, output.last_evaluated_key)); } - let mode = if partition.is_some() { "query" } else { "scan" }; - let after = cursor - .map(|encoded| self.decode_cursor(mode, prefix, encoded, partition)) - .transpose()?; - let native_limit = i32::try_from(limit).map_err(|_error| invalid_input())?; - let names = HashMap::from([ - ("#pk".to_owned(), "pk".to_owned()), - ("#sk".to_owned(), "sk".to_owned()), - ("#format".to_owned(), "format".to_owned()), - ("#kind".to_owned(), "kind".to_owned()), - ]); - let base_values = HashMap::from([ - (":format".to_owned(), AttributeValue::S(FORMAT.to_owned())), - (":kind".to_owned(), AttributeValue::S("r".to_owned())), - ( - ":prefix".to_owned(), - AttributeValue::S(format!("r#{prefix}")), - ), - ]); - self.inner.bounded(deadline, async { - let (items, position) = if let Some(query_partition) = partition { - let mut values = base_values; - values.insert(":pk".to_owned(), AttributeValue::S(self.partition_key(query_partition)?)); - let output = self.inner.client.query().table_name(&self.inner.table).consistent_read(true) - .scan_index_forward(true).limit(native_limit) - .key_condition_expression("#pk = :pk") - .filter_expression("#format = :format AND #kind = :kind") - .projection_expression("#pk, #sk, #format, #kind") - .set_expression_attribute_names(Some(names)) - // Query cannot filter a key attribute. Full membership is - // checked below, while the partition PK already bounds keys. - .set_expression_attribute_values(Some(values.into_iter().filter(|(name, _)| name != ":prefix").collect())) - .set_exclusive_start_key(after.clone()) - .customize().config_override(self.inner.operation_policy(deadline)?) - .send().await.map_err(|_error| KvError::Unavailable)?; - (output.items.unwrap_or_default(), output.last_evaluated_key) - } else { - let mut values = base_values; - values.insert(":binding".to_owned(), AttributeValue::S(self.partition_base.clone())); - let output = self.inner.client.scan().table_name(&self.inner.table).limit(native_limit) - .filter_expression("begins_with(#pk, :binding) AND #format = :format AND #kind = :kind AND begins_with(#sk, :prefix)") - .projection_expression("#pk, #sk, #format, #kind") - .set_expression_attribute_names(Some(names)).set_expression_attribute_values(Some(values)) - .set_exclusive_start_key(after.clone()) - .customize().config_override(self.inner.operation_policy(deadline)?) - .send().await.map_err(|_error| KvError::Unavailable)?; - (output.items.unwrap_or_default(), output.last_evaluated_key) - }; - if partition.is_some() { - validate_query_positions(&items, after.as_ref(), position.as_ref())?; - } - let keys = self.listed_keys(items, prefix, limit, partition)?; - let next = self.next_cursor(mode, prefix, after.as_ref(), position, partition)?; - Ok(KvPage { keys, cursor: next }) - }).await + let output = self + .client + .scan() + .table_name(&self.table) + .set_limit(request.limit) + .set_filter_expression(request.filter_expression.map(str::to_owned)) + .set_projection_expression(request.projection_expression.map(str::to_owned)) + .set_expression_attribute_names(names) + .set_expression_attribute_values(values) + .set_exclusive_start_key(request.exclusive_start_key.map(to_sdk_item)) + .customize() + .config_override(policy) + .send() + .await + .map_err(|error| transport_error(&error))?; + Ok(page_response(output.items, output.last_evaluated_key)) } } -#[expect( - clippy::arbitrary_source_item_ordering, - reason = "keep prepared capability and ordinary methods ahead of the record boundary" -)] -#[expect( - clippy::missing_trait_methods, - reason = "ordinary exists deliberately delegates to the same strong get-bytes path" -)] #[async_trait(?Send)] -impl KvStore for DynamoDbRecordStore { - fn record_binding(&self) -> Option { - Some(self.binding.clone()) - } - - async fn get_bytes(&self, key: &str) -> Result, KvError> { - let partition = self.binding.layout.resolve(key)?; - Ok(self - .lookup(key, &partition) - .await? - .map(|record| record.body)) - } - - async fn put_bytes(&self, key: &str, value: Bytes) -> Result<(), KvError> { - let partition = self.binding.layout.resolve(key)?; - self.insert( - key, - &partition, - RecordWrite { - body: &value, - metadata: None, - ttl: None, - mode: RecordWriteMode::Overwrite, - }, - ) - .await?; - Ok(()) - } - - async fn put_bytes_with_ttl( +impl RecordTransport for NativeTransport { + async fn call( &self, - key: &str, - value: Bytes, - ttl: Duration, - ) -> Result<(), KvError> { - let partition = self.binding.layout.resolve(key)?; - self.insert( - key, - &partition, - RecordWrite { - body: &value, - metadata: None, - ttl: Some(ttl), - mode: RecordWriteMode::Overwrite, - }, - ) - .await?; - Ok(()) - } - - async fn delete(&self, key: &str) -> Result<(), KvError> { - self.delete_value(key, &self.binding.layout.resolve(key)?) + operation: Operation, + request: Request, + deadline: Deadline, + ) -> Result { + // Resolve the remaining policy before constructing the request future. + let policy = self.operation_policy(deadline)?; + let remaining = deadline + .remaining_at(self.clock.now()) + .filter(|budget| !budget.is_zero()) + .ok_or(TransportError::NotDispatched)?; + timeout(remaining, self.send(operation, request, policy)) .await + .map_err(|_elapsed| TransportError::Uncertain)? } - - async fn list_keys_page( - &self, - prefix: &str, - cursor: Option<&str>, - limit: usize, - ) -> Result { - self.page(prefix, None, cursor, limit).await - } - - async fn record_lookup( - &self, - key: &str, - partition: &RecordPartition, - ) -> Result, KvError> { - self.lookup(key, partition).await - } - - async fn record_insert( - &self, - key: &str, - partition: &RecordPartition, - write: RecordWrite<'_>, - ) -> Result { - self.insert(key, partition, write).await - } - - async fn record_exists_strong( - &self, - key: &str, - partition: &RecordPartition, - ) -> Result { - Ok(self.lookup(key, partition).await?.is_some()) - } - - async fn record_delete(&self, key: &str, partition: &RecordPartition) -> Result<(), KvError> { - self.delete_value(key, partition).await - } - - async fn record_list_partition( - &self, - partition: &RecordPartition, - cursor: Option<&str>, - limit: usize, - ) -> Result { - self.partition_key(partition)?; - let page = self - .page(partition.prefix(), Some(partition), cursor, limit) - .await?; - Ok(RecordPage { - keys: page.keys, - cursor: page.cursor, - }) - } -} - -pub(super) fn endpoint_identity(uri: &str) -> Option { - let mut endpoint = url::Url::parse(uri).ok()?; - endpoint.host_str()?; - endpoint.set_username("").ok()?; - endpoint.set_password(None).ok()?; - endpoint.set_query(None); - endpoint.set_fragment(None); - Some(endpoint.into()) } pub(super) fn prepared_identity( @@ -728,132 +392,89 @@ pub(super) fn prepared_identity( }) } -fn mutation_error(error: &SdkError) -> KvError -where - E: ProvideErrorMetadata, -{ - if matches!(error, SdkError::ConstructionFailure(_)) - || error.as_service_error().is_some_and(|_service| { - error - .raw_response() - .is_some_and(|response| (400..500).contains(&response.status().as_u16())) - }) - { - KvError::Unavailable - } else { - KvError::MutationUncertain - } -} +type SdkNames = Option>; +type SdkValues = Option>; -fn physical_key(pk: String, sk: String) -> HashMap { - HashMap::from([ - ("pk".to_owned(), AttributeValue::S(pk)), - ("sk".to_owned(), AttributeValue::S(sk)), - ]) -} - -fn record_partition_base( - settings: &DynamoDbKvSettings, - layout: &RecordLayout, -) -> Result { - // Byte lengths delimit arbitrary namespace/layout identities without escaping - // or collisions. The final remainder is the unchanged declared partition. - settings.validate()?; - let base = format!( - "{FORMAT}#{}:{}{}:{}{}:", - settings.namespace.len(), - settings.namespace, - layout.id().len(), - layout.id(), - layout.version() - ); - if base - .len() - .checked_add(MAX_KEY_BYTES) - .is_none_or(|size| size > MAX_PARTITION_BYTES) - { - return Err(PreparationError::InvalidBinding); - } - Ok(base) +/// The SDK omits an expression map when it is empty; so does the JSON transport. +fn expression_maps(request: &Request) -> (SdkNames, SdkValues) { + let names = (!request.names.is_empty()).then(|| { + request + .names + .iter() + .map(|(alias, name)| (alias.clone(), name.clone())) + .collect() + }); + let values = (!request.values.is_empty()).then(|| to_sdk_item(request.values.clone())); + (names, values) } -fn validate_position(key: &HashMap) -> Result<(&str, &str), KvError> { - if key.len() != 2 { - return Err(KvError::Unavailable); +fn page_response( + items: Option>>, + last_evaluated_key: Option>, +) -> Response { + Response { + items: items + .unwrap_or_default() + .into_iter() + .map(from_sdk_item) + .collect(), + last_evaluated_key: last_evaluated_key.map(from_sdk_item), + ..Response::default() } - validate_position_item(key) } -fn validate_position_item(item: &HashMap) -> Result<(&str, &str), KvError> { - match (item.get("pk"), item.get("sk")) { - (Some(AttributeValue::S(pk)), Some(AttributeValue::S(sk))) - if !pk.is_empty() - && pk.len() <= MAX_PARTITION_BYTES - && !sk.is_empty() - && sk.len() <= 1_024 => - { - Ok((pk, sk)) - } - _ => Err(KvError::Unavailable), - } +/// The SDK's view of one attempt. Only a typed service error is a service reply. +fn transport_error(error: &SdkError) -> TransportError +where + E: ProvideErrorMetadata, +{ + if matches!(error, SdkError::ConstructionFailure(_)) { + return TransportError::NotDispatched; + } + error + .as_service_error() + .map_or(TransportError::Uncertain, |service| { + TransportError::Service { + conditional: service.code() == Some("ConditionalCheckFailedException"), + definitive: error + .raw_response() + .is_some_and(|response| (400..500).contains(&response.status().as_u16())), + } + }) } -fn validate_query_positions( - items: &[HashMap], - after: Option<&HashMap>, - next_position: Option<&HashMap>, -) -> Result<(), KvError> { - let mut previous = after.map(validate_position).transpose()?.map(|(_, sk)| sk); - for item in items { - let (_, sk) = validate_position_item(item)?; - if previous.is_some_and(|last| sk <= last) { - return Err(KvError::Unavailable); - } - previous = Some(sk); - } - if let Some(position) = next_position.filter(|candidate| !candidate.is_empty()) { - let (_, sk) = validate_position(position)?; - if previous.is_some_and(|last| sk < last) { - return Err(KvError::Unavailable); - } - } - Ok(()) +fn to_sdk_item(item: Item) -> HashMap { + item.into_iter() + .map(|(name, value)| (name, to_sdk_value(value))) + .collect() } -fn validate_value_kind(item: &HashMap) -> Result<(), KvError> { - if item.get("format") != Some(&AttributeValue::S(FORMAT.to_owned())) - || item.get("kind") != Some(&AttributeValue::S("r".to_owned())) - { - return Err(KvError::Unavailable); +fn to_sdk_value(value: Attr) -> AttributeValue { + match value { + Attr::Binary(bytes) => AttributeValue::B(Blob::new(bytes)), + Attr::Number(number) => AttributeValue::N(number), + Attr::Text(text) => AttributeValue::S(text), + // The core never sends an opaque value. NULL is the inert placeholder if it did. + Attr::Other => AttributeValue::Null(true), } - Ok(()) } -#[expect( - clippy::iter_over_hash_type, - reason = "checked item-byte summation is independent of attribute order" -)] #[expect( clippy::wildcard_enum_match_arm, - reason = "all non-scalar attribute types are rejected uniformly in the record format" + reason = "every non-scalar SDK attribute type is opaque to the record format" )] -fn validate_record_size(item: &HashMap) -> Result<(), KvError> { - let mut size = 0_usize; - for (name, value) in item { - let bytes = match value { - AttributeValue::S(text) | AttributeValue::N(text) => text.len(), - AttributeValue::B(blob) => blob.as_ref().len(), - _ => return Err(invalid_input()), - }; - size = size - .checked_add(name.len()) - .and_then(|with_name| with_name.checked_add(bytes)) - .ok_or_else(invalid_input)?; - } - if size > MAX_ITEM_BYTES { - return Err(invalid_input()); - } - Ok(()) +fn from_sdk_item(item: HashMap) -> Item { + item.into_iter() + .map(|(name, value)| { + let converted = match value { + AttributeValue::B(blob) => Attr::Binary(blob.into_inner()), + AttributeValue::N(number) => Attr::Number(number), + AttributeValue::S(text) => Attr::Text(text), + _ => Attr::Other, + }; + (name, converted) + }) + .collect() } #[cfg(test)] diff --git a/crates/edgezero-store-aws/src/dynamodb_records_tests.rs b/crates/edgezero-store-aws/src/dynamodb_records_tests.rs index 93e431f6a..f21981db1 100644 --- a/crates/edgezero-store-aws/src/dynamodb_records_tests.rs +++ b/crates/edgezero-store-aws/src/dynamodb_records_tests.rs @@ -8,8 +8,11 @@ use super::*; use crate::dynamodb_kv::sdk_tests::{active_table, loopback_client, read_request}; -use crate::settings::{AwsPreparationLimits, DynamoDbKvLimits}; +use crate::settings::{AwsPreparationLimits, DynamoDbKvLimits, DynamoDbPinnedIdentity}; +use bytes::Bytes; +use edgezero_core::key_value_store::KvStore as _; use edgezero_core::record_store::{RecordKeyLayout, contract}; +use edgezero_core::record_store::{RecordWrite, RecordWriteMode, RecordWriteOutcome}; use edgezero_core::time::MonotonicClock; use serde_json::{Value, json}; use std::collections::{BTreeMap, BTreeSet, VecDeque}; @@ -20,6 +23,7 @@ use std::sync::{ atomic::{AtomicBool, Ordering}, }; use std::thread::{self, JoinHandle}; +use std::time::Duration; use tokio::runtime::{Builder as RuntimeBuilder, Runtime}; #[derive(Clone, Copy)] @@ -1154,6 +1158,406 @@ fn partition_encoding_is_collision_free_and_preserves_full_unicode_keys() { let key_partition = provider_a.binding.layout.resolve(key).unwrap(); assert_eq!( provider_a.key(key, &key_partition, "r").unwrap()["sk"], - AttributeValue::S(format!("r#{key}")) + Attr::Text(format!("r#{key}")) ); } + +#[test] +fn pinned_preparation_and_preflight_use_the_same_table_identity() { + let runtime = runtime(); + let fixture = Fixture::start(); + let settings = settings(); + let endpoint = format!("http://{}", fixture.address); + let prepare = || { + let client = loopback_client(&runtime, &endpoint, settings.limits); + runtime.block_on(async { + let mut preparation = + AwsPreparation::new(MonotonicClock::default(), AwsPreparationLimits::default()) + .unwrap(); + preparation.validate_dynamodb_mapping(&settings).unwrap(); + preparation + .finish_dynamodb_preparation(&settings, client) + .await + .unwrap() + }) + }; + // Preflight reports exactly the identity native preparation binds into cursors. + let identity = preflight_identity(&prepare(), &format!("{endpoint}/")).unwrap(); + assert_eq!( + identity.pinned, + DynamoDbPinnedIdentity { + table_arn: "arn:aws:dynamodb:us-east-1:111111111111:table/fixture-kv".to_owned(), + table_id: Some("fixture-table-id".to_owned()), + } + ); + assert_eq!( + preflight_identity(&prepare(), "https://dynamodb.us-east-1.amazonaws.com/").unwrap_err(), + PreparationError::InvalidEndpoint + ); + // Preflight only describes the table. + assert!( + fixture + .requests() + .iter() + .all(|(target, _)| target == "DescribeTable") + ); + let layout = RecordLayout::new(Groups).unwrap(); + let base = record_partition_base(&settings, &layout).unwrap(); + pinned_store( + prepare(), + layout.clone(), + base.clone(), + Some(&identity.pinned), + ) + .unwrap(); + let mut recreated = identity.pinned; + recreated.table_id = Some("recreated-table".to_owned()); + assert_eq!( + pinned_store(prepare(), layout, base, Some(&recreated)) + .map(|_store| ()) + .unwrap_err(), + PreparationError::PinnedIdentityMismatch + ); +} + +/// The portable JSON 1.0 transport against the same loopback service, through a real +/// `HttpClient`. Rows written by one transport are read by the other. +#[cfg(feature = "dynamodb-records-portable")] +mod portable { + use super::*; + use crate::portable_dynamodb::PreparedDynamoDbRecords; + use crate::settings::{ + DynamoDbKvLimitsInput, DynamoDbPinnedIdentity, DynamoDbRecordsSettings, SecretsReference, + }; + use edgezero_adapter_axum::outbound::AxumOutboundClient; + use edgezero_adapter_axum::outbound_executor::AxumOutboundExecutor; + use edgezero_core::config_store::BoundedStoreRead; + use edgezero_core::outbound::HttpClient; + use edgezero_core::secret_store::{ + InMemorySecretStore, SecretError, SecretHandle, SecretStore, + }; + use edgezero_core::store_registry::BoundSecretStore; + use edgezero_core::time::Deadline; + use std::sync::atomic::AtomicUsize; + + struct Counting { + inner: InMemorySecretStore, + reads: Arc, + } + + #[async_trait::async_trait(?Send)] + impl SecretStore for Counting { + async fn get_bytes( + &self, + store_name: &str, + key: &str, + ) -> Result, SecretError> { + self.reads.fetch_add(1, Ordering::SeqCst); + self.inner.get_bytes(store_name, key).await + } + + 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> { + self.reads.fetch_add(1, Ordering::SeqCst); + self.inner + .get_bytes_bounded( + store_name, + key, + clock, + deadline, + max_backend_bytes, + max_value_bytes, + ) + .await + } + } + + fn binding(fixture: &Fixture) -> DynamoDbRecordsSettings { + DynamoDbRecordsSettings { + credentials: Some(SecretsReference { + secrets: "stores".to_owned(), + }), + endpoint: Some(format!("http://{}", fixture.address)), + limits: DynamoDbKvLimitsInput::default(), + namespace: "records-wire".to_owned(), + pinned: Some(DynamoDbPinnedIdentity { + table_arn: "arn:aws:dynamodb:us-east-1:111111111111:table/fixture-kv".to_owned(), + table_id: Some("fixture-table-id".to_owned()), + }), + region: "us-east-1".to_owned(), + table: "fixture-kv".to_owned(), + } + } + + fn secrets(session: bool) -> (BoundSecretStore, Arc) { + let mut entries = vec![ + ("stores/KV__IDENTITY__AWS_ACCESS_KEY_ID", "AKIDFIXTURE"), + ( + "stores/KV__IDENTITY__AWS_SECRET_ACCESS_KEY", + "fixture-secret", + ), + ]; + if session { + entries.push(("stores/KV__IDENTITY__AWS_SESSION_TOKEN", "fixture-session")); + } + let reads = Arc::new(AtomicUsize::new(0)); + let store = Counting { + inner: InMemorySecretStore::new(entries), + reads: Arc::clone(&reads), + }; + ( + BoundSecretStore::new(SecretHandle::new(Arc::new(store)), "stores".to_owned()), + reads, + ) + } + + fn prepared(fixture: &Fixture, session: bool) -> (PreparedDynamoDbRecords, Arc) { + let (store, reads) = secrets(session); + let layout = RecordLayout::new(Groups).unwrap(); + ( + PreparedDynamoDbRecords::new("identity", &binding(fixture), &layout, store).unwrap(), + reads, + ) + } + + fn client(executor: &AxumOutboundExecutor) -> HttpClient { + HttpClient::with_client(AxumOutboundClient::try_new(executor.handle()).unwrap()) + } + + #[test] + fn portable_and_native_bindings_share_scope_rows_and_cursors() { + let runtime = runtime(); + let fixture = Fixture::start(); + let native = store(&runtime, &fixture, &settings()); + let (portable, _reads) = prepared(&fixture, false); + let (portable_binding, native_binding) = (portable.record_binding(), &native.binding); + assert_eq!(portable_binding.scope, native_binding.scope); + assert_eq!(portable_binding.format, native_binding.format); + assert_eq!( + portable_binding.max_metadata_bytes, + DynamoDbKvLimits::PORTABLE.max_value_bytes + ); + let mut executor = AxumOutboundExecutor::new(); + let http = client(&executor); + runtime.block_on(executor.run_until(async { + let portable_kv = KvHandle::new(Arc::new(portable.bind(http.clone()))); + let native_kv = KvHandle::new(Arc::new(native)); + let portable_records = portable_kv.require_records().unwrap(); + let native_records = native_kv.require_records().unwrap(); + // Native writes, portable reads, and portable CAS against the native generation. + assert_eq!( + native_records + .insert("a/one", write(b"native", RecordWriteMode::Add)) + .await + .unwrap(), + RecordWriteOutcome::Written + ); + let read = portable_records.lookup("a/one").await.unwrap().unwrap(); + assert_eq!(read.body.as_ref(), b"native"); + assert_eq!(read.metadata.as_deref(), Some("m\u{e9}tadata")); + assert_eq!( + portable_records + .insert( + "a/one", + write( + b"portable", + RecordWriteMode::IfGenerationMatch(read.generation) + ) + ) + .await + .unwrap(), + RecordWriteOutcome::Written + ); + assert_eq!( + portable_records + .insert( + "a/one", + write( + b"stale", + RecordWriteMode::IfGenerationMatch(read.generation) + ) + ) + .await + .unwrap(), + RecordWriteOutcome::PreconditionFailed + ); + // Portable writes, native reads. + assert_eq!( + native_records + .lookup("a/one") + .await + .unwrap() + .unwrap() + .body + .as_ref(), + b"portable" + ); + portable_records + .insert("a/two", write(b"two", RecordWriteMode::Add)) + .await + .unwrap(); + // A cursor from one transport continues on the other, both ways. + let partition = native_records.partition("a/").unwrap(); + let first = native_records + .list_partition(&partition, None, 1) + .await + .unwrap(); + let rest = portable_records + .list_partition(&partition, first.cursor.as_deref(), 1000) + .await + .unwrap(); + let mut keys: Vec<_> = first.keys.into_iter().chain(rest.keys).collect(); + keys.sort(); + assert_eq!(keys, ["a/one", "a/two"]); + let scan = portable_kv.list_keys_page("a/", None, 1).await.unwrap(); + native_kv + .list_keys_page("a/", scan.cursor.as_deref(), 1000) + .await + .unwrap(); + portable_records.delete("a/one").await.unwrap(); + assert!(!native_records.exists_strong("a/one").await.unwrap()); + })); + } + + #[test] + fn shared_public_record_contract_uses_the_portable_wire() { + let runtime = runtime(); + let fixture = Fixture::start(); + let (portable, _reads) = prepared(&fixture, false); + let mut executor = AxumOutboundExecutor::new(); + let http = client(&executor); + runtime.block_on(executor.run_until(async { + let kv = KvHandle::new(Arc::new(portable.bind(http))); + contract::assert_record_contract(&kv, "group/").await; + })); + let targets: BTreeSet<_> = fixture + .requests() + .into_iter() + .map(|(target, _)| target) + .collect(); + assert!(!targets.contains("DescribeTable")); + } + + #[test] + fn credentials_are_read_on_first_use_once_per_bound_store() { + let runtime = runtime(); + let fixture = Fixture::start(); + let (portable, reads) = prepared(&fixture, true); + let mut executor = AxumOutboundExecutor::new(); + let http = client(&executor); + runtime.block_on(executor.run_until(async { + let first = KvHandle::new(Arc::new(portable.bind(http.clone()))); + // Binding and capability acquisition perform no secret reads or I/O. + first.require_records().unwrap(); + assert_eq!(reads.load(Ordering::SeqCst), 0); + assert!(fixture.requests().is_empty()); + first.get_bytes("a/missing").await.unwrap(); + first.get_bytes("a/missing").await.unwrap(); + // Access key, secret key and optional session token, once. + assert_eq!(reads.load(Ordering::SeqCst), 3); + let second = KvHandle::new(Arc::new(portable.bind(http))); + second.get_bytes("a/missing").await.unwrap(); + assert_eq!(reads.load(Ordering::SeqCst), 6); + })); + } + + #[test] + fn missing_credentials_never_dispatch() { + let runtime = runtime(); + let fixture = Fixture::start(); + let layout = RecordLayout::new(Groups).unwrap(); + let empty = BoundSecretStore::new( + SecretHandle::new(Arc::new(InMemorySecretStore::new( + Vec::<(String, Bytes)>::new(), + ))), + "stores".to_owned(), + ); + let portable = + PreparedDynamoDbRecords::new("identity", &binding(&fixture), &layout, empty).unwrap(); + let mut executor = AxumOutboundExecutor::new(); + let http = client(&executor); + runtime.block_on(executor.run_until(async { + let kv = KvHandle::new(Arc::new(portable.bind(http))); + assert!(matches!( + kv.put_bytes("a/key", Bytes::from_static(b"v")).await, + Err(KvError::Unavailable) + )); + })); + assert!(fixture.requests().is_empty()); + } + + #[test] + fn mutation_failures_use_the_native_classifier_without_retry() { + for (status, code, mode, expected) in [ + ( + 500, + "InternalServerError", + RecordWriteMode::Overwrite, + Err(KvError::MutationUncertain), + ), + ( + 400, + "ValidationException", + RecordWriteMode::Overwrite, + Err(KvError::Unavailable), + ), + ( + 400, + "ConditionalCheckFailedException", + RecordWriteMode::Add, + Ok(RecordWriteOutcome::PreconditionFailed), + ), + ] { + let runtime = runtime(); + let fixture = Fixture::start(); + let (portable, _reads) = prepared(&fixture, false); + fixture.fail("PutItem", false, status, code); + let mut executor = AxumOutboundExecutor::new(); + let http = client(&executor); + let outcome = runtime.block_on(executor.run_until(async { + let kv = KvHandle::new(Arc::new(portable.bind(http))); + kv.require_records() + .unwrap() + .insert("a/key", write(b"v", mode)) + .await + })); + assert_eq!( + outcome.map_err(|error| error.to_string()), + expected.map_err(|error: KvError| error.to_string()) + ); + let puts = fixture + .requests() + .into_iter() + .filter(|(target, _)| target == "PutItem") + .count(); + assert_eq!(puts, 1, "no retry for {code}"); + } + } + + #[test] + fn one_portable_deadline_bounds_allocation_before_value_dispatch() { + let runtime = runtime(); + let fixture = Fixture::start(); + let (portable, _reads) = prepared(&fixture, false); + // The portable default deadline is 1,000 ms for both insert calls together. + fixture.state.lock().unwrap().allocation_delay = Some(Duration::from_millis(1_200)); + let mut executor = AxumOutboundExecutor::new(); + let http = client(&executor); + let outcome = runtime.block_on(executor.run_until(async { + let kv = KvHandle::new(Arc::new(portable.bind(http))); + kv.require_records() + .unwrap() + .insert("a/budget", write(b"body", RecordWriteMode::Add)) + .await + })); + assert!(matches!(outcome, Err(KvError::Unavailable))); + assert_eq!(fixture.requests().len(), 1); + } +} diff --git a/crates/edgezero-store-aws/src/lib.rs b/crates/edgezero-store-aws/src/lib.rs index c4df04a63..0519c3d94 100644 --- a/crates/edgezero-store-aws/src/lib.rs +++ b/crates/edgezero-store-aws/src/lib.rs @@ -39,6 +39,8 @@ mod appconfig_tests; #[cfg(all(not(target_arch = "wasm32"), feature = "dynamodb-kv"))] mod dynamodb_kv; +#[cfg(feature = "dynamodb-records-portable")] +pub mod portable_dynamodb; #[cfg(all( not(target_arch = "wasm32"), any( @@ -48,6 +50,11 @@ mod dynamodb_kv; ) ))] mod preparation; +#[cfg(any( + all(not(target_arch = "wasm32"), feature = "dynamodb-records"), + feature = "dynamodb-records-portable" +))] +mod records_core; #[cfg(all(not(target_arch = "wasm32"), feature = "secrets-manager"))] mod secrets_manager; #[cfg(test)] @@ -88,6 +95,8 @@ pub enum PreparationError { Malformed, #[error("missing resource or version")] Missing, + #[error("pinned identity mismatch")] + PinnedIdentityMismatch, #[error("size limit")] SizeLimit, #[error("throttled")] diff --git a/crates/edgezero-store-aws/src/portable_dynamodb.rs b/crates/edgezero-store-aws/src/portable_dynamodb.rs new file mode 100644 index 000000000..8fd940f87 --- /dev/null +++ b/crates/edgezero-store-aws/src/portable_dynamodb.rs @@ -0,0 +1,470 @@ +//! Portable `DynamoDB` record provider over `EdgeZero` outbound HTTP. +//! +//! Requests use the `DynamoDB` JSON 1.0 protocol and are signed with `SigV4` from +//! credentials in a logical secrets store. There is no AWS SDK, credential chain, +//! endpoint discovery or retry. Rows, cursors and outcomes are the native record format. + +#![expect( + clippy::arbitrary_source_item_ordering, + reason = "keep the prepared state, its request-local transport and the wire codec in lifecycle order" +)] + +use std::fmt; +use std::str; +use std::sync::Arc; +use std::time::{Duration, UNIX_EPOCH as StdEpoch}; + +use async_trait::async_trait; +use aws_credential_types::Credentials; +use aws_sigv4::http_request::{SignableBody, SignableRequest, SigningSettings, sign}; +use aws_sigv4::sign::v4; +use base64::Engine as _; +use base64::engine::general_purpose::STANDARD; +use edgezero_core::error::EdgeError; +use edgezero_core::error_detail::ProviderFailurePhase; +use edgezero_core::http::header::{ACCEPT_ENCODING, CONTENT_TYPE}; +use edgezero_core::http::{HeaderName, HeaderValue, Method, StatusCode, Uri}; +use edgezero_core::key_value_store::KvStore; +use edgezero_core::outbound::{HttpClient, OutboundRequest, ResponseDecoding}; +use edgezero_core::record_store::{RecordBinding, RecordLayout}; +use edgezero_core::store_registry::BoundSecretStore; +use edgezero_core::time::Deadline; +use futures_util::lock::Mutex; +use serde_json::{Map, Value}; +use web_time::{SystemTime, UNIX_EPOCH}; + +use crate::PreparationError; +use crate::records_core::{ + Attr, Item, Operation, RecordCore, RecordScope, RecordTransport, Request, Response, + TransportError, record_binding, record_partition_base, +}; +use crate::settings::{DynamoDbCredentialKeys, DynamoDbKvLimits, DynamoDbRecordsSettings}; + +const CONTENT: &str = "application/x-amz-json-1.0"; +/// A Query or Scan page reads at most 1 MB; JSON and base64 roughly double it. +const MAX_RESPONSE_BYTES: u64 = 0x0040_0000; +const MAX_ERROR_BYTES: u64 = 0x1_0000; + +struct Shared { + endpoint: Uri, + keys: DynamoDbCredentialKeys, + limits: DynamoDbKvLimits, + region: String, + secrets: BoundSecretStore, + table: String, +} + +/// Validated settings, pinned identity and secrets reference for one KV ID. +/// +/// Building it performs no I/O and reads no secret. It is `Send + Sync` and is +/// kept for the life of the application; [`Self::bind`] is cheap and per request. +pub struct PreparedDynamoDbRecords { + binding: RecordBinding, + partition_base: String, + shared: Arc, +} + +impl fmt::Debug for PreparedDynamoDbRecords { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("PreparedDynamoDbRecords") + .finish_non_exhaustive() + } +} + +impl PreparedDynamoDbRecords { + /// Builds the record binding from configuration alone. + /// + /// `secrets` must be the bound logical store named by the binding's `credentials`. + /// + /// # Errors + /// Rejects a binding without `pinned` or `credentials`, invalid settings or + /// endpoint, and a KV ID outside `[a-z0-9_]`. + #[inline] + pub fn new( + kv_id: &str, + settings: &DynamoDbRecordsSettings, + layout: &RecordLayout, + secrets: BoundSecretStore, + ) -> Result { + if !valid_portable_id(kv_id) { + return Err(PreparationError::InvalidBinding); + } + settings.validate(DynamoDbKvLimits::PORTABLE)?; + let pinned = settings + .pinned + .as_ref() + .ok_or(PreparationError::InvalidBinding)?; + if settings.credentials.is_none() { + return Err(PreparationError::InvalidBinding); + } + let address = settings.kv_settings(DynamoDbKvLimits::PORTABLE); + let endpoint = settings.portable_endpoint()?; + let binding = record_binding( + address.limits, + layout.clone(), + &RecordScope { + endpoint: &endpoint, + namespace: &address.namespace, + region: &address.region, + table: &address.table, + table_arn: &pinned.table_arn, + table_id: pinned.table_id.as_deref(), + }, + )?; + Ok(Self { + binding, + partition_base: record_partition_base(&address, layout)?, + shared: Arc::new(Shared { + endpoint: endpoint + .parse() + .map_err(|_error| PreparationError::InvalidEndpoint)?, + keys: DynamoDbCredentialKeys::for_kv_id(kv_id), + limits: address.limits, + region: address.region, + secrets, + table: address.table, + }), + }) + } + + /// The configured record binding. No I/O. + #[inline] + #[must_use] + pub const fn record_binding(&self) -> &RecordBinding { + &self.binding + } + + /// A request-bound store over `client`. Credentials are read on its first + /// operation and reused only by this store. + #[inline] + #[must_use] + pub fn bind(&self, client: HttpClient) -> impl KvStore + use<> { + let clock = client.time().clock().clone(); + RecordCore { + binding: self.binding.clone(), + clock, + limits: self.shared.limits, + partition_base: self.partition_base.clone(), + transport: PortableTransport { + client, + credentials: Mutex::new(None), + shared: Arc::clone(&self.shared), + }, + } + } +} + +/// One request's transport. The credential cache lives and dies with it. +struct PortableTransport { + client: HttpClient, + credentials: Mutex>, + shared: Arc, +} + +impl PortableTransport { + async fn credentials(&self) -> Result { + let mut cached = self.credentials.lock().await; + if let Some(credentials) = cached.as_ref() { + return Ok(credentials.clone()); + } + let keys = &self.shared.keys; + let access = self.secret(&keys.access_key_id).await?; + let secret = self.secret(&keys.secret_access_key).await?; + let session = self + .shared + .secrets + .get_bytes(&keys.session_token) + .await + .map_err(|_error| TransportError::NotDispatched)? + .map(|bytes| secret_text(&bytes)) + .transpose()?; + let credentials = Credentials::new(access, secret, session, None, "edgezero-secrets"); + *cached = Some(credentials.clone()); + Ok(credentials) + } + + async fn secret(&self, key: &str) -> Result { + let bytes = self + .shared + .secrets + .require_bytes(key) + .await + .map_err(|_error| TransportError::NotDispatched)?; + secret_text(&bytes) + } + + fn signed_request( + &self, + operation: Operation, + body: Vec, + credentials: Credentials, + deadline: Deadline, + ) -> Result { + let target = format!("DynamoDB_20120810.{}", operation.target()); + let uri = self.shared.endpoint.to_string(); + let identity = credentials.into(); + let since_epoch = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_err(|_error| TransportError::NotDispatched)?; + let params = v4::SigningParams::builder() + .identity(&identity) + .region(&self.shared.region) + .name("dynamodb") + .time( + StdEpoch + .checked_add(since_epoch) + .ok_or(TransportError::NotDispatched)?, + ) + .settings(SigningSettings::default()) + .build() + .map_err(|_error| TransportError::NotDispatched)? + .into(); + let signable = SignableRequest::new( + "POST", + &uri, + [("content-type", CONTENT), ("x-amz-target", target.as_str())].into_iter(), + SignableBody::Bytes(&body), + ) + .map_err(|_error| TransportError::NotDispatched)?; + let (instructions, _signature) = sign(signable, ¶ms) + .map_err(|_error| TransportError::NotDispatched)? + .into_parts(); + let mut request = OutboundRequest::new(Method::POST, self.shared.endpoint.clone()) + .map_err(|_error| TransportError::NotDispatched)? + .body(body) + .deadline(deadline) + .connect_timeout(Duration::from_millis(self.shared.limits.connect_timeout_ms)) + .response_decoding(ResponseDecoding::Original) + .max_response_bytes(MAX_RESPONSE_BYTES); + let headers = request.headers_mut(); + headers.insert(CONTENT_TYPE, HeaderValue::from_static(CONTENT)); + headers.insert(ACCEPT_ENCODING, HeaderValue::from_static("identity")); + headers.insert( + HeaderName::from_static("x-amz-target"), + HeaderValue::from_str(&target).map_err(|_error| TransportError::NotDispatched)?, + ); + for (name, value) in instructions.headers() { + let mut header = + HeaderValue::from_str(value).map_err(|_error| TransportError::NotDispatched)?; + header.set_sensitive(true); + headers.insert( + HeaderName::from_bytes(name.as_bytes()) + .map_err(|_error| TransportError::NotDispatched)?, + header, + ); + } + Ok(request) + } +} + +#[async_trait(?Send)] +impl RecordTransport for PortableTransport { + async fn call( + &self, + operation: Operation, + request: Request, + deadline: Deadline, + ) -> Result { + let credentials = self.credentials().await?; + let body = serde_json::to_vec(&encode_request(&self.shared.table, request)) + .map_err(|_error| TransportError::NotDispatched)?; + let outbound = self.signed_request(operation, body, credentials, deadline)?; + let response = self + .client + .send(outbound) + .await + .map_err(|error| send_error(&error))?; + let status = response.status(); + if status == StatusCode::OK { + let bytes = response + .into_bytes_bounded_until(MAX_RESPONSE_BYTES, deadline) + .await + .map_err(|_error| TransportError::Uncertain)?; + return decode_response(&bytes).ok_or(TransportError::Uncertain); + } + let definitive = status.is_client_error(); + let conditional = response + .into_bytes_bounded_until(MAX_ERROR_BYTES, deadline) + .await + .is_ok_and(|bytes| is_conditional_failure(&bytes)); + Err(TransportError::Service { + conditional, + definitive, + }) + } +} + +/// Facade validation and pre-dispatch adapter phases never reached the network. +fn send_error(error: &EdgeError) -> TransportError { + if matches!( + error, + EdgeError::Validation { .. } | EdgeError::BadRequest { .. } + ) || error.provider_failure_detail().is_some_and(|detail| { + matches!( + detail.phase(), + ProviderFailurePhase::BackendRegistration | ProviderFailurePhase::RequestPreparation + ) + }) { + TransportError::NotDispatched + } else { + TransportError::Uncertain + } +} + +fn secret_text(bytes: &[u8]) -> Result { + str::from_utf8(bytes) + .ok() + .map(str::trim) + .filter(|text| !text.is_empty() && text.bytes().all(|byte| byte.is_ascii_graphic())) + .map(str::to_owned) + .ok_or(TransportError::NotDispatched) +} + +/// Lowercase ASCII, digits and underscore, so uppercased key names cannot collide. +pub(crate) fn valid_portable_id(id: &str) -> bool { + !id.is_empty() + && id + .bytes() + .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_') +} + +fn is_conditional_failure(bytes: &[u8]) -> bool { + serde_json::from_slice::(bytes) + .ok() + .and_then(|value| value.get("__type")?.as_str().map(str::to_owned)) + .is_some_and(|kind| kind.rsplit('#').next() == Some("ConditionalCheckFailedException")) +} + +fn encode_request(table: &str, request: Request) -> Value { + let mut body = Map::new(); + body.insert("TableName".to_owned(), Value::from(table)); + let mut text = |name: &str, value: Option<&'static str>| { + if let Some(expression) = value { + body.insert(name.to_owned(), Value::from(expression)); + } + }; + text("UpdateExpression", request.update_expression); + text("ConditionExpression", request.condition_expression); + text("KeyConditionExpression", request.key_condition_expression); + text("FilterExpression", request.filter_expression); + text("ProjectionExpression", request.projection_expression); + if let Some(key) = request.key { + body.insert("Key".to_owned(), encode_item(key)); + } + if let Some(item) = request.item { + body.insert("Item".to_owned(), encode_item(item)); + } + if let Some(start) = request.exclusive_start_key { + body.insert("ExclusiveStartKey".to_owned(), encode_item(start)); + } + if let Some(consistent) = request.consistent_read { + body.insert("ConsistentRead".to_owned(), Value::from(consistent)); + } + if let Some(forward) = request.scan_index_forward { + body.insert("ScanIndexForward".to_owned(), Value::from(forward)); + } + if let Some(limit) = request.limit { + body.insert("Limit".to_owned(), Value::from(limit)); + } + if request.return_updated_new { + body.insert("ReturnValues".to_owned(), Value::from("UPDATED_NEW")); + } + if !request.names.is_empty() { + body.insert( + "ExpressionAttributeNames".to_owned(), + Value::Object( + request + .names + .into_iter() + .map(|(alias, name)| (alias, Value::from(name))) + .collect(), + ), + ); + } + if !request.values.is_empty() { + body.insert( + "ExpressionAttributeValues".to_owned(), + encode_item(request.values), + ); + } + Value::Object(body) +} + +fn encode_item(item: Item) -> Value { + Value::Object( + item.into_iter() + .map(|(name, value)| (name, encode_value(value))) + .collect(), + ) +} + +fn encode_value(value: Attr) -> Value { + let (kind, encoded) = match value { + Attr::Binary(bytes) => ("B", STANDARD.encode(bytes)), + Attr::Number(number) => ("N", number), + Attr::Text(text) => ("S", text), + // The core never sends an opaque value. NULL is the inert placeholder if it did. + Attr::Other => return serde_json::json!({ "NULL": true }), + }; + let mut object = Map::new(); + object.insert(kind.to_owned(), Value::from(encoded)); + Value::Object(object) +} + +fn decode_response(bytes: &[u8]) -> Option { + let Value::Object(mut body) = serde_json::from_slice::(bytes).ok()? else { + return None; + }; + // `None` is malformed; `Some(None)` is an absent field. + let item = |fields: &mut Map, name: &str| match fields.remove(name) { + None => Some(None), + Some(value) => decode_item(value).map(Some), + }; + let items = match body.remove("Items") { + None => Vec::new(), + Some(Value::Array(values)) => values + .into_iter() + .map(decode_item) + .collect::>>()?, + Some(_) => return None, + }; + Some(Response { + attributes: item(&mut body, "Attributes")?, + item: item(&mut body, "Item")?, + items, + last_evaluated_key: item(&mut body, "LastEvaluatedKey")?, + }) +} + +fn decode_item(value: Value) -> Option { + let Value::Object(object) = value else { + return None; + }; + object + .into_iter() + .map(|(name, attribute)| Some((name, decode_value(attribute)?))) + .collect() +} + +fn decode_value(value: Value) -> Option { + let Value::Object(object) = value else { + return None; + }; + let mut entries = object.into_iter(); + let (kind, encoded) = entries.next()?; + if entries.next().is_some() { + return None; + } + Some(match (kind.as_str(), encoded) { + ("B", Value::String(text)) => Attr::Binary(STANDARD.decode(text).ok()?), + ("N", Value::String(text)) => Attr::Number(text), + ("S", Value::String(text)) => Attr::Text(text), + ("B" | "N" | "S", _) => return None, + _ => Attr::Other, + }) +} + +#[cfg(test)] +#[path = "portable_dynamodb_tests.rs"] +mod tests; diff --git a/crates/edgezero-store-aws/src/portable_dynamodb_tests.rs b/crates/edgezero-store-aws/src/portable_dynamodb_tests.rs new file mode 100644 index 000000000..9bb0a3b42 --- /dev/null +++ b/crates/edgezero-store-aws/src/portable_dynamodb_tests.rs @@ -0,0 +1,246 @@ +//! Wire codec, signing and classification checks. Real-transport proof lives in the +//! loopback interop tests and the `DynamoDB` Local runner. + +use super::*; +use edgezero_core::key_value_store::KvError; +use edgezero_core::record_store::RecordKeyLayout; +use edgezero_core::secret_store::{InMemorySecretStore, SecretHandle}; +use serde_json::json; + +struct Groups; + +impl RecordKeyLayout for Groups { + fn id(&self) -> &'static str { + "wire-groups" + } + fn version(&self) -> u32 { + 1 + } + fn validate(&self) -> Result<(), KvError> { + Ok(()) + } + fn partition_prefix<'key>(&self, key: &'key str) -> Result<&'key str, KvError> { + let end = key + .find('/') + .ok_or_else(|| KvError::Validation("missing group".to_owned()))?; + key.get(..=end) + .ok_or_else(|| KvError::Validation("missing group".to_owned())) + } + fn validate_partition(&self, prefix: &str) -> Result<(), KvError> { + if prefix.ends_with('/') && prefix.matches('/').count() == 1 { + Ok(()) + } else { + Err(KvError::Validation("invalid group".to_owned())) + } + } +} + +fn settings() -> DynamoDbRecordsSettings { + toml::from_str( + "region = 'us-east-1'\ntable = 'fixture-kv'\nnamespace = 'records-wire'\n\ + pinned = { table_arn = 'arn:aws:dynamodb:us-east-1:111111111111:table/fixture-kv', table_id = 'fixture-table-id' }\n\ + credentials = { secrets = 'stores' }", + ) + .unwrap() +} + +fn secrets() -> BoundSecretStore { + BoundSecretStore::new( + SecretHandle::new(Arc::new(InMemorySecretStore::new([( + "KV__IDENTITY__AWS_ACCESS_KEY_ID", + "AKIDFIXTURE", + )]))), + "stores".to_owned(), + ) +} + +#[test] +fn credential_keys_are_namespaced_by_the_kv_id() { + assert_eq!( + DynamoDbCredentialKeys::for_kv_id("identity"), + DynamoDbCredentialKeys { + access_key_id: "KV__IDENTITY__AWS_ACCESS_KEY_ID".to_owned(), + secret_access_key: "KV__IDENTITY__AWS_SECRET_ACCESS_KEY".to_owned(), + session_token: "KV__IDENTITY__AWS_SESSION_TOKEN".to_owned(), + } + ); +} + +#[test] +fn preparation_needs_pins_credentials_and_a_lowercase_id_without_io() { + let layout = RecordLayout::new(Groups).unwrap(); + let prepared = + PreparedDynamoDbRecords::new("identity", &settings(), &layout, secrets()).unwrap(); + assert_eq!( + prepared.record_binding().max_metadata_bytes, + DynamoDbKvLimits::PORTABLE.max_value_bytes + ); + // The scope is the tuple native preparation binds, with the regional endpoint. + assert_eq!( + prepared.record_binding().scope, + json!([ + "https://dynamodb.us-east-1.amazonaws.com/", + "arn:aws:dynamodb:us-east-1:111111111111:table/fixture-kv", + "fixture-table-id", + "us-east-1", + "fixture-kv", + "records-wire" + ]) + .to_string() + ); + for id in ["Identity", "", "id-entity"] { + assert_eq!( + PreparedDynamoDbRecords::new(id, &settings(), &layout, secrets()).unwrap_err(), + PreparationError::InvalidBinding + ); + } + let mut unpinned = settings(); + unpinned.pinned = None; + assert_eq!( + PreparedDynamoDbRecords::new("identity", &unpinned, &layout, secrets()).unwrap_err(), + PreparationError::InvalidBinding + ); + let mut uncredentialed = settings(); + uncredentialed.credentials = None; + assert_eq!( + PreparedDynamoDbRecords::new("identity", &uncredentialed, &layout, secrets()).unwrap_err(), + PreparationError::InvalidBinding + ); +} + +#[test] +fn portable_endpoints_require_https_except_on_loopback() { + let with = |endpoint: &str| { + let mut binding = settings(); + binding.endpoint = Some(endpoint.to_owned()); + binding.portable_endpoint() + }; + assert_eq!( + with("http://127.0.0.1:8000").unwrap(), + "http://127.0.0.1:8000/" + ); + assert_eq!(with("http://[::1]:8000/").unwrap(), "http://[::1]:8000/"); + assert_eq!( + with("https://dynamodb.example.net").unwrap(), + "https://dynamodb.example.net/" + ); + for rejected in [ + "http://dynamodb.us-east-1.amazonaws.com", + "http://localhost:8000", + "https://user:secret@dynamodb.example.net", + "https://dynamodb.example.net/base", + "https://dynamodb.example.net/?token=1", + "ftp://dynamodb.example.net", + ] { + assert_eq!( + with(rejected).unwrap_err(), + PreparationError::InvalidEndpoint + ); + } + let mut china = settings(); + china.region = "cn-north-1".to_owned(); + assert_eq!( + china.portable_endpoint().unwrap(), + "https://dynamodb.cn-north-1.amazonaws.com.cn/" + ); +} + +#[test] +fn requests_encode_the_json_protocol_and_omit_empty_maps() { + let request = Request { + key: Some(Item::from([ + ("pk".to_owned(), Attr::Text("p".to_owned())), + ("sk".to_owned(), Attr::Text("r#k".to_owned())), + ])), + consistent_read: Some(true), + ..Request::default() + }; + assert_eq!( + encode_request("fixture-kv", request), + json!({"TableName": "fixture-kv", "Key": {"pk": {"S": "p"}, "sk": {"S": "r#k"}}, "ConsistentRead": true}) + ); + let update = Request { + item: Some(Item::from([ + ("v".to_owned(), Attr::Binary(vec![0, 255])), + ("generation".to_owned(), Attr::Number("7".to_owned())), + ])), + condition_expression: Some("attribute_not_exists(#pk)"), + names: [("#pk".to_owned(), "pk".to_owned())].into(), + return_updated_new: true, + limit: Some(3_i32), + ..Request::default() + }; + assert_eq!( + encode_request("t", update), + json!({ + "TableName": "t", + "Item": {"v": {"B": "AP8="}, "generation": {"N": "7"}}, + "ConditionExpression": "attribute_not_exists(#pk)", + "ExpressionAttributeNames": {"#pk": "pk"}, + "ReturnValues": "UPDATED_NEW", + "Limit": 3_i32 + }) + ); +} + +#[test] +fn responses_decode_scalars_and_keep_other_types_opaque() { + let decoded = decode_response( + br#"{"Items":[{"pk":{"S":"p"},"v":{"B":"AP8="},"n":{"N":"1"},"m":{"M":{}}}], + "LastEvaluatedKey":{"pk":{"S":"p"},"sk":{"S":"s"}},"Count":1,"ScannedCount":4}"#, + ) + .unwrap(); + assert_eq!(decoded.items.len(), 1); + assert_eq!(decoded.items[0]["v"], Attr::Binary(vec![0, 255])); + assert_eq!(decoded.items[0]["n"], Attr::Number("1".to_owned())); + assert_eq!(decoded.items[0]["m"], Attr::Other); + assert_eq!( + decoded.last_evaluated_key.unwrap()["sk"], + Attr::Text("s".to_owned()) + ); + assert!(decode_response(b"{}").unwrap().item.is_none()); + for malformed in [ + b"[]".as_slice(), + br#"{"Item":{"v":{"B":"not base64!"}}}"#, + br#"{"Item":{"v":{"S":1}}}"#, + br#"{"Item":{"v":{"S":"a","N":"1"}}}"#, + br#"{"Items":{}}"#, + b"not json", + ] { + assert!(decode_response(malformed).is_none()); + } +} + +#[test] +fn only_conditional_check_failures_are_conditional() { + for body in [ + br#"{"__type":"com.amazonaws.dynamodb.v20120810#ConditionalCheckFailedException"}"# + .as_slice(), + br#"{"__type":"ConditionalCheckFailedException","message":"x"}"#, + ] { + assert!(is_conditional_failure(body)); + } + for body in [ + br#"{"__type":"com.amazonaws.dynamodb.v20120810#ValidationException"}"#.as_slice(), + br#"{"message":"ConditionalCheckFailedException"}"#, + b"", + ] { + assert!(!is_conditional_failure(body)); + } +} + +#[test] +fn facade_rejections_never_reach_the_network() { + assert_eq!( + send_error(&EdgeError::validation("rejected before dispatch")), + TransportError::NotDispatched + ); + assert_eq!( + send_error(&EdgeError::bad_gateway("reset after dispatch")), + TransportError::Uncertain + ); + assert_eq!( + send_error(&EdgeError::gateway_timeout("late")), + TransportError::Uncertain + ); +} diff --git a/crates/edgezero-store-aws/src/preparation.rs b/crates/edgezero-store-aws/src/preparation.rs index 6c2facf61..49409d9dc 100644 --- a/crates/edgezero-store-aws/src/preparation.rs +++ b/crates/edgezero-store-aws/src/preparation.rs @@ -57,7 +57,8 @@ pub struct AwsPreparation { pub(crate) clock: MonotonicClock, pub(crate) deadline: Deadline, #[cfg(feature = "dynamodb-kv")] - pub(crate) dynamodb_clients: HashMap<(String, DynamoDbKvLimits), DynamoDbClient>, + pub(crate) dynamodb_clients: + HashMap<(String, DynamoDbKvLimits, Option), DynamoDbClient>, pub(crate) limits: AwsPreparationLimits, #[cfg(feature = "secrets-manager")] pub(crate) secret_cache: HashMap, diff --git a/crates/edgezero-store-aws/src/records_core.rs b/crates/edgezero-store-aws/src/records_core.rs new file mode 100644 index 000000000..28c45fca3 --- /dev/null +++ b/crates/edgezero-store-aws/src/records_core.rs @@ -0,0 +1,944 @@ +//! Transport-independent `DynamoDB` record format shared by native and portable transports. +//! +//! The core owns partition and sort keys, retained allocator items, cursor encoding, size and +//! value-kind checks, deadlines and the error classifier. A transport only performs one +//! single-attempt operation and reports where a failure happened. + +#![expect( + clippy::arbitrary_source_item_ordering, + reason = "keep the wire model, transport boundary, record core and validators grouped" +)] + +use std::collections::BTreeMap; +use std::time::Duration; + +use async_trait::async_trait; +use bytes::Bytes; +use edgezero_core::key_value_store::{KvError, KvPage, KvStore}; +use edgezero_core::record_store::{ + Record, RecordBinding, RecordGeneration, RecordLayout, RecordPage, RecordPartition, + RecordWrite, RecordWriteMode, RecordWriteOutcome, +}; +use edgezero_core::time::{Deadline, MonotonicClock}; +use serde::{Deserialize, Serialize}; +use web_time::{SystemTime, UNIX_EPOCH}; + +use crate::PreparationError; +use crate::settings::{DynamoDbKvLimits, DynamoDbKvSettings}; + +pub(crate) const FORMAT: &str = "edgezero-dynamodb-records-v1"; +pub(crate) const MAX_CURSOR_BYTES: usize = 0x4000; +pub(crate) const MAX_ITEM_BYTES: usize = 409_600; +pub(crate) const MAX_KEY_BYTES: usize = 512; +pub(crate) const MAX_PAGE_KEYS: usize = 1_000; +const MAX_PARTITION_BYTES: usize = 2_048; + +/// The scalar attribute shapes used by the record format. Other shapes are opaque. +#[derive(Clone, Debug, Eq, PartialEq)] +pub(crate) enum Attr { + Binary(Vec), + Number(String), + /// Any other `DynamoDB` attribute type. It never matches an expected value. + Other, + Text(String), +} + +impl Attr { + pub(crate) fn as_n(&self) -> Result<&str, KvError> { + match self { + Self::Number(number) => Ok(number), + Self::Binary(_) | Self::Other | Self::Text(_) => Err(KvError::Unavailable), + } + } + + pub(crate) fn as_s(&self) -> Result<&str, KvError> { + match self { + Self::Text(text) => Ok(text), + Self::Binary(_) | Self::Number(_) | Self::Other => Err(KvError::Unavailable), + } + } +} + +pub(crate) type Item = BTreeMap; + +/// The six operations the record format uses. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub(crate) enum Operation { + DeleteItem, + GetItem, + PutItem, + Query, + Scan, + UpdateItem, +} + +#[cfg(feature = "dynamodb-records-portable")] +impl Operation { + pub(crate) const fn target(self) -> &'static str { + match self { + Self::DeleteItem => "DeleteItem", + Self::GetItem => "GetItem", + Self::PutItem => "PutItem", + Self::Query => "Query", + Self::Scan => "Scan", + Self::UpdateItem => "UpdateItem", + } + } +} + +/// One operation's inputs. Empty maps and `None` fields are omitted from the wire request. +#[derive(Clone, Debug, Default)] +pub(crate) struct Request { + pub condition_expression: Option<&'static str>, + pub consistent_read: Option, + pub exclusive_start_key: Option, + pub filter_expression: Option<&'static str>, + pub item: Option, + pub key: Option, + pub key_condition_expression: Option<&'static str>, + pub limit: Option, + pub names: BTreeMap, + pub projection_expression: Option<&'static str>, + pub return_updated_new: bool, + pub scan_index_forward: Option, + pub update_expression: Option<&'static str>, + pub values: Item, +} + +/// One operation's outputs. Absent fields are `None` or empty. +#[derive(Debug, Default)] +pub(crate) struct Response { + pub attributes: Option, + pub item: Option, + pub items: Vec, + pub last_evaluated_key: Option, +} + +/// Where a single-attempt operation failed. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub(crate) enum TransportError { + /// The request was never handed to the network: construction, signing, credentials, + /// backend creation or an exhausted budget. + NotDispatched, + /// The service returned a typed error. `definitive` is a 4xx status. + Service { conditional: bool, definitive: bool }, + /// The request may have reached the service: timeout, reset, 5xx-like or unreadable reply. + Uncertain, +} + +/// One single-attempt `DynamoDB` operation, bounded by `deadline`. No retries. +#[async_trait(?Send)] +pub(crate) trait RecordTransport: Send + Sync { + async fn call( + &self, + operation: Operation, + request: Request, + deadline: Deadline, + ) -> Result; +} + +/// Physical identity bound into every record binding scope and cursor. +#[derive(Clone, Copy, Debug)] +pub(crate) struct RecordScope<'identity> { + pub endpoint: &'identity str, + pub namespace: &'identity str, + pub region: &'identity str, + pub table: &'identity str, + pub table_arn: &'identity str, + pub table_id: Option<&'identity str>, +} + +impl RecordScope<'_> { + /// Encodes the same tuple native preparation has always bound into cursors. + pub(crate) fn encode(&self) -> Result { + if self.table_arn.is_empty() { + return Err(PreparationError::Malformed); + } + serde_json::to_string(&( + self.endpoint, + self.table_arn, + self.table_id, + self.region, + self.table, + self.namespace, + )) + .map_err(|_error| PreparationError::Malformed) + } +} + +/// Builds the record binding a provider reports through `record_binding()`. +pub(crate) fn record_binding( + limits: DynamoDbKvLimits, + layout: RecordLayout, + scope: &RecordScope<'_>, +) -> Result { + Ok(RecordBinding { + layout, + scope: scope.encode()?, + format: FORMAT.to_owned(), + // Metadata may use the full configured payload budget when the + // body is empty. Inserts also enforce their combined byte size. + max_metadata_bytes: limits.max_value_bytes, + }) +} + +#[derive(Deserialize, Serialize)] +#[serde(deny_unknown_fields)] +struct RecordCursor { + format: String, + layout_id: String, + layout_version: u32, + mode: String, + pk: String, + prefix: String, + scope: String, + sk: String, +} + +/// The record format over one transport. All fields are fixed for the provider's lifetime. +pub(crate) struct RecordCore { + pub binding: RecordBinding, + pub clock: MonotonicClock, + pub limits: DynamoDbKvLimits, + pub partition_base: String, + pub transport: T, +} + +#[expect( + clippy::arbitrary_source_item_ordering, + reason = "keep keys, point operations and pagination helpers grouped" +)] +impl RecordCore { + pub(crate) fn runtime_deadline(&self) -> Result { + self.clock + .now() + .checked_add(Duration::from_millis(self.limits.operation_timeout_ms)) + .map(Deadline::at_instant) + .ok_or(KvError::Unavailable) + } + + fn require_remaining(&self, deadline: Deadline) -> Result<(), KvError> { + deadline + .remaining_at(self.clock.now()) + .filter(|remaining| !remaining.is_zero()) + .map(|_remaining| ()) + .ok_or(KvError::Unavailable) + } + + /// A read or allocation. Every failure, including a late reply, is `Unavailable`. + async fn bounded( + &self, + deadline: Deadline, + operation: Operation, + request: Request, + ) -> Result { + self.require_remaining(deadline)?; + let result = self.transport.call(operation, request, deadline).await; + if deadline.is_expired_at(self.clock.now()) { + return Err(KvError::Unavailable); + } + result.map_err(|_error| KvError::Unavailable) + } + + /// A value mutation. A late reply is `MutationUncertain`; the caller classifies errors. + async fn mutate( + &self, + deadline: Deadline, + operation: Operation, + request: Request, + ) -> Result, KvError> { + self.require_remaining(deadline)?; + let result = self.transport.call(operation, request, deadline).await; + if deadline.is_expired_at(self.clock.now()) { + return Err(KvError::MutationUncertain); + } + Ok(result) + } + + pub(crate) fn partition_key(&self, partition: &RecordPartition) -> Result { + if self.binding.layout.partition(partition.prefix())? != *partition { + return Err(invalid_input()); + } + let pk = format!("{}{}", self.partition_base, partition.prefix()); + if pk.len() > MAX_PARTITION_BYTES { + return Err(invalid_input()); + } + Ok(pk) + } + + pub(crate) fn key( + &self, + key: &str, + partition: &RecordPartition, + kind: &str, + ) -> Result { + if self.binding.layout.resolve(key)? != *partition { + return Err(invalid_input()); + } + Ok(physical_key( + self.partition_key(partition)?, + format!("{kind}#{key}"), + )) + } + + async fn allocate( + &self, + key: &str, + partition: &RecordPartition, + deadline: Deadline, + ) -> Result { + // Failure here cannot have changed a value row. An unobserved allocation + // is merely a gap, and is never represented as a successful value write. + let request = Request { + key: Some(self.key(key, partition, "g")?), + update_expression: Some("SET #generation = if_not_exists(#generation, :zero) + :one"), + condition_expression: Some( + "attribute_not_exists(#generation) OR #generation < :ceiling", + ), + names: names(&[("#generation", "generation")]), + values: Item::from([ + (":zero".to_owned(), Attr::Number("0".to_owned())), + (":one".to_owned(), Attr::Number("1".to_owned())), + (":ceiling".to_owned(), Attr::Number(u64::MAX.to_string())), + ]), + return_updated_new: true, + ..Request::default() + }; + let output = self + .bounded(deadline, Operation::UpdateItem, request) + .await?; + let generation = output + .attributes + .as_ref() + .and_then(|attributes| attributes.get("generation")) + .ok_or(KvError::Unavailable) + .and_then(Attr::as_n) + .and_then(read_unsigned)?; + if generation == 0 { + return Err(KvError::Unavailable); + } + Ok(RecordGeneration::from_u64(generation)) + } + + pub(crate) async fn insert( + &self, + key: &str, + partition: &RecordPartition, + write: RecordWrite<'_>, + ) -> Result { + let deadline = self.runtime_deadline()?; + let metadata = write.metadata.filter(|text| !text.is_empty()); + if write + .body + .len() + .checked_add(metadata.map_or(0, str::len)) + .is_none_or(|bytes| bytes > self.limits.max_value_bytes) + { + return Err(invalid_input()); + } + let expiry = write + .ttl + .map(|ttl| { + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_err(|_error| KvError::Unavailable)?; + // Native TTL is in seconds. Rounding up never shortens the requested TTL. + Ok::(expiry_from_duration(now, ttl)?.div_ceil(1_000)) + }) + .transpose()?; + let mut item = self.key(key, partition, "r")?; + item.insert("v".to_owned(), Attr::Binary(write.body.to_vec())); + item.insert("format".to_owned(), Attr::Text(FORMAT.to_owned())); + item.insert("kind".to_owned(), Attr::Text("r".to_owned())); + if let Some(text) = metadata { + item.insert("metadata".to_owned(), Attr::Text(text.to_owned())); + } + if let Some(expires) = expiry { + item.insert("ttl_epoch_s".to_owned(), Attr::Number(expires.to_string())); + } + // Include the maximum generation before allocation so oversized values + // never consume an allocator request. + item.insert("generation".to_owned(), Attr::Number(u64::MAX.to_string())); + validate_record_size(&item)?; + let generation = self.allocate(key, partition, deadline).await?; + item.insert( + "generation".to_owned(), + Attr::Number(generation.as_u64().to_string()), + ); + let mut request = Request { + item: Some(item), + ..Request::default() + }; + match write.mode { + RecordWriteMode::Overwrite => {} + RecordWriteMode::Add => { + request.condition_expression = Some("attribute_not_exists(#pk)"); + request.names = names(&[("#pk", "pk")]); + } + RecordWriteMode::IfGenerationMatch(expected) => { + request.condition_expression = Some("#generation = :expected"); + request.names = names(&[("#generation", "generation")]); + request.values = Item::from([( + ":expected".to_owned(), + Attr::Number(expected.as_u64().to_string()), + )]); + } + } + // Deadline exhaustion after allocation alone remains Unavailable. + match self.mutate(deadline, Operation::PutItem, request).await? { + Ok(_) => Ok(RecordWriteOutcome::Written), + Err(TransportError::Service { + conditional: true, .. + }) if write.mode != RecordWriteMode::Overwrite => { + Ok(RecordWriteOutcome::PreconditionFailed) + } + Err(error) => Err(mutation_error(error)), + } + } + + pub(crate) async fn lookup( + &self, + key: &str, + partition: &RecordPartition, + ) -> Result, KvError> { + let deadline = self.runtime_deadline()?; + let expected = self.key(key, partition, "r")?; + let request = Request { + key: Some(expected.clone()), + consistent_read: Some(true), + ..Request::default() + }; + self.bounded(deadline, Operation::GetItem, request) + .await? + .item + .map(|item| self.record(&expected, item)) + .transpose() + } + + fn record(&self, expected: &Item, mut item: Item) -> Result { + if expected + .iter() + .any(|(name, value)| item.get(name) != Some(value)) + { + return Err(KvError::Unavailable); + } + validate_value_kind(&item)?; + let generation = match item.remove("generation") { + Some(Attr::Number(value)) => RecordGeneration::from_u64(read_unsigned(&value)?), + _ => return Err(KvError::Unavailable), + }; + let metadata = match item.remove("metadata") { + None => None, + Some(Attr::Text(text)) if text.len() <= self.limits.max_value_bytes => { + (!text.is_empty()).then_some(text) + } + _ => return Err(KvError::Unavailable), + }; + let body = match item.remove("v") { + Some(Attr::Binary(body)) if body.len() <= self.limits.max_value_bytes => { + Bytes::from(body) + } + _ => return Err(KvError::Unavailable), + }; + if body + .len() + .checked_add(metadata.as_deref().map_or(0, str::len)) + .is_none_or(|bytes| bytes > self.limits.max_value_bytes) + { + return Err(KvError::Unavailable); + } + // Check native TTL's shape but never impose a hard expiry filter. + if let Some(ttl) = item.get("ttl_epoch_s") { + read_unsigned(ttl.as_n()?)?; + } + Ok(Record { + body, + metadata, + generation, + }) + } + + pub(crate) async fn delete_value( + &self, + key: &str, + partition: &RecordPartition, + ) -> Result<(), KvError> { + let deadline = self.runtime_deadline()?; + let request = Request { + key: Some(self.key(key, partition, "r")?), + ..Request::default() + }; + self.mutate(deadline, Operation::DeleteItem, request) + .await? + .map(|_response| ()) + .map_err(mutation_error) + } + + pub(crate) fn decode_cursor( + &self, + mode: &str, + prefix: &str, + encoded: &str, + partition: Option<&RecordPartition>, + ) -> Result { + if encoded.len() > MAX_CURSOR_BYTES { + return Err(invalid_input()); + } + let cursor: RecordCursor = + serde_json::from_str(encoded).map_err(|_error| invalid_input())?; + if cursor.format != FORMAT + || cursor.layout_id != self.binding.layout.id() + || cursor.layout_version != self.binding.layout.version() + || cursor.scope != self.binding.scope + || cursor.mode != mode + || cursor.prefix != prefix + { + return Err(invalid_input()); + } + let key = physical_key(cursor.pk, cursor.sk); + validate_position(&key).map_err(|_error| invalid_input())?; + if let Some(expected_partition) = partition + && key.get("pk") != Some(&Attr::Text(self.partition_key(expected_partition)?)) + { + return Err(invalid_input()); + } + Ok(key) + } + + pub(crate) fn next_cursor( + &self, + mode: &str, + prefix: &str, + after: Option<&Item>, + next_position: Option, + partition: Option<&RecordPartition>, + ) -> Result, KvError> { + let Some(position) = next_position.filter(|candidate| !candidate.is_empty()) else { + return Ok(None); + }; + let (pk, sk) = validate_position(&position)?; + if after == Some(&position) { + return Err(KvError::Unavailable); + } + if let Some(expected_partition) = partition + && (pk != self.partition_key(expected_partition)? + || after + .and_then(|key| key.get("sk")) + .and_then(|value| value.as_s().ok()) + .is_some_and(|previous| sk <= previous)) + { + return Err(KvError::Unavailable); + } + let encoded = serde_json::to_string(&RecordCursor { + format: FORMAT.to_owned(), + layout_id: self.binding.layout.id().to_owned(), + layout_version: self.binding.layout.version(), + mode: mode.to_owned(), + pk: pk.to_owned(), + prefix: prefix.to_owned(), + scope: self.binding.scope.clone(), + sk: sk.to_owned(), + }) + .map_err(|_error| KvError::Unavailable)?; + if encoded.len() > MAX_CURSOR_BYTES { + return Err(KvError::Unavailable); + } + Ok(Some(encoded)) + } + + fn listed_keys( + &self, + items: Vec, + prefix: &str, + limit: usize, + partition: Option<&RecordPartition>, + ) -> Result, KvError> { + if items.len() > limit { + return Err(KvError::Unavailable); + } + items + .into_iter() + .map(|item| { + validate_value_kind(&item)?; + let (pk, sk) = validate_position_item(&item)?; + let key = sk + .strip_prefix("r#") + .filter(|key| key.starts_with(prefix)) + .ok_or(KvError::Unavailable)?; + let resolved = self + .binding + .layout + .resolve(key) + .map_err(|_error| KvError::Unavailable)?; + if pk != self.partition_key(&resolved)? + || partition.is_some_and(|expected| expected != &resolved) + { + return Err(KvError::Unavailable); + } + Ok(key.to_owned()) + }) + .collect() + } + + fn page_request( + &self, + prefix: &str, + partition: Option<&RecordPartition>, + after: Option, + limit: usize, + ) -> Result<(Operation, Request), KvError> { + let native_limit = i32::try_from(limit).map_err(|_error| invalid_input())?; + let mut request = Request { + exclusive_start_key: after, + limit: Some(native_limit), + names: names(&[ + ("#pk", "pk"), + ("#sk", "sk"), + ("#format", "format"), + ("#kind", "kind"), + ]), + projection_expression: Some("#pk, #sk, #format, #kind"), + values: Item::from([ + (":format".to_owned(), Attr::Text(FORMAT.to_owned())), + (":kind".to_owned(), Attr::Text("r".to_owned())), + ]), + ..Request::default() + }; + if let Some(query_partition) = partition { + // Query cannot filter a key attribute. Full membership is checked + // after the reply, while the partition PK already bounds keys. + request.consistent_read = Some(true); + request.scan_index_forward = Some(true); + request.key_condition_expression = Some("#pk = :pk"); + request.filter_expression = Some("#format = :format AND #kind = :kind"); + request.values.insert( + ":pk".to_owned(), + Attr::Text(self.partition_key(query_partition)?), + ); + return Ok((Operation::Query, request)); + } + request.filter_expression = Some( + "begins_with(#pk, :binding) AND #format = :format AND #kind = :kind AND begins_with(#sk, :prefix)", + ); + request.values.insert( + ":binding".to_owned(), + Attr::Text(self.partition_base.clone()), + ); + request + .values + .insert(":prefix".to_owned(), Attr::Text(format!("r#{prefix}"))); + Ok((Operation::Scan, request)) + } + + pub(crate) async fn page( + &self, + prefix: &str, + partition: Option<&RecordPartition>, + cursor: Option<&str>, + limit: usize, + ) -> Result { + let deadline = self.runtime_deadline()?; + if prefix.len() > MAX_KEY_BYTES || prefix.chars().any(char::is_control) { + return Err(invalid_input()); + } + if limit == 0 || limit > MAX_PAGE_KEYS { + return Err(invalid_input()); + } + let mode = if partition.is_some() { "query" } else { "scan" }; + let after = cursor + .map(|encoded| self.decode_cursor(mode, prefix, encoded, partition)) + .transpose()?; + let (operation, request) = self.page_request(prefix, partition, after.clone(), limit)?; + let output = self.bounded(deadline, operation, request).await?; + if partition.is_some() { + validate_query_positions( + &output.items, + after.as_ref(), + output.last_evaluated_key.as_ref(), + )?; + } + let keys = self.listed_keys(output.items, prefix, limit, partition)?; + let next = self.next_cursor( + mode, + prefix, + after.as_ref(), + output.last_evaluated_key, + partition, + )?; + Ok(KvPage { keys, cursor: next }) + } +} + +#[expect( + clippy::arbitrary_source_item_ordering, + reason = "keep prepared capability and ordinary methods ahead of the record boundary" +)] +#[expect( + clippy::missing_trait_methods, + reason = "ordinary exists deliberately delegates to the same strong get-bytes path" +)] +#[async_trait(?Send)] +impl KvStore for RecordCore { + fn record_binding(&self) -> Option { + Some(self.binding.clone()) + } + + async fn get_bytes(&self, key: &str) -> Result, KvError> { + let partition = self.binding.layout.resolve(key)?; + Ok(self + .lookup(key, &partition) + .await? + .map(|record| record.body)) + } + + async fn put_bytes(&self, key: &str, value: Bytes) -> Result<(), KvError> { + let partition = self.binding.layout.resolve(key)?; + self.insert( + key, + &partition, + RecordWrite { + body: &value, + metadata: None, + ttl: None, + mode: RecordWriteMode::Overwrite, + }, + ) + .await?; + Ok(()) + } + + async fn put_bytes_with_ttl( + &self, + key: &str, + value: Bytes, + ttl: Duration, + ) -> Result<(), KvError> { + let partition = self.binding.layout.resolve(key)?; + self.insert( + key, + &partition, + RecordWrite { + body: &value, + metadata: None, + ttl: Some(ttl), + mode: RecordWriteMode::Overwrite, + }, + ) + .await?; + Ok(()) + } + + async fn delete(&self, key: &str) -> Result<(), KvError> { + self.delete_value(key, &self.binding.layout.resolve(key)?) + .await + } + + async fn list_keys_page( + &self, + prefix: &str, + cursor: Option<&str>, + limit: usize, + ) -> Result { + self.page(prefix, None, cursor, limit).await + } + + async fn record_lookup( + &self, + key: &str, + partition: &RecordPartition, + ) -> Result, KvError> { + self.lookup(key, partition).await + } + + async fn record_insert( + &self, + key: &str, + partition: &RecordPartition, + write: RecordWrite<'_>, + ) -> Result { + self.insert(key, partition, write).await + } + + async fn record_exists_strong( + &self, + key: &str, + partition: &RecordPartition, + ) -> Result { + Ok(self.lookup(key, partition).await?.is_some()) + } + + async fn record_delete(&self, key: &str, partition: &RecordPartition) -> Result<(), KvError> { + self.delete_value(key, partition).await + } + + async fn record_list_partition( + &self, + partition: &RecordPartition, + cursor: Option<&str>, + limit: usize, + ) -> Result { + self.partition_key(partition)?; + let page = self + .page(partition.prefix(), Some(partition), cursor, limit) + .await?; + Ok(RecordPage { + keys: page.keys, + cursor: page.cursor, + }) + } +} + +/// One classifier for value mutations on every transport. +pub(crate) const fn mutation_error(error: TransportError) -> KvError { + match error { + TransportError::NotDispatched + | TransportError::Service { + definitive: true, .. + } => KvError::Unavailable, + TransportError::Service { + definitive: false, .. + } + | TransportError::Uncertain => KvError::MutationUncertain, + } +} + +fn names(pairs: &[(&str, &str)]) -> BTreeMap { + pairs + .iter() + .map(|(alias, name)| ((*alias).to_owned(), (*name).to_owned())) + .collect() +} + +pub(crate) fn physical_key(pk: String, sk: String) -> Item { + Item::from([ + ("pk".to_owned(), Attr::Text(pk)), + ("sk".to_owned(), Attr::Text(sk)), + ]) +} + +pub(crate) fn record_partition_base( + settings: &DynamoDbKvSettings, + layout: &RecordLayout, +) -> Result { + // Byte lengths delimit arbitrary namespace/layout identities without escaping + // or collisions. The final remainder is the unchanged declared partition. + settings.validate()?; + let base = format!( + "{FORMAT}#{}:{}{}:{}{}:", + settings.namespace.len(), + settings.namespace, + layout.id().len(), + layout.id(), + layout.version() + ); + if base + .len() + .checked_add(MAX_KEY_BYTES) + .is_none_or(|size| size > MAX_PARTITION_BYTES) + { + return Err(PreparationError::InvalidBinding); + } + Ok(base) +} + +fn validate_position(key: &Item) -> Result<(&str, &str), KvError> { + if key.len() != 2 { + return Err(KvError::Unavailable); + } + validate_position_item(key) +} + +fn validate_position_item(item: &Item) -> Result<(&str, &str), KvError> { + match (item.get("pk"), item.get("sk")) { + (Some(Attr::Text(pk)), Some(Attr::Text(sk))) + if !pk.is_empty() + && pk.len() <= MAX_PARTITION_BYTES + && !sk.is_empty() + && sk.len() <= 1_024 => + { + Ok((pk, sk)) + } + _ => Err(KvError::Unavailable), + } +} + +fn validate_query_positions( + items: &[Item], + after: Option<&Item>, + next_position: Option<&Item>, +) -> Result<(), KvError> { + let mut previous = after.map(validate_position).transpose()?.map(|(_, sk)| sk); + for item in items { + let (_, sk) = validate_position_item(item)?; + if previous.is_some_and(|last| sk <= last) { + return Err(KvError::Unavailable); + } + previous = Some(sk); + } + if let Some(position) = next_position.filter(|candidate| !candidate.is_empty()) { + let (_, sk) = validate_position(position)?; + if previous.is_some_and(|last| sk < last) { + return Err(KvError::Unavailable); + } + } + Ok(()) +} + +fn validate_value_kind(item: &Item) -> Result<(), KvError> { + if item.get("format") != Some(&Attr::Text(FORMAT.to_owned())) + || item.get("kind") != Some(&Attr::Text("r".to_owned())) + { + return Err(KvError::Unavailable); + } + Ok(()) +} + +fn validate_record_size(item: &Item) -> Result<(), KvError> { + let mut size = 0_usize; + for (name, value) in item { + let bytes = match value { + Attr::Text(text) | Attr::Number(text) => text.len(), + Attr::Binary(blob) => blob.len(), + Attr::Other => return Err(invalid_input()), + }; + size = size + .checked_add(name.len()) + .and_then(|with_name| with_name.checked_add(bytes)) + .ok_or_else(invalid_input)?; + } + if size > MAX_ITEM_BYTES { + return Err(invalid_input()); + } + Ok(()) +} + +pub(crate) fn expiry_from_duration(now: Duration, ttl: Duration) -> Result { + if ttl.is_zero() { + return Err(invalid_input()); + } + let expires = now.checked_add(ttl).ok_or_else(invalid_input)?; + let rounded = expires + .as_millis() + .checked_add(u128::from( + !expires.subsec_nanos().is_multiple_of(1_000_000), + )) + .ok_or_else(invalid_input)?; + u64::try_from(rounded).map_err(|_error| invalid_input()) +} + +pub(crate) fn invalid_input() -> KvError { + KvError::Validation("invalid DynamoDB KV input".to_owned()) +} + +pub(crate) fn read_unsigned(value: &str) -> Result { + if value.is_empty() || value.len() > 20 || !value.bytes().all(|byte| byte.is_ascii_digit()) { + return Err(KvError::Unavailable); + } + let number = value + .parse::() + .map_err(|_error| KvError::Unavailable)?; + if number.to_string() != value { + return Err(KvError::Unavailable); + } + Ok(number) +} diff --git a/crates/edgezero-store-aws/src/settings.rs b/crates/edgezero-store-aws/src/settings.rs index b7ada58fc..42cc945b0 100644 --- a/crates/edgezero-store-aws/src/settings.rs +++ b/crates/edgezero-store-aws/src/settings.rs @@ -8,12 +8,13 @@ use std::collections::BTreeMap; use std::fmt; use std::net::IpAddr; -use std::time::{Duration, Instant}; +use std::time::Duration; use percent_encoding::percent_decode_str; use serde::de::Error as _; use serde::{Deserialize, Deserializer}; use url::Url; +use web_time::Instant; use crate::PreparationError; @@ -175,6 +176,15 @@ impl Default for DynamoDbKvLimits { } impl DynamoDbKvLimits { + /// Enforced defaults for portable bindings: one 1,000 ms operation deadline, + /// shared by both calls of an insert, and a 250 ms connect timeout. + pub const PORTABLE: Self = Self { + max_value_bytes: 393_216, + operation_timeout_ms: 1_000, + connect_timeout_ms: 250, + attempt_timeout_ms: 1_000, + }; + /// Checks payload bounds and representable, ordered operation budgets. /// /// # Errors @@ -246,6 +256,262 @@ impl DynamoDbKvSettings { } } +/// Per-binding limits as written. Absent fields take the target's defaults. +#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq)] +#[serde(deny_unknown_fields)] +pub struct DynamoDbKvLimitsInput { + pub attempt_timeout_ms: Option, + pub connect_timeout_ms: Option, + pub max_value_bytes: Option, + pub operation_timeout_ms: Option, +} + +impl DynamoDbKvLimitsInput { + /// Fills absent fields from `defaults`, either native or [`DynamoDbKvLimits::PORTABLE`]. + #[inline] + #[must_use] + pub fn resolve(self, defaults: DynamoDbKvLimits) -> DynamoDbKvLimits { + DynamoDbKvLimits { + max_value_bytes: self.max_value_bytes.unwrap_or(defaults.max_value_bytes), + operation_timeout_ms: self + .operation_timeout_ms + .unwrap_or(defaults.operation_timeout_ms), + connect_timeout_ms: self + .connect_timeout_ms + .unwrap_or(defaults.connect_timeout_ms), + attempt_timeout_ms: self + .attempt_timeout_ms + .unwrap_or(defaults.attempt_timeout_ms), + } + } +} + +/// The secret key names a portable `DynamoDB` binding reads for KV ID `id`. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct DynamoDbCredentialKeys { + pub access_key_id: String, + pub secret_access_key: String, + pub session_token: String, +} + +impl DynamoDbCredentialKeys { + /// `KV____AWS_ACCESS_KEY_ID`, `..._AWS_SECRET_ACCESS_KEY` and optional + /// `..._AWS_SESSION_TOKEN`. Bindings cannot name other keys. + #[inline] + #[must_use] + pub fn for_kv_id(id: &str) -> Self { + let prefix = format!("KV__{}__", id.to_ascii_uppercase()); + Self { + access_key_id: format!("{prefix}AWS_ACCESS_KEY_ID"), + secret_access_key: format!("{prefix}AWS_SECRET_ACCESS_KEY"), + session_token: format!("{prefix}AWS_SESSION_TOKEN"), + } + } +} + +/// A logical secrets store ID. Key names derive from the KV ID and are never configured. +#[derive(Clone, Deserialize, Eq, PartialEq)] +#[serde(deny_unknown_fields)] +pub struct SecretsReference { + pub secrets: String, +} + +impl fmt::Debug for SecretsReference { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("SecretsReference").finish_non_exhaustive() + } +} + +impl SecretsReference { + /// Checks the logical ID shape. Whether it is declared is the bindings document's check. + /// + /// # Errors + /// Rejects an empty or non-`[A-Za-z0-9_]` logical ID. + #[inline] + pub fn validate(&self) -> Result<(), PreparationError> { + if self.secrets.is_empty() + || self.secrets.len() > MAX_SECRET_KEY_BYTES + || !self + .secrets + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || byte == b'_') + { + return Err(PreparationError::InvalidBinding); + } + Ok(()) + } +} + +/// The `DescribeTable` identity an offline preflight pinned into the binding. +#[derive(Clone, Deserialize, Eq, PartialEq, serde::Serialize)] +#[serde(deny_unknown_fields)] +pub struct DynamoDbPinnedIdentity { + pub table_arn: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub table_id: Option, +} + +impl fmt::Debug for DynamoDbPinnedIdentity { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("DynamoDbPinnedIdentity") + .finish_non_exhaustive() + } +} + +impl DynamoDbPinnedIdentity { + /// Checks the pinned values' shape. Their truth is only known to preflight. + /// + /// # Errors + /// Rejects empty, oversized or control-character identities. + #[inline] + pub fn validate(&self) -> Result<(), PreparationError> { + let valid = |value: &str| { + !value.is_empty() && value.len() <= 2_048 && !value.chars().any(char::is_control) + }; + if !valid(&self.table_arn) || self.table_id.as_deref().is_some_and(|id| !valid(id)) { + return Err(PreparationError::InvalidResource); + } + Ok(()) + } +} + +/// What offline preflight observed: the endpoint identity it used and the table to pin. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct DynamoDbRecordIdentity { + pub endpoint: String, + pub pinned: DynamoDbPinnedIdentity, +} + +/// An `aws-dynamodb-records` binding. Native preparation uses the SDK credential +/// chain and endpoint resolution; portable bindings use `endpoint`, `pinned` and +/// `credentials`. Debug never exposes resource names. +#[derive(Clone, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct DynamoDbRecordsSettings { + #[serde(default)] + pub credentials: Option, + #[serde(default)] + pub endpoint: Option, + #[serde(default)] + pub limits: DynamoDbKvLimitsInput, + pub namespace: String, + #[serde(default)] + pub pinned: Option, + pub region: String, + pub table: String, +} + +impl fmt::Debug for DynamoDbRecordsSettings { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("DynamoDbRecordsSettings") + .finish_non_exhaustive() + } +} + +impl DynamoDbRecordsSettings { + /// The table address with limits resolved against `defaults`. + #[inline] + #[must_use] + pub fn kv_settings(&self, defaults: DynamoDbKvLimits) -> DynamoDbKvSettings { + DynamoDbKvSettings { + region: self.region.clone(), + table: self.table.clone(), + namespace: self.namespace.clone(), + limits: self.limits.resolve(defaults), + } + } + + /// The endpoint identity a portable transport sends to and binds into cursors. + /// + /// Without an explicit `endpoint` this is the region's public `DynamoDB` endpoint. + /// It is normalized exactly as native preparation normalizes its request URI. + /// + /// # Errors + /// Rejects an endpoint that is not `https`, or `http` on a loopback IP literal, + /// and one carrying user information, a query, a fragment or a path. + #[inline] + pub fn portable_endpoint(&self) -> Result { + let explicit = self + .endpoint + .as_deref() + .map(validated_endpoint) + .transpose()?; + let url = if let Some(url) = explicit { + url + } else { + let suffix = if self.region.starts_with("cn-") { + "amazonaws.com.cn" + } else { + "amazonaws.com" + }; + Url::parse(&format!("https://dynamodb.{}.{suffix}", self.region)) + .map_err(|_error| PreparationError::InvalidEndpoint)? + }; + endpoint_identity(url.as_str()).ok_or(PreparationError::InvalidEndpoint) + } + + /// Structural checks with limits resolved against `defaults`. No I/O. + /// + /// # Errors + /// Rejects invalid addresses, limits, endpoints, pins and secrets references. + #[inline] + pub fn validate(&self, defaults: DynamoDbKvLimits) -> Result<(), PreparationError> { + self.kv_settings(defaults).validate()?; + if let Some(endpoint) = &self.endpoint { + validated_endpoint(endpoint)?; + } + if let Some(pinned) = &self.pinned { + pinned.validate()?; + } + if let Some(credentials) = &self.credentials { + credentials.validate()?; + } + Ok(()) + } +} + +/// Scheme, host, port and path only. Native binds the same form of its request URI. +pub(crate) fn endpoint_identity(uri: &str) -> Option { + let mut endpoint = Url::parse(uri).ok()?; + endpoint.host_str()?; + endpoint.set_username("").ok()?; + endpoint.set_password(None).ok()?; + endpoint.set_query(None); + endpoint.set_fragment(None); + Some(endpoint.into()) +} + +fn validated_endpoint(endpoint: &str) -> Result { + if endpoint + .bytes() + .any(|byte| byte.is_ascii_whitespace() || byte.is_ascii_control()) + { + return Err(PreparationError::InvalidEndpoint); + } + let url = Url::parse(endpoint).map_err(|_error| PreparationError::InvalidEndpoint)?; + let loopback = match url.host() { + Some(url::Host::Ipv4(ip)) => ip.is_loopback(), + Some(url::Host::Ipv6(ip)) => ip.is_loopback(), + Some(url::Host::Domain(_)) | None => false, + }; + let scheme_allowed = url.scheme() == "https" || (url.scheme() == "http" && loopback); + if !scheme_allowed + || url.host_str().is_none() + || !url.username().is_empty() + || url.password().is_some() + || url.query().is_some() + || url.fragment().is_some() + || url.path() != "/" + || url.port() == Some(0) + { + return Err(PreparationError::InvalidEndpoint); + } + Ok(url) +} + /// Exactly one version selector. Omission means AWSCURRENT at startup. /// API lengths count characters; non-control Unicode and embedded spaces retain /// their exact meaning. Validation does not assert that a version/stage exists. diff --git a/crates/edgezero-store-celld/Cargo.toml b/crates/edgezero-store-celld/Cargo.toml index 422ad7fe9..1c3e771c3 100644 --- a/crates/edgezero-store-celld/Cargo.toml +++ b/crates/edgezero-store-celld/Cargo.toml @@ -13,40 +13,57 @@ workspace = true [features] default = [] kv = [ - "dep:edgezero-core", + "wire", "dep:bytes", "dep:async-trait", "dep:reqwest", "dep:tokio", "dep:futures-util", + "dep:sha2", +] +records = ["kv", "record-wire"] +# Shared request and response policy. Not a public selection. +wire = [ + "dep:edgezero-core", "dep:serde_json", "dep:base64", - "dep:sha2", "dep:getrandom", + "dep:bytes", + "dep:async-trait", ] -records = ["kv"] +# Shared record format and record wire variants. Not a public selection. +record-wire = ["wire", "dep:sha2", "dep:bytes", "dep:async-trait"] +# Portable record transport over EdgeZero outbound HTTP. +portable-records = ["record-wire", "dep:futures-util", "futures-util/std"] [dependencies] -serde = { workspace = true } -thiserror = { workspace = true } -url = { workspace = true } - -[target.'cfg(not(target_arch = "wasm32"))'.dependencies] async-trait = { workspace = true, optional = true } base64 = { workspace = true, optional = true } bytes = { workspace = true, optional = true } edgezero-core = { workspace = true, optional = true } futures-util = { workspace = true, optional = true } getrandom = { workspace = true, optional = true } -reqwest = { workspace = true, optional = true, features = ["stream"] } +serde = { workspace = true } serde_json = { workspace = true, optional = true } sha2 = { workspace = true, optional = true } +thiserror = { workspace = true } +url = { workspace = true } + +# The JavaScript host supplies randomness on wasm32-unknown-unknown (Cloudflare). +[target.'cfg(all(target_arch = "wasm32", target_os = "unknown"))'.dependencies] +getrandom = { workspace = true, optional = true, features = ["wasm_js"] } + +[target.'cfg(not(target_arch = "wasm32"))'.dependencies] +reqwest = { workspace = true, optional = true, features = ["stream"] } tokio = { workspace = true, optional = true } [dev-dependencies] serde_json = { workspace = true } [target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies] +# A real native HttpClient for portable-transport tests. The adapter depends on this +# crate; Cargo permits the cycle for dev-dependencies only. +edgezero-adapter-axum = { workspace = true, features = ["axum"] } edgezero-core = { workspace = true, features = ["test-utils"] } tempfile = { workspace = true } tokio-rustls = { workspace = true } diff --git a/crates/edgezero-store-celld/src/client.rs b/crates/edgezero-store-celld/src/client.rs index 736777920..a7bd1d199 100644 --- a/crates/edgezero-store-celld/src/client.rs +++ b/crates/edgezero-store-celld/src/client.rs @@ -1,42 +1,26 @@ -//! One bounded HTTP exchange. No discovery, redirects, proxies or mutation replay. +//! One bounded native HTTP exchange. No discovery, redirects, proxies or mutation replay. //! -//! Every mutation carries a fresh random ID. The store service records it in the -//! same transaction as the write, so a duplicate delivery inside celld or a proxy -//! cannot apply it twice. The client itself never resends a mutation. - -#![expect( - clippy::arbitrary_source_item_ordering, - reason = "keep transport construction, request lifecycle and response validators together" -)] +//! Request and response policy lives in [`crate::wire`]; this module only sends with +//! reqwest and streams the bounded body. use std::fmt; use std::time::Duration; -use base64::Engine as _; -use base64::engine::general_purpose::URL_SAFE_NO_PAD; +use async_trait::async_trait; use bytes::Bytes; use edgezero_core::time::{Deadline, MonotonicClock}; use futures_util::StreamExt as _; -use reqwest::header::{ - ACCEPT_ENCODING, AUTHORIZATION, CONTENT_ENCODING, CONTENT_LENGTH, CONTENT_TYPE, HeaderMap, - HeaderValue, -}; +use reqwest::header::HeaderValue; use reqwest::redirect::Policy; use reqwest::retry::never; -use reqwest::{Client, Method, StatusCode}; -use serde::Deserialize; +use reqwest::{Client, Method}; use tokio::time::timeout; use url::Url; use crate::PreparationError; use crate::settings::{CelldAccessToken, CelldPreparationLimits}; - -const ERROR_CAP: usize = 1_024; -const INSTANCE_HEADER: &str = "x-edgezero-store-instance"; -const MUTATION_HEADER: &str = "x-edgezero-mutation-id"; -const VERSION_HEADER: &str = "x-edgezero-store-version"; -const RECORD_HEADER: &str = "x-edgezero-record-version"; -const EXPECTED_INSTANCE_HEADER: &str = "x-edgezero-expected-instance"; +use crate::wire::{self, Exchanger, Head}; +pub(crate) use crate::wire::{Exchange, ResponseKind}; pub(crate) struct ScopedClient { authorization: Option, @@ -52,88 +36,10 @@ impl fmt::Debug for ScopedClient { } } -#[derive(Clone, Copy)] -pub(crate) enum ResponseKind { - Exists, - Mutation, - Page, - Value, - #[cfg(feature = "records")] - RecordCapabilities, - #[cfg(feature = "records")] - RecordExists([u8; 22]), - #[cfg(feature = "records")] - RecordMutation([u8; 22]), - #[cfg(feature = "records")] - RecordPage([u8; 22]), - #[cfg(feature = "records")] - RecordValue([u8; 22]), -} - -impl ResponseKind { - const fn mutation(self) -> bool { - match self { - Self::Mutation => true, - #[cfg(feature = "records")] - Self::RecordMutation(_) => true, - _ => false, - } - } - - const fn json(self) -> bool { - match self { - Self::Page => true, - #[cfg(feature = "records")] - Self::RecordCapabilities | Self::RecordPage(_) | Self::RecordValue(_) => true, - _ => false, - } - } - - const fn optional(self) -> bool { - match self { - Self::Value => true, - #[cfg(feature = "records")] - Self::RecordValue(_) => true, - _ => false, - } - } - - const fn record(self) -> bool { - match self { - #[cfg(feature = "records")] - Self::RecordCapabilities - | Self::RecordExists(_) - | Self::RecordMutation(_) - | Self::RecordPage(_) - | Self::RecordValue(_) => true, - _ => false, - } - } - - const fn expected_instance(self) -> Option<[u8; 22]> { - match self { - #[cfg(feature = "records")] - Self::RecordExists(instance) - | Self::RecordMutation(instance) - | Self::RecordPage(instance) - | Self::RecordValue(instance) => Some(instance), - _ => None, - } - } -} - -/// A validated exchange. The instance identifies the store's durable state. -pub(crate) struct Exchange { - pub body: Option>, - pub instance: Option, -} - -impl fmt::Debug for Exchange { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Exchange").finish_non_exhaustive() - } -} - +#[expect( + clippy::arbitrary_source_item_ordering, + reason = "keep the public constructor ahead of its test seam" +)] impl ScopedClient { pub(crate) fn new( endpoint: Url, @@ -168,14 +74,7 @@ impl ScopedClient { if let Some(certificate) = root { builder = builder.tls_certs_only([certificate]); } - let authorization = token - .map(|credential| { - let mut header = HeaderValue::from_str(&format!("Bearer {}", credential.expose())) - .map_err(|_error| PreparationError::Credentials)?; - header.set_sensitive(true); - Ok(header) - }) - .transpose()?; + let authorization = token.map(wire::authorization).transpose()?; Ok(Self { authorization, client: builder @@ -186,8 +85,15 @@ impl ScopedClient { limits, }) } +} - pub(crate) fn deadline(&self) -> Result { +#[expect( + clippy::arbitrary_source_item_ordering, + reason = "keep deadlines ahead of the request lifecycle" +)] +#[async_trait(?Send)] +impl Exchanger for ScopedClient { + fn deadline(&self) -> Result { self.clock .now() .checked_add(Duration::from_millis(self.limits.operation_timeout_ms)) @@ -195,25 +101,20 @@ impl ScopedClient { .ok_or(PreparationError::Deadline) } - pub(crate) fn check(&self, deadline: Deadline) -> Result { + fn check(&self, deadline: Deadline) -> Result { deadline .remaining_at(self.clock.now()) .ok_or(PreparationError::Deadline) } - pub(crate) fn url(&self, store: &str, resource: &str) -> Result { - let mut url = self.endpoint.clone(); - url.path_segments_mut() - .map_err(|_error| PreparationError::InvalidEndpoint)? - .clear() - .extend(["v1", "stores", store, resource]); - Ok(url) + fn url(&self, store: &str, resource: &str) -> Result { + wire::store_url(&self.endpoint, store, resource) } /// Covers sending, streaming and decoding with one real timer and injected /// monotonic checks. A None body means a validated miss, never a protocol /// failure. Successful responses must name the store instance. - pub(crate) async fn execute( + async fn execute( &self, method: Method, url: Url, @@ -225,261 +126,43 @@ impl ScopedClient { let budget = self .check(deadline)? .min(Duration::from_millis(self.limits.operation_timeout_ms)); + let headers = wire::request_headers(kind, self.authorization.as_ref(), body.is_some())?; let mut request = self .client .request(method.clone(), url) - .header(ACCEPT_ENCODING, "identity") + .headers(headers) .timeout(budget); - if let Some(authorization) = &self.authorization { - request = request.header(AUTHORIZATION, authorization.clone()); - } - if kind.mutation() { - request = request.header(MUTATION_HEADER, mutation_id()?); - } - if kind.record() { - request = request.header(RECORD_HEADER, "1"); - } - if let Some(expected) = kind.expected_instance() { - request = request.header( - EXPECTED_INSTANCE_HEADER, - HeaderValue::from_bytes(&expected).map_err(|_error| PreparationError::Malformed)?, - ); - } if let Some(payload) = body { - request = request - .header( - CONTENT_TYPE, - if kind.record() { - "application/json" - } else { - "application/octet-stream" - }, - ) - .body(payload); + request = request.body(payload); } let mut definitive_rejection = false; let exchange = timeout(budget, async { let response = request.send().await.map_err(http_error)?; - self.decode_response( - response, - method, - cap, - deadline, - kind, - &mut definitive_rejection, - ) - .await + let status = response.status(); + match wire::head(kind, &method, status, response.headers(), cap)? { + Head::Complete(exchange) => Ok(exchange), + Head::Body { + cap: body_cap, + instance, + success, + } => { + let bytes = collect(response, body_cap, &self.clock, deadline).await?; + wire::body( + kind, + status, + instance, + success, + bytes, + &mut definitive_rejection, + ) + } + } }) .await .map_err(|_elapsed| PreparationError::Deadline); let result = self.check(deadline).and_then(|_remaining| exchange?); - #[cfg(feature = "records")] - if matches!(kind, ResponseKind::RecordMutation(_)) && !definitive_rejection { - return result.map_err(|_error| PreparationError::MutationUncertain); - } - result - } - - async fn decode_response( - &self, - response: reqwest::Response, - method: Method, - cap: usize, - deadline: Deadline, - kind: ResponseKind, - definitive_rejection: &mut bool, - ) -> Result { - let status = response.status(); - let success = status - == if kind.mutation() { - StatusCode::NO_CONTENT - } else { - StatusCode::OK - }; - let missing = status == StatusCode::NOT_FOUND; - let headers = response.headers(); - let instance = validated_instance(headers, kind, &method, status, success)?; - - // A mutation acknowledgement carries no body, so it has no media type. - if status == StatusCode::NO_CONTENT && success { - if headers - .get(CONTENT_LENGTH) - .is_some_and(|length| length.as_bytes() != b"0") - { - return Err(PreparationError::Malformed); - } - return Ok(Exchange { - body: Some(Vec::new()), - instance, - }); - } - // The wire HEAD contract has no error body, including non-404 errors. - if method == Method::HEAD { - return if success { - Ok(Exchange { - body: Some(Vec::new()), - instance, - }) - } else if missing { - Ok(Exchange { - body: None, - instance, - }) - } else { - Err(status_error(status).map_or(PreparationError::Malformed, |(_, error)| error)) - }; - } - let expected_type = if !success || kind.json() { - "application/json" - } else { - "application/octet-stream" - }; - validate_content_type(headers, expected_type)?; - let response_cap = if success { cap } else { ERROR_CAP }; - let bytes = collect(response, response_cap, &self.clock, deadline).await?; - if success { - return Ok(Exchange { - body: Some(bytes), - instance, - }); - } - let error = validated_error(kind, status, &bytes)?; - if status.is_client_error() { - *definitive_rejection = true; - } - if missing && kind.optional() { - return Ok(Exchange { - body: None, - instance, - }); - } - Err(error) - } -} - -fn validated_instance( - headers: &HeaderMap, - kind: ResponseKind, - method: &Method, - status: StatusCode, - success: bool, -) -> Result, PreparationError> { - validate_headers(headers)?; - if kind.record() { - let mut versions = headers.get_all(RECORD_HEADER).iter(); - if versions.next().is_none_or(|value| value.as_bytes() != b"1") || versions.next().is_some() - { - return Err(PreparationError::UnsupportedVersion); - } - } - let observed = instance(headers)?; - if let Some(expected) = kind.expected_instance() - && observed - .as_ref() - .is_some_and(|value| value.as_bytes() != expected) - { - return Err(PreparationError::InstanceChanged); - } - let logical_miss = - status == StatusCode::NOT_FOUND && (*method == Method::HEAD || kind.optional()); - if (success || logical_miss || (kind.record() && status == StatusCode::PRECONDITION_FAILED)) - && observed.is_none() - { - return Err(PreparationError::Malformed); + wire::finish(kind, result, definitive_rejection) } - Ok(observed) -} - -fn validated_error( - kind: ResponseKind, - status: StatusCode, - bytes: &[u8], -) -> Result { - if status == StatusCode::PRECONDITION_FAILED && !kind.record() { - return Err(PreparationError::Malformed); - } - let parsed: ErrorBody = - serde_json::from_slice(bytes).map_err(|_error| PreparationError::Malformed)?; - #[cfg(feature = "records")] - let record_error = match (kind, status, parsed.error.as_str()) { - ( - ResponseKind::RecordMutation(_), - StatusCode::PRECONDITION_FAILED, - "precondition_failed", - ) => Some(PreparationError::PreconditionFailed), - (_, StatusCode::SERVICE_UNAVAILABLE, "instance_changed") if kind.record() => { - Some(PreparationError::InstanceChanged) - } - _ => None, - }; - #[cfg(not(feature = "records"))] - let record_error = None; - let error = if let Some(error) = record_error { - error - } else { - let (expected, error) = status_error(status).ok_or(PreparationError::Malformed)?; - if parsed.error != expected { - return Err(PreparationError::Malformed); - } - error - }; - - Ok(error) -} - -/// A fresh 128-bit mutation ID. It is never reused, including after a failure. -fn mutation_id() -> Result { - let mut bytes = [0_u8; 16]; - getrandom::fill(&mut bytes).map_err(|_error| PreparationError::Unavailable)?; - HeaderValue::from_str(&URL_SAFE_NO_PAD.encode(bytes)) - .map_err(|_error| PreparationError::Unavailable) -} - -fn instance(headers: &HeaderMap) -> Result, PreparationError> { - let mut values = headers.get_all(INSTANCE_HEADER).iter(); - let Some(value) = values.next() else { - return Ok(None); - }; - let bytes = value.as_bytes(); - if values.next().is_some() - || bytes.len() != 22 - || !bytes - .iter() - .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_')) - { - return Err(PreparationError::Malformed); - } - Ok(Some( - String::from_utf8(bytes.to_vec()).map_err(|_error| PreparationError::Malformed)?, - )) -} - -fn validate_headers(headers: &HeaderMap) -> Result<(), PreparationError> { - let mut versions = headers.get_all(VERSION_HEADER).iter(); - if versions.next().is_none_or(|value| value.as_bytes() != b"1") || versions.next().is_some() { - return Err(PreparationError::UnsupportedVersion); - } - let mut encodings = headers.get_all(CONTENT_ENCODING).iter(); - if encodings - .next() - .is_some_and(|value| !value.as_bytes().eq_ignore_ascii_case(b"identity")) - || encodings.next().is_some() - { - return Err(PreparationError::Malformed); - } - Ok(()) -} - -fn validate_content_type(headers: &HeaderMap, expected: &str) -> Result<(), PreparationError> { - let mut types = headers.get_all(CONTENT_TYPE).iter(); - if types - .next() - .is_none_or(|value| value.as_bytes() != expected.as_bytes()) - || types.next().is_some() - { - return Err(PreparationError::Malformed); - } - Ok(()) } async fn collect( @@ -510,12 +193,6 @@ async fn collect( Ok(bytes) } -#[derive(Deserialize)] -#[serde(deny_unknown_fields)] -struct ErrorBody { - error: String, -} - #[expect( clippy::needless_pass_by_value, reason = "consume transport errors at the redaction boundary so no source chain escapes" @@ -528,22 +205,9 @@ fn http_error(error: reqwest::Error) -> PreparationError { } } -fn status_error(status: StatusCode) -> Option<(&'static str, PreparationError)> { - Some(match status.as_u16() { - 400 => ("invalid_input", PreparationError::InvalidResource), - 401 => ("unauthenticated", PreparationError::Unauthenticated), - 403 => ("forbidden", PreparationError::Forbidden), - 404 => ("not_found", PreparationError::Missing), - 413 => ("limit_exceeded", PreparationError::SizeLimit), - 426 => ("unsupported_version", PreparationError::UnsupportedVersion), - 503 => ("unavailable", PreparationError::Unavailable), - 504 => ("deadline", PreparationError::Deadline), - _ => return None, - }) -} - #[cfg(test)] mod tests { + use crate::wire::Exchanger as _; use std::env::{current_exe, var}; use std::io::ErrorKind; use std::net::TcpListener; diff --git a/crates/edgezero-store-celld/src/kv.rs b/crates/edgezero-store-celld/src/kv.rs index 2747329d8..e1dfc669c 100644 --- a/crates/edgezero-store-celld/src/kv.rs +++ b/crates/edgezero-store-celld/src/kv.rs @@ -25,6 +25,7 @@ use url::Url; use crate::PreparationError; use crate::client::{Exchange, ResponseKind, ScopedClient}; use crate::settings::{CelldPreparationLimits, valid_key}; +use crate::wire::Exchanger as _; const MAX_PROVIDER_CURSOR: usize = 8_192; const MAX_SERVICE_CURSOR: usize = 2_048; @@ -363,6 +364,7 @@ fn kv_error(error: PreparationError) -> KvError { | PreparationError::Malformed | PreparationError::UnsupportedVersion | PreparationError::InstanceChanged + | PreparationError::PinnedIdentityMismatch | PreparationError::Unavailable | PreparationError::Deadline => KvError::Unavailable, } diff --git a/crates/edgezero-store-celld/src/lib.rs b/crates/edgezero-store-celld/src/lib.rs index 172192d3b..f67a18ea8 100644 --- a/crates/edgezero-store-celld/src/lib.rs +++ b/crates/edgezero-store-celld/src/lib.rs @@ -18,13 +18,23 @@ pub mod settings; mod client; #[cfg(all(not(target_arch = "wasm32"), feature = "kv"))] mod kv; +#[cfg(feature = "portable-records")] +pub mod portable; #[cfg(all(not(target_arch = "wasm32"), feature = "kv"))] mod preparation; -#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] +#[cfg(any( + all(not(target_arch = "wasm32"), feature = "records"), + feature = "portable-records" +))] mod records; #[cfg(test)] #[cfg(all(not(target_arch = "wasm32"), feature = "kv"))] mod test_support; +#[cfg(any( + all(not(target_arch = "wasm32"), feature = "kv"), + feature = "portable-records" +))] +mod wire; #[cfg(all(not(target_arch = "wasm32"), feature = "kv"))] pub use preparation::{CelldPreparation, PreparationStats}; @@ -59,14 +69,16 @@ pub enum PreparationError { UnsupportedVersion, #[error("store instance changed")] InstanceChanged, + #[error("pinned identity mismatch")] + PinnedIdentityMismatch, #[error("provider unavailable")] Unavailable, #[error("deadline exceeded")] Deadline, - #[cfg(feature = "records")] + #[cfg(feature = "record-wire")] #[error("write precondition failed")] PreconditionFailed, - #[cfg(feature = "records")] + #[cfg(feature = "record-wire")] #[error("mutation may have committed")] MutationUncertain, } diff --git a/crates/edgezero-store-celld/src/portable.rs b/crates/edgezero-store-celld/src/portable.rs new file mode 100644 index 000000000..da789f025 --- /dev/null +++ b/crates/edgezero-store-celld/src/portable.rs @@ -0,0 +1,290 @@ +//! Portable celld record provider over `EdgeZero` outbound HTTP. +//! +//! Only authenticated HTTPS access is supported. The bearer token comes from a +//! logical secrets store, the store instance from offline preflight. Request and +//! response policy is the native client's, in [`crate::wire`]; no request is retried. + +#![expect( + clippy::arbitrary_source_item_ordering, + reason = "keep the prepared state, its request-local exchanger and error mapping in lifecycle order" +)] + +use std::fmt; +use std::sync::Arc; +use std::time::Duration; + +use async_trait::async_trait; +use bytes::Bytes; +use edgezero_core::error::EdgeError; +use edgezero_core::error_detail::ProviderFailurePhase; +use edgezero_core::http::{HeaderValue, Method, Uri}; +use edgezero_core::key_value_store::KvStore; +use edgezero_core::outbound::{HttpClient, OutboundRequest, ResponseDecoding}; +use edgezero_core::record_store::{RecordBinding, RecordLayout}; +use edgezero_core::store_registry::BoundSecretStore; +use edgezero_core::time::{Deadline, MonotonicClock}; +use futures_util::lock::Mutex; +use url::Url; + +use crate::PreparationError; +use crate::records::{CelldRecordKvStore, instance_bytes, record_binding}; +use crate::settings::{ + CelldAccessToken, CelldPreparationLimits, CelldRecordsSettings, celld_token_key, +}; +use crate::wire::{self, ERROR_CAP, Exchange, Exchanger, Head, ResponseKind}; + +struct Shared { + endpoint: Url, + instance: [u8; 22], + limits: CelldPreparationLimits, + secrets: BoundSecretStore, + store: String, + token_key: String, +} + +/// Validated settings, pinned instance and secrets reference for one KV ID. +/// +/// Building it performs no I/O and reads no secret. It is `Send + Sync` and is +/// kept for the life of the application; [`Self::bind`] is cheap and per request. +pub struct PreparedCelldRecords { + binding: RecordBinding, + shared: Arc, +} + +impl fmt::Debug for PreparedCelldRecords { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("PreparedCelldRecords") + .finish_non_exhaustive() + } +} + +impl PreparedCelldRecords { + /// Builds the record binding from configuration alone. + /// + /// `secrets` must be the bound logical store named by the binding's `token_secret`. + /// + /// # Errors + /// Rejects anything but authenticated HTTPS with a `token_secret`, a missing or + /// malformed pinned instance, and a KV ID outside `[a-z0-9_]`. + #[inline] + pub fn new( + kv_id: &str, + settings: &CelldRecordsSettings, + layout: &RecordLayout, + secrets: BoundSecretStore, + ) -> Result { + if !valid_portable_id(kv_id) { + return Err(PreparationError::InvalidBinding); + } + let endpoint = settings.portable_endpoint()?; + let pinned = settings + .pinned + .as_ref() + .ok_or(PreparationError::InvalidBinding)?; + let instance = instance_bytes(&pinned.instance)?; + Ok(Self { + binding: record_binding(&endpoint, &settings.store, &pinned.instance, layout)?, + shared: Arc::new(Shared { + endpoint, + instance, + limits: CelldPreparationLimits::PORTABLE, + secrets, + store: settings.store.clone(), + token_key: celld_token_key(kv_id), + }), + }) + } + + /// The configured record binding. No I/O. + #[inline] + #[must_use] + pub const fn record_binding(&self) -> &RecordBinding { + &self.binding + } + + /// A request-bound store over `client`. The token is read on its first + /// operation and reused only by this store. + #[inline] + #[must_use] + pub fn bind(&self, client: HttpClient) -> impl KvStore + use<> { + let clock = client.time().clock().clone(); + CelldRecordKvStore::pinned( + Arc::new(PortableExchanger { + authorization: Mutex::new(None), + client, + clock, + shared: Arc::clone(&self.shared), + }), + self.binding.clone(), + self.shared.instance, + self.shared.limits, + self.shared.store.clone(), + ) + } +} + +/// One request's exchanger. The bearer header cache lives and dies with it. +struct PortableExchanger { + authorization: Mutex>, + client: HttpClient, + clock: MonotonicClock, + shared: Arc, +} + +impl PortableExchanger { + async fn authorization(&self) -> Result { + let mut cached = self.authorization.lock().await; + if let Some(header) = cached.as_ref() { + return Ok(header.clone()); + } + let bytes = self + .shared + .secrets + .require_bytes(&self.shared.token_key) + .await + .map_err(|_error| PreparationError::Credentials)?; + let text = + String::from_utf8(bytes.to_vec()).map_err(|_error| PreparationError::Credentials)?; + let header = wire::authorization(&CelldAccessToken::new(text.trim().to_owned())?)?; + *cached = Some(header.clone()); + Ok(header) + } + + fn request( + &self, + method: Method, + url: &Url, + body: Option, + cap: usize, + deadline: Deadline, + ) -> Result { + let uri: Uri = url + .as_str() + .parse() + .map_err(|_error| PreparationError::InvalidEndpoint)?; + let response_cap = + u64::try_from(cap.max(ERROR_CAP)).map_err(|_error| PreparationError::SizeLimit)?; + let mut request = OutboundRequest::new(method, uri) + .map_err(|_error| PreparationError::InvalidEndpoint)? + .deadline(deadline) + .connect_timeout(Duration::from_millis(self.shared.limits.connect_timeout_ms)) + .response_decoding(ResponseDecoding::Original) + .max_response_bytes(response_cap); + if let Some(payload) = body { + request = request.body(payload); + } + Ok(request) + } +} + +#[expect( + clippy::arbitrary_source_item_ordering, + reason = "keep deadlines ahead of the request lifecycle, as in the native client" +)] +#[async_trait(?Send)] +impl Exchanger for PortableExchanger { + fn deadline(&self) -> Result { + self.clock + .now() + .checked_add(Duration::from_millis( + self.shared.limits.operation_timeout_ms, + )) + .map(Deadline::at_instant) + .ok_or(PreparationError::Deadline) + } + + fn check(&self, deadline: Deadline) -> Result { + deadline + .remaining_at(self.clock.now()) + .ok_or(PreparationError::Deadline) + } + + fn url(&self, store: &str, resource: &str) -> Result { + wire::store_url(&self.shared.endpoint, store, resource) + } + + async fn execute( + &self, + method: Method, + url: Url, + body: Option, + cap: usize, + deadline: Deadline, + kind: ResponseKind, + ) -> Result { + // Every failure before the request is handed to the client is definitive. + self.check(deadline)?; + let authorization = self.authorization().await?; + let headers = wire::request_headers(kind, Some(&authorization), body.is_some())?; + let mut request = self.request(method.clone(), &url, body, cap, deadline)?; + request.headers_mut().extend(headers); + let response = match self.client.send(request).await { + Ok(response) => response, + Err(error) if not_dispatched(&error) => return Err(PreparationError::Unavailable), + Err(error) => return wire::finish(kind, Err(transport_error(&error)), false), + }; + let status = response.status(); + let mut definitive_rejection = false; + let result = match wire::head(kind, &method, status, response.headers(), cap) { + Ok(Head::Complete(exchange)) => Ok(exchange), + Ok(Head::Body { + cap: body_cap, + instance, + success, + }) => match u64::try_from(body_cap) { + Ok(limit) => match response.into_bytes_bounded_until(limit, deadline).await { + Ok(bytes) => wire::body( + kind, + status, + instance, + success, + bytes.to_vec(), + &mut definitive_rejection, + ), + Err(error) => Err(transport_error(&error)), + }, + Err(_overflow) => Err(PreparationError::SizeLimit), + }, + Err(error) => Err(error), + }; + let checked = self.check(deadline).and_then(|_remaining| result); + wire::finish(kind, checked, definitive_rejection) + } +} + +/// Facade validation and pre-dispatch adapter phases never reached the network. +fn not_dispatched(error: &EdgeError) -> bool { + matches!( + error, + EdgeError::Validation { .. } | EdgeError::BadRequest { .. } + ) || error.provider_failure_detail().is_some_and(|detail| { + matches!( + detail.phase(), + ProviderFailurePhase::BackendRegistration | ProviderFailurePhase::RequestPreparation + ) + }) +} + +fn transport_error(error: &EdgeError) -> PreparationError { + if matches!(error, EdgeError::GatewayTimeout { .. }) { + PreparationError::Deadline + } else if matches!(error, EdgeError::ResponseTooLarge { .. }) { + PreparationError::SizeLimit + } else { + PreparationError::Unavailable + } +} + +/// Lowercase ASCII, digits and underscore, so uppercased key names cannot collide. +fn valid_portable_id(id: &str) -> bool { + !id.is_empty() + && id + .bytes() + .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_') +} + +#[cfg(test)] +#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] +#[path = "portable_tests.rs"] +mod tests; diff --git a/crates/edgezero-store-celld/src/portable_tests.rs b/crates/edgezero-store-celld/src/portable_tests.rs new file mode 100644 index 000000000..cec7323a2 --- /dev/null +++ b/crates/edgezero-store-celld/src/portable_tests.rs @@ -0,0 +1,359 @@ +//! The portable exchanger through a real `HttpClient` against the scripted service. +//! Production bindings require HTTPS; these tests construct the exchanger directly +//! over loopback HTTP to observe its requests. Real TLS is proven under Viceroy. + +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; + +use bytes::Bytes; +use edgezero_adapter_axum::outbound::AxumOutboundClient; +use edgezero_adapter_axum::outbound_executor::AxumOutboundExecutor; +use edgezero_core::config_store::BoundedStoreRead; +use edgezero_core::key_value_store::{KvError, KvStore as _}; +use edgezero_core::outbound::HttpClient; +use edgezero_core::record_store::{ + RecordKeyLayout, RecordLayout, RecordWrite, RecordWriteMode, RecordWriteOutcome, +}; +use edgezero_core::secret_store::{InMemorySecretStore, SecretError, SecretHandle, SecretStore}; +use edgezero_core::store_registry::BoundSecretStore; +use edgezero_core::time::{Deadline, MonotonicClock}; +use futures_util::lock::Mutex; +use serde_json::json; +use url::Url; + +use super::{PortableExchanger, PreparedCelldRecords, Shared}; +use crate::PreparationError; +use crate::records::{CelldRecordKvStore, record_binding}; +use crate::settings::{CelldPreparationLimits, CelldRecordsSettings, celld_token_key}; +use crate::test_support::{Fixture, Reply}; + +const INSTANCE: &str = "AAAAAAAAAAAAAAAAAAAAAA"; +const TOKEN: &str = "portable-test-bearer-credential-32-bytes"; + +struct Layout; +impl RecordKeyLayout for Layout { + fn id(&self) -> &'static str { + "fixture-groups" + } + fn version(&self) -> u32 { + 1 + } + fn validate(&self) -> Result<(), KvError> { + Ok(()) + } + fn partition_prefix<'key>(&self, key: &'key str) -> Result<&'key str, KvError> { + key.find('/') + .and_then(|index| key.get(..=index)) + .ok_or_else(|| KvError::Validation("missing fixture group".to_owned())) + } + fn validate_partition(&self, prefix: &str) -> Result<(), KvError> { + if prefix.ends_with('/') && prefix.matches('/').count() == 1 && prefix.len() > 1 { + Ok(()) + } else { + Err(KvError::Validation("invalid fixture group".to_owned())) + } + } +} + +struct Counting { + inner: InMemorySecretStore, + reads: Arc, +} + +#[async_trait::async_trait(?Send)] +impl SecretStore for Counting { + async fn get_bytes(&self, store_name: &str, key: &str) -> Result, SecretError> { + self.reads.fetch_add(1, Ordering::SeqCst); + self.inner.get_bytes(store_name, key).await + } + + 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> { + self.reads.fetch_add(1, Ordering::SeqCst); + self.inner + .get_bytes_bounded( + store_name, + key, + clock, + deadline, + max_backend_bytes, + max_value_bytes, + ) + .await + } +} + +fn layout() -> RecordLayout { + RecordLayout::new(Layout).unwrap() +} + +fn headers() -> String { + format!( + "x-edgezero-store-version: 1\r\nx-edgezero-record-version: 1\r\nx-edgezero-store-instance: {INSTANCE}\r\n" + ) +} + +fn ack() -> Reply { + Reply::custom(204, "application/json", &headers(), b"") +} + +fn error(status: u16, category: &str) -> Reply { + Reply::custom( + status, + "application/json", + &headers(), + &serde_json::to_vec(&json!({ "error": category })).unwrap(), + ) +} + +fn secrets(token: bool) -> (BoundSecretStore, Arc) { + let key = format!("stores/{}", celld_token_key("sessions")); + let entries = if token { + vec![(key, TOKEN.to_owned())] + } else { + Vec::new() + }; + let reads = Arc::new(AtomicUsize::new(0)); + let store = Counting { + inner: InMemorySecretStore::new(entries), + reads: Arc::clone(&reads), + }; + ( + BoundSecretStore::new(SecretHandle::new(Arc::new(store)), "stores".to_owned()), + reads, + ) +} + +fn store( + fixture: &Fixture, + executor: &AxumOutboundExecutor, + secrets: BoundSecretStore, +) -> CelldRecordKvStore { + let endpoint = Url::parse(fixture.endpoint()).unwrap(); + let client = HttpClient::with_client(AxumOutboundClient::try_new(executor.handle()).unwrap()); + let instance = *b"AAAAAAAAAAAAAAAAAAAAAA"; + let limits = CelldPreparationLimits::PORTABLE; + CelldRecordKvStore::pinned( + Arc::new(PortableExchanger { + authorization: Mutex::new(None), + clock: client.time().clock().clone(), + client, + shared: Arc::new(Shared { + endpoint: endpoint.clone(), + instance, + limits, + secrets, + store: "state".to_owned(), + token_key: celld_token_key("sessions"), + }), + }), + record_binding(&endpoint, "state", INSTANCE, &layout()).unwrap(), + instance, + limits, + "state".to_owned(), + ) +} + +fn write(mode: RecordWriteMode) -> RecordWrite<'static> { + RecordWrite { + body: b"\0\xff", + metadata: Some("\u{e9}"), + ttl: None, + mode, + } +} + +#[tokio::test(flavor = "current_thread")] +async fn requests_carry_bearer_instance_and_fresh_mutation_ids_with_one_token_read() { + let fixture = Fixture::new(vec![ack(), ack()]).await; + let mut executor = AxumOutboundExecutor::new(); + let (secrets, reads) = secrets(true); + let records = store(&fixture, &executor, secrets); + executor + .run_until(async { + let partition = records + .record_binding() + .unwrap() + .layout + .resolve("group/a") + .unwrap(); + for key in ["group/a", "group/b"] { + assert_eq!( + records + .record_insert(key, &partition, write(RecordWriteMode::Add)) + .await + .unwrap(), + RecordWriteOutcome::Written + ); + } + }) + .await; + assert_eq!(reads.load(Ordering::SeqCst), 1); + let requests = fixture.requests().await; + assert_eq!(requests.len(), 2); + for request in &requests { + assert_eq!(request.method, "POST"); + assert_eq!( + request.authorization.as_deref(), + Some(format!("Bearer {TOKEN}").as_str()) + ); + assert_eq!(request.record_version.as_deref(), Some("1")); + assert_eq!(request.expected_instance.as_deref(), Some(INSTANCE)); + assert_eq!(request.encoding.as_deref(), Some("identity")); + assert!(request.mutation_id.is_some()); + } + assert_ne!(requests[0].mutation_id, requests[1].mutation_id); +} + +#[tokio::test(flavor = "current_thread")] +async fn outcomes_use_the_native_classifier_without_retry() { + for (reply, mode, expected) in [ + ( + error(412, "precondition_failed"), + RecordWriteMode::Add, + Ok(RecordWriteOutcome::PreconditionFailed), + ), + ( + error(503, "unavailable"), + RecordWriteMode::Add, + Err(KvError::MutationUncertain), + ), + ( + Reply::Drop, + RecordWriteMode::Overwrite, + Err(KvError::MutationUncertain), + ), + ( + error(403, "forbidden"), + RecordWriteMode::Overwrite, + Err(KvError::Unavailable), + ), + ] { + let fixture = Fixture::new(vec![reply]).await; + let mut executor = AxumOutboundExecutor::new(); + let (secrets, _reads) = secrets(true); + let records = store(&fixture, &executor, secrets); + let outcome = executor + .run_until(async { + let partition = records + .record_binding() + .unwrap() + .layout + .resolve("group/a") + .unwrap(); + records + .record_insert("group/a", &partition, write(mode)) + .await + }) + .await; + assert_eq!( + outcome.map_err(|failure| failure.to_string()), + expected.map_err(|failure: KvError| failure.to_string()) + ); + assert_eq!(fixture.count().await, 1, "no retry"); + } +} + +#[tokio::test(flavor = "current_thread")] +async fn a_missing_token_fails_before_dispatch() { + let fixture = Fixture::new(vec![ack()]).await; + let mut executor = AxumOutboundExecutor::new(); + let (secrets, _reads) = secrets(false); + let records = store(&fixture, &executor, secrets); + let outcome = executor + .run_until(async { + let partition = records + .record_binding() + .unwrap() + .layout + .resolve("group/a") + .unwrap(); + records + .record_insert("group/a", &partition, write(RecordWriteMode::Add)) + .await + }) + .await; + assert!(matches!(outcome, Err(KvError::Unavailable))); + assert_eq!(fixture.count().await, 0); +} + +#[test] +fn portable_bindings_require_authenticated_https_and_a_pinned_instance() { + let settings = + |value: serde_json::Value| serde_json::from_value::(value).unwrap(); + let valid = json!({ + "endpoint": "https://celld.example.net", + "store": "sessions", + "pinned": { "instance": INSTANCE }, + "access": { "mode": "authenticated", "token_secret": { "secrets": "stores" } }, + }); + let (bound, reads) = secrets(true); + let prepared = + PreparedCelldRecords::new("sessions", &settings(valid.clone()), &layout(), bound).unwrap(); + assert_eq!( + prepared.record_binding().scope, + record_binding( + &Url::parse("https://celld.example.net").unwrap(), + "sessions", + INSTANCE, + &layout() + ) + .unwrap() + .scope + ); + assert_eq!(prepared.record_binding().max_metadata_bytes, 1_024); + assert_eq!(reads.load(Ordering::SeqCst), 0); + let with = |field: &str, value: serde_json::Value| { + let mut changed = valid.clone(); + changed[field] = value; + changed + }; + let mut unpinned = valid.clone(); + unpinned.as_object_mut().unwrap().remove("pinned"); + for (input, error) in [ + ( + with("endpoint", json!("http://celld.example.net")), + PreparationError::InvalidEndpoint, + ), + ( + with( + "access", + json!({ "mode": "authenticated", "token_env": "TOKEN" }), + ), + PreparationError::InvalidBinding, + ), + ( + with("access", json!({ "mode": "trusted-network" })), + PreparationError::InvalidBinding, + ), + (unpinned, PreparationError::InvalidBinding), + ] { + let (rejected_store, _reads) = secrets(true); + assert_eq!( + PreparedCelldRecords::new( + "sessions", + &settings(input.clone()), + &layout(), + rejected_store, + ) + .map(|_prepared| ()) + .unwrap_err(), + error, + "{input}" + ); + } + let (uppercase_store, _reads) = secrets(true); + assert_eq!( + PreparedCelldRecords::new("Sessions", &settings(valid), &layout(), uppercase_store) + .map(|_prepared| ()) + .unwrap_err(), + PreparationError::InvalidBinding + ); +} diff --git a/crates/edgezero-store-celld/src/preparation.rs b/crates/edgezero-store-celld/src/preparation.rs index cb87dd32d..c84cd8b66 100644 --- a/crates/edgezero-store-celld/src/preparation.rs +++ b/crates/edgezero-store-celld/src/preparation.rs @@ -18,10 +18,12 @@ use crate::PreparationError; use crate::client::ScopedClient; use crate::kv::CelldKvStore; #[cfg(feature = "records")] -use crate::records::CelldRecordKvStore; +use crate::records::{CelldRecordKvStore, read_capabilities}; use crate::settings::{ CelldAccess, CelldAccessToken, CelldKvSettings, CelldPreparationLimits, endpoint, }; +#[cfg(feature = "records")] +use crate::settings::{CelldPinnedIdentity, CelldRecordsSettings}; /// Aggregate counters, not process memory measurements. Metadata counts bounded /// identifier storage plus conservative per-binding overhead. @@ -114,9 +116,27 @@ impl CelldPreparation { settings: &CelldKvSettings, layout: &RecordLayout, token: Option<&CelldAccessToken>, + ) -> Result { + self.prepare_record_store_pinned(settings, layout, token, None) + .await + } + + /// Prepares like [`Self::prepare_record_store`], then requires the service instance + /// to equal `pinned` when one is supplied. + /// + /// # Errors + /// Returns [`PreparationError::PinnedIdentityMismatch`] for a different instance. + #[cfg(feature = "records")] + #[inline] + pub async fn prepare_record_store_pinned( + &mut self, + settings: &CelldKvSettings, + layout: &RecordLayout, + token: Option<&CelldAccessToken>, + pinned: Option<&CelldPinnedIdentity>, ) -> Result { self.begin()?; - let result = self.records_inner(settings, layout, token).await; + let result = self.records_inner(settings, layout, token, pinned).await; if result.is_ok() { self.poisoned = false; } @@ -129,6 +149,7 @@ impl CelldPreparation { settings: &CelldKvSettings, layout: &RecordLayout, token: Option<&CelldAccessToken>, + pinned: Option<&CelldPinnedIdentity>, ) -> Result { settings.validate()?; self.charge_mapping(&[settings.endpoint.len(), settings.store.len()])?; @@ -143,10 +164,50 @@ impl CelldPreparation { self.deadline, ) .await?; + if pinned.is_some_and(|expected| !store.has_instance(&expected.instance)) { + return Err(PreparationError::PinnedIdentityMismatch); + } self.check()?; Ok(KvHandle::new(Arc::new(store))) } + /// Offline preflight for a portable binding. Reads the read-only capabilities with + /// `token`, rejects every service native preparation rejects and returns the + /// instance to pin. It never writes a probe record. + /// + /// `token_env` names the variable that supplied `token`; it only identifies the client. + /// + /// # Errors + /// Rejects a binding that is not portable, and any preparation failure. + #[cfg(feature = "records")] + #[inline] + pub async fn preflight_record_store( + &mut self, + settings: &CelldRecordsSettings, + token_env: &str, + token: &CelldAccessToken, + ) -> Result { + settings.portable_endpoint()?; + let native = CelldKvSettings { + endpoint: settings.endpoint.clone(), + access: CelldAccess::Authenticated { + token_env: token_env.to_owned(), + }, + store: settings.store.clone(), + }; + self.begin()?; + native.validate()?; + self.charge_mapping(&[native.endpoint.len(), native.store.len()])?; + let (_, client) = self.client(&native.endpoint, &native.access, Some(token))?; + let capabilities = + read_capabilities(client.as_ref(), &native.store, self.limits, self.deadline).await?; + self.check()?; + self.poisoned = false; + Ok(CelldPinnedIdentity { + instance: capabilities.instance, + }) + } + /// Safe aggregate counters; no resource or authorization identifiers. #[inline] #[must_use] diff --git a/crates/edgezero-store-celld/src/records.rs b/crates/edgezero-store-celld/src/records.rs index 26f2b1c8f..e3bf0efd0 100644 --- a/crates/edgezero-store-celld/src/records.rs +++ b/crates/edgezero-store-celld/src/records.rs @@ -1,45 +1,91 @@ //! Prepared records over the EdgeZero-owned service on official stock celld. //! Ordinary and record operations share its rows and generation history. +//! +//! The record logic is transport-independent. Native preparation reads the service +//! capabilities; portable bindings use the instance pinned by offline preflight. #![expect( clippy::arbitrary_source_item_ordering, - reason = "keep the prepared store and native operations before wire models and validation" + reason = "keep the prepared store and record operations before wire models and validation" )] use std::sync::Arc; use std::time::Duration; +use async_trait::async_trait; use base64::Engine as _; use base64::engine::general_purpose::{STANDARD, URL_SAFE_NO_PAD}; use bytes::Bytes; +use edgezero_core::http::Method; use edgezero_core::key_value_store::{KvError, KvHandle, KvPage, KvStore}; use edgezero_core::record_store::{ Record, RecordBinding, RecordGeneration, RecordLayout, RecordPage, RecordPartition, RecordWrite, RecordWriteMode, RecordWriteOutcome, }; +#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] use edgezero_core::time::Deadline; -use reqwest::Method; use serde::{Deserialize, Deserializer, Serialize}; use sha2::{Digest as _, Sha256}; use url::Url; use crate::PreparationError; -use crate::client::{ResponseKind, ScopedClient}; +#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] +use crate::client::ScopedClient; use crate::settings::{CelldPreparationLimits, valid_key}; +use crate::wire::{Exchanger, ResponseKind}; -const MAX_METADATA_BYTES: usize = 1_024; +pub(crate) const MAX_METADATA_BYTES: usize = 1_024; const MAX_PROVIDER_CURSOR: usize = 8_192; const MAX_SERVICE_CURSOR: usize = 2_048; -pub(crate) struct CelldRecordKvStore { +pub(crate) struct CelldRecordKvStore { binding: RecordBinding, - client: Arc, + client: Arc, instance: [u8; 22], limits: CelldPreparationLimits, store: String, } -impl CelldRecordKvStore { +/// The binding every transport reports for one store instance. +pub(crate) fn record_binding( + endpoint: &Url, + store: &str, + instance: &str, + layout: &RecordLayout, +) -> Result { + let scope = fingerprint(&[ + "edgezero-celld-store", + "rows-v1", + "records-v1", + endpoint.as_str(), + store, + instance, + ])?; + Ok(RecordBinding { + layout: layout.clone(), + scope, + format: "celld-store-records-v1".to_owned(), + max_metadata_bytes: MAX_METADATA_BYTES, + }) +} + +/// A 22-byte URL-safe store instance, as the service reports it. +pub(crate) fn instance_bytes(instance: &str) -> Result<[u8; 22], PreparationError> { + let bytes: [u8; 22] = instance + .as_bytes() + .try_into() + .map_err(|_error| PreparationError::Malformed)?; + if !bytes + .iter() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_')) + { + return Err(PreparationError::Malformed); + } + Ok(bytes) +} + +#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] +impl CelldRecordKvStore { pub(crate) async fn prepare( client: Arc, endpoint: &Url, @@ -48,63 +94,12 @@ impl CelldRecordKvStore { layout: &RecordLayout, preparation_deadline: Deadline, ) -> Result { - let deadline = Deadline::at_instant( - preparation_deadline - .instant() - .min(client.deadline()?.instant()), - ); - let exchange = client - .execute( - Method::GET, - client.url(&store, "capabilities")?, - None, - usize::try_from(limits.max_page_bytes) - .map_err(|_error| PreparationError::InvalidLimits)?, - deadline, - ResponseKind::RecordCapabilities, - ) - .await?; - let capabilities: Capabilities = - serde_json::from_slice(&exchange.body.ok_or(PreparationError::Malformed)?) - .map_err(|_error| PreparationError::Malformed)?; - if capabilities.service != "edgezero-celld-store" - || capabilities.protocol != 1 - || capabilities.format != "rows-v1" - || capabilities.pagination != "keyset" - || !capabilities.no_expiry - || !capabilities.mutation_ledger - || !capabilities.records - || capabilities.record_protocol != 1 - || capabilities.max_metadata_bytes != MAX_METADATA_BYTES - || capabilities.max_value_bytes == 0 - { - return Err(PreparationError::UnsupportedVersion); - } - if exchange.instance.as_deref() != Some(capabilities.instance.as_str()) { - return Err(PreparationError::Malformed); - } - let instance = capabilities - .instance - .as_bytes() - .try_into() - .map_err(|_error| PreparationError::Malformed)?; - let scope = fingerprint(&[ - "edgezero-celld-store", - "rows-v1", - "records-v1", - endpoint.as_str(), - &store, - &capabilities.instance, - ])?; + let capabilities = + read_capabilities(client.as_ref(), &store, limits, preparation_deadline).await?; limits.max_value_bytes = limits.max_value_bytes.min(capabilities.max_value_bytes); - client.check(deadline)?; + let instance = instance_bytes(&capabilities.instance)?; Ok(Self { - binding: RecordBinding { - layout: layout.clone(), - scope, - format: "celld-store-records-v1".to_owned(), - max_metadata_bytes: MAX_METADATA_BYTES, - }, + binding: record_binding(endpoint, &store, &capabilities.instance, layout)?, client, instance, limits, @@ -112,6 +107,96 @@ impl CelldRecordKvStore { }) } + /// Whether preparation observed exactly this pinned instance. + pub(crate) fn has_instance(&self, instance: &str) -> bool { + self.instance.as_slice() == instance.as_bytes() + } +} + +/// Native read-only capability exchange. It never writes a probe record. +#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] +pub(crate) async fn read_capabilities( + client: &ScopedClient, + store: &str, + limits: CelldPreparationLimits, + preparation_deadline: Deadline, +) -> Result { + let deadline = Deadline::at_instant( + preparation_deadline + .instant() + .min(client.deadline()?.instant()), + ); + let exchange = client + .execute( + Method::GET, + client.url(store, "capabilities")?, + None, + usize::try_from(limits.max_page_bytes) + .map_err(|_error| PreparationError::InvalidLimits)?, + deadline, + ResponseKind::RecordCapabilities, + ) + .await?; + let capabilities: Capabilities = + serde_json::from_slice(&exchange.body.ok_or(PreparationError::Malformed)?) + .map_err(|_error| PreparationError::Malformed)?; + if capabilities.service != "edgezero-celld-store" + || capabilities.protocol != 1 + || capabilities.format != "rows-v1" + || capabilities.pagination != "keyset" + || !capabilities.no_expiry + || !capabilities.mutation_ledger + || !capabilities.records + || capabilities.record_protocol != 1 + || capabilities.max_metadata_bytes != MAX_METADATA_BYTES + || capabilities.max_value_bytes == 0 + { + return Err(PreparationError::UnsupportedVersion); + } + if exchange.instance.as_deref() != Some(capabilities.instance.as_str()) { + return Err(PreparationError::Malformed); + } + instance_bytes(&capabilities.instance)?; + client.check(deadline)?; + Ok(ServiceCapabilities { + instance: capabilities.instance, + max_value_bytes: capabilities.max_value_bytes, + }) +} + +/// The capability facts preflight and native preparation keep. +#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] +pub(crate) struct ServiceCapabilities { + pub instance: String, + pub max_value_bytes: u64, +} + +impl CelldRecordKvStore { + /// Binds a pinned instance without any I/O. Every request still carries the + /// expected instance, so a reset store fails until the binding is re-pinned. + #[cfg_attr( + not(feature = "portable-records"), + expect( + dead_code, + reason = "only portable bindings construct from a pinned instance" + ) + )] + pub(crate) fn pinned( + client: Arc, + binding: RecordBinding, + instance: [u8; 22], + limits: CelldPreparationLimits, + store: String, + ) -> Self { + Self { + binding, + client, + instance, + limits, + store, + } + } + fn point_url(&self, resource: &str, key: &str) -> Result { self.binding.layout.resolve(key)?; let mut url = self.client.url(&self.store, resource).map_err(kv_error)?; @@ -373,8 +458,8 @@ impl CelldRecordKvStore { } } -#[async_trait::async_trait(?Send)] -impl KvStore for CelldRecordKvStore { +#[async_trait(?Send)] +impl KvStore for CelldRecordKvStore { async fn delete(&self, key: &str) -> Result<(), KvError> { self.delete_value(key).await } @@ -476,6 +561,7 @@ impl KvStore for CelldRecordKvStore { } } +#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] #[derive(Deserialize)] #[serde(deny_unknown_fields)] struct Capabilities { @@ -627,11 +713,13 @@ fn kv_error(error: PreparationError) -> KvError { | PreparationError::Malformed | PreparationError::UnsupportedVersion | PreparationError::InstanceChanged + | PreparationError::PinnedIdentityMismatch | PreparationError::Unavailable | PreparationError::Deadline => KvError::Unavailable, } } #[cfg(test)] +#[cfg(all(not(target_arch = "wasm32"), feature = "records"))] #[path = "records_tests.rs"] mod tests; diff --git a/crates/edgezero-store-celld/src/records_tests.rs b/crates/edgezero-store-celld/src/records_tests.rs index ae84ae0a7..8eeb670b9 100644 --- a/crates/edgezero-store-celld/src/records_tests.rs +++ b/crates/edgezero-store-celld/src/records_tests.rs @@ -14,8 +14,9 @@ use url::Url; use super::CelldRecordKvStore; use crate::client::ScopedClient; -use crate::settings::{CelldAccess, CelldKvSettings, CelldPreparationLimits}; +use crate::settings::{CelldAccess, CelldKvSettings, CelldPinnedIdentity, CelldPreparationLimits}; use crate::test_support::{Fixture, Reply}; +use crate::wire::Exchanger as _; use crate::{CelldPreparation, PreparationError}; const INSTANCE: &str = "AAAAAAAAAAAAAAAAAAAAAA"; @@ -75,7 +76,7 @@ fn capabilities() -> Reply { async fn store_with_limits( fixture: &Fixture, limits: CelldPreparationLimits, -) -> CelldRecordKvStore { +) -> CelldRecordKvStore { let endpoint = Url::parse(fixture.endpoint()).unwrap(); let clock = MonotonicClock::default(); let client = Arc::new(ScopedClient::new(endpoint.clone(), None, clock, limits).unwrap()); @@ -91,7 +92,7 @@ async fn store_with_limits( .await .unwrap() } -async fn store(fixture: &Fixture) -> CelldRecordKvStore { +async fn store(fixture: &Fixture) -> CelldRecordKvStore { store_with_limits(fixture, CelldPreparationLimits::default()).await } fn write(mode: RecordWriteMode) -> RecordWrite<'static> { @@ -436,3 +437,33 @@ async fn value_limits_are_effective_and_record_ttl_is_encoded_as_integer_millise ); assert!(serde_json::from_slice::(&requests[2].body).unwrap()["metadata"].is_null()); } + +#[tokio::test(flavor = "current_thread")] +async fn pinned_preparation_requires_the_observed_instance() { + for (pinned, accepted) in [(INSTANCE, true), (OTHER_INSTANCE, false)] { + let fixture = Fixture::new(vec![capabilities()]).await; + let mut prep = + CelldPreparation::new(MonotonicClock::default(), CelldPreparationLimits::default()) + .unwrap(); + let result = prep + .prepare_record_store_pinned( + &settings(&fixture), + &layout(), + None, + Some(&CelldPinnedIdentity { + instance: pinned.to_owned(), + }), + ) + .await; + if accepted { + result.unwrap(); + } else { + assert_eq!( + result.map(|_kv| ()).unwrap_err(), + PreparationError::PinnedIdentityMismatch + ); + } + // Only the read-only capability exchange, never a write probe. + assert_eq!(fixture.count().await, 1); + } +} diff --git a/crates/edgezero-store-celld/src/settings.rs b/crates/edgezero-store-celld/src/settings.rs index c1b703505..fb3efe676 100644 --- a/crates/edgezero-store-celld/src/settings.rs +++ b/crates/edgezero-store-celld/src/settings.rs @@ -74,6 +74,187 @@ impl fmt::Debug for CelldKvSettings { } } +/// A logical secrets store ID. The token key derives from the KV ID and is never configured. +#[derive(Clone, Deserialize, Serialize, Eq, PartialEq)] +#[serde(deny_unknown_fields)] +pub struct SecretsReference { + pub secrets: String, +} + +impl fmt::Debug for SecretsReference { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("SecretsReference").finish_non_exhaustive() + } +} + +/// The secret key a portable celld binding reads for KV ID `id`: `KV____CELLD_TOKEN`. +/// Offline preflight reads its token from the environment variable of the same name. +#[inline] +#[must_use] +pub fn celld_token_key(id: &str) -> String { + format!("KV__{}__CELLD_TOKEN", id.to_ascii_uppercase()) +} + +/// Record-binding access policy. `trusted-network` and `token_env` are native-only; +/// portable bindings require `authenticated` with a `token_secret`. +#[derive(Clone, Deserialize, Serialize, Eq, PartialEq)] +#[serde(tag = "mode", rename_all = "kebab-case", deny_unknown_fields)] +pub enum CelldRecordAccess { + TrustedNetwork { + #[serde(default)] + allow_remote_http: bool, + }, + Authenticated { + #[serde(default, skip_serializing_if = "Option::is_none")] + token_env: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + token_secret: Option, + }, +} + +impl fmt::Debug for CelldRecordAccess { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("CelldRecordAccess").finish_non_exhaustive() + } +} + +/// The store instance an offline preflight pinned into the binding. +#[derive(Clone, Deserialize, Serialize, Eq, PartialEq)] +#[serde(deny_unknown_fields)] +pub struct CelldPinnedIdentity { + pub instance: String, +} + +impl fmt::Debug for CelldPinnedIdentity { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("CelldPinnedIdentity") + .finish_non_exhaustive() + } +} + +/// A `celld-records` binding. Debug never exposes the endpoint or store. +#[derive(Clone, Deserialize, Serialize)] +#[serde(deny_unknown_fields)] +pub struct CelldRecordsSettings { + pub endpoint: String, + pub access: CelldRecordAccess, + pub store: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub pinned: Option, +} + +impl fmt::Debug for CelldRecordsSettings { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("CelldRecordsSettings") + .finish_non_exhaustive() + } +} + +impl CelldRecordsSettings { + /// Structural checks valid for any target. No I/O. + /// + /// # Errors + /// Rejects invalid endpoints, aliases, pins, and an authenticated policy + /// without exactly one token source. + #[inline] + pub fn validate(&self) -> Result<(), PreparationError> { + match &self.access { + CelldRecordAccess::TrustedNetwork { allow_remote_http } => { + checked_endpoint(&self.endpoint, Some(*allow_remote_http))?; + } + CelldRecordAccess::Authenticated { + token_env, + token_secret, + } => { + match (token_env, token_secret) { + (Some(name), None) if valid_variable(name) => {} + (None, Some(reference)) if valid_logical_id(&reference.secrets) => {} + _ => return Err(PreparationError::InvalidBinding), + } + checked_endpoint(&self.endpoint, None)?; + } + } + if !valid_alias(&self.store) { + return Err(PreparationError::InvalidResource); + } + if let Some(pinned) = &self.pinned + && !valid_instance(&pinned.instance) + { + return Err(PreparationError::InvalidResource); + } + Ok(()) + } + + /// The native settings Axum prepares. Native keeps `trusted-network` and + /// `token_env`; it has no secrets-store token source. + /// + /// # Errors + /// Rejects a `token_secret` and any structurally invalid binding. + #[inline] + pub fn native_settings(&self) -> Result { + self.validate()?; + let access = match &self.access { + CelldRecordAccess::TrustedNetwork { allow_remote_http } => { + CelldAccess::TrustedNetwork { + allow_remote_http: *allow_remote_http, + } + } + CelldRecordAccess::Authenticated { + token_env: Some(name), + token_secret: None, + } => CelldAccess::Authenticated { + token_env: name.clone(), + }, + CelldRecordAccess::Authenticated { .. } => { + return Err(PreparationError::InvalidBinding); + } + }; + Ok(CelldKvSettings { + endpoint: self.endpoint.clone(), + access, + store: self.store.clone(), + }) + } + + /// The HTTPS endpoint a portable transport uses. Portable access is + /// `authenticated` with a `token_secret` only. + /// + /// # Errors + /// Rejects `trusted-network`, `token_env` and any structurally invalid binding. + #[inline] + pub fn portable_endpoint(&self) -> Result { + self.validate()?; + match &self.access { + CelldRecordAccess::Authenticated { + token_env: None, + token_secret: Some(_), + } => checked_endpoint(&self.endpoint, None), + CelldRecordAccess::Authenticated { .. } | CelldRecordAccess::TrustedNetwork { .. } => { + Err(PreparationError::InvalidBinding) + } + } + } + + /// The logical secrets ID a portable binding reads its token from. + #[inline] + #[must_use] + pub fn token_secret(&self) -> Option<&str> { + match &self.access { + CelldRecordAccess::Authenticated { + token_secret: Some(reference), + .. + } => Some(&reference.secrets), + CelldRecordAccess::Authenticated { .. } | CelldRecordAccess::TrustedNetwork { .. } => { + None + } + } + } +} + /// Captured application bearer token. Debug reveals neither value nor length. #[derive(Clone)] pub struct CelldAccessToken(String); @@ -136,6 +317,18 @@ impl Default for CelldPreparationLimits { } impl CelldPreparationLimits { + /// Enforced defaults for portable bindings: one 1,000 ms operation deadline and a + /// 250 ms connect timeout. Portable bindings perform no preparation. + pub const PORTABLE: Self = Self { + max_remote_values: 1_024, + max_metadata_bytes: 0x0010_0000, + max_value_bytes: 0x0010_0000, + max_page_bytes: 0x0020_0000, + preparation_timeout_ms: 1_000, + operation_timeout_ms: 1_000, + connect_timeout_ms: 250, + }; + /// Checks positive, representable quotas and ordered finite deadlines. /// /// # Errors @@ -163,7 +356,7 @@ impl CelldPreparationLimits { } } -pub(crate) fn endpoint(value: &str, access: &CelldAccess) -> Result { +fn parsed_endpoint(value: &str) -> Result<(Url, bool), PreparationError> { if value.len() > 4_096 || value .bytes() @@ -221,24 +414,66 @@ pub(crate) fn endpoint(value: &str, access: &CelldAccess) -> Result return Err(PreparationError::InvalidEndpoint), }; + Ok((parsed, loopback)) +} + +/// `trusted` is `None` for authenticated access, which always requires HTTPS, or the +/// trusted-network `allow_remote_http` choice. +fn scheme_allowed( + url: &Url, + loopback: bool, + trusted: Option, +) -> Result<(), PreparationError> { + let allowed = match trusted { + None => url.scheme() == "https", + Some(allow_remote_http) => url.scheme() != "http" || loopback || allow_remote_http, + }; + if allowed { + Ok(()) + } else { + Err(PreparationError::InvalidEndpoint) + } +} + +pub(crate) fn endpoint(value: &str, access: &CelldAccess) -> Result { + let (parsed, loopback) = parsed_endpoint(value)?; match access { CelldAccess::Authenticated { token_env } => { if !valid_variable(token_env) { return Err(PreparationError::InvalidBinding); } - if parsed.scheme() != "https" { - return Err(PreparationError::InvalidEndpoint); - } + scheme_allowed(&parsed, loopback, None)?; } CelldAccess::TrustedNetwork { allow_remote_http } => { - if parsed.scheme() == "http" && !loopback && !allow_remote_http { - return Err(PreparationError::InvalidEndpoint); - } + scheme_allowed(&parsed, loopback, Some(*allow_remote_http))?; } } Ok(parsed) } +fn checked_endpoint(value: &str, trusted: Option) -> Result { + let (parsed, loopback) = parsed_endpoint(value)?; + scheme_allowed(&parsed, loopback, trusted)?; + Ok(parsed) +} + +/// A logical store ID: nonempty `[A-Za-z0-9_]`, at most 512 bytes. +fn valid_logical_id(value: &str) -> bool { + !value.is_empty() + && value.len() <= 512 + && value + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || byte == b'_') +} + +/// A store instance as the service reports it: 22 URL-safe base64 bytes. +fn valid_instance(value: &str) -> bool { + value.len() == 22 + && value + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_')) +} + pub(crate) fn valid_alias(value: &str) -> bool { !value.is_empty() && value.len() <= 64 @@ -247,7 +482,10 @@ pub(crate) fn valid_alias(value: &str) -> bool { .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-')) } -#[cfg(all(not(target_arch = "wasm32"), feature = "kv"))] +#[cfg(any( + all(not(target_arch = "wasm32"), feature = "kv"), + feature = "portable-records" +))] pub(crate) fn valid_key(value: &str, empty: bool) -> bool { (empty || !value.is_empty()) && value.len() <= 512 && !value.chars().any(char::is_control) } diff --git a/crates/edgezero-store-celld/src/wire.rs b/crates/edgezero-store-celld/src/wire.rs new file mode 100644 index 000000000..42736479e --- /dev/null +++ b/crates/edgezero-store-celld/src/wire.rs @@ -0,0 +1,481 @@ +//! Transport-neutral store-service exchange policy shared by native and portable clients. +//! +//! Every mutation carries a fresh random ID. The store service records it in the +//! same transaction as the write, so a duplicate delivery inside celld or a proxy +//! cannot apply it twice. No client ever resends a mutation. + +#![expect( + clippy::arbitrary_source_item_ordering, + reason = "keep request construction, response heads, bodies and validators in lifecycle order" +)] + +use std::fmt; +use std::time::Duration; + +use async_trait::async_trait; +use base64::Engine as _; +use base64::engine::general_purpose::URL_SAFE_NO_PAD; +use bytes::Bytes; +use edgezero_core::http::header::{ + ACCEPT_ENCODING, AUTHORIZATION, CONTENT_ENCODING, CONTENT_LENGTH, CONTENT_TYPE, +}; +use edgezero_core::http::{HeaderMap, HeaderValue, Method, StatusCode}; +use edgezero_core::time::Deadline; +use serde::Deserialize; +use url::Url; + +use crate::PreparationError; +use crate::settings::CelldAccessToken; + +pub(crate) const ERROR_CAP: usize = 1_024; +const INSTANCE_HEADER: &str = "x-edgezero-store-instance"; +const MUTATION_HEADER: &str = "x-edgezero-mutation-id"; +const VERSION_HEADER: &str = "x-edgezero-store-version"; +#[cfg(feature = "record-wire")] +const RECORD_HEADER: &str = "x-edgezero-record-version"; +#[cfg(feature = "record-wire")] +const EXPECTED_INSTANCE_HEADER: &str = "x-edgezero-expected-instance"; + +#[derive(Clone, Copy)] +#[cfg_attr( + not(all(not(target_arch = "wasm32"), feature = "kv")), + expect( + dead_code, + reason = "ordinary and capability exchanges are native-only; portable builds send record exchanges" + ) +)] +pub(crate) enum ResponseKind { + Exists, + Mutation, + Page, + Value, + #[cfg(feature = "record-wire")] + RecordCapabilities, + #[cfg(feature = "record-wire")] + RecordExists([u8; 22]), + #[cfg(feature = "record-wire")] + RecordMutation([u8; 22]), + #[cfg(feature = "record-wire")] + RecordPage([u8; 22]), + #[cfg(feature = "record-wire")] + RecordValue([u8; 22]), +} + +impl ResponseKind { + pub(crate) const fn mutation(self) -> bool { + match self { + Self::Mutation => true, + #[cfg(feature = "record-wire")] + Self::RecordMutation(_) => true, + _ => false, + } + } + + const fn json(self) -> bool { + match self { + Self::Page => true, + #[cfg(feature = "record-wire")] + Self::RecordCapabilities | Self::RecordPage(_) | Self::RecordValue(_) => true, + _ => false, + } + } + + const fn optional(self) -> bool { + match self { + Self::Value => true, + #[cfg(feature = "record-wire")] + Self::RecordValue(_) => true, + _ => false, + } + } + + pub(crate) const fn record(self) -> bool { + match self { + #[cfg(feature = "record-wire")] + Self::RecordCapabilities + | Self::RecordExists(_) + | Self::RecordMutation(_) + | Self::RecordPage(_) + | Self::RecordValue(_) => true, + _ => false, + } + } + + const fn expected_instance(self) -> Option<[u8; 22]> { + match self { + #[cfg(feature = "record-wire")] + Self::RecordExists(instance) + | Self::RecordMutation(instance) + | Self::RecordPage(instance) + | Self::RecordValue(instance) => Some(instance), + _ => None, + } + } +} + +/// One bounded store-service exchange. Native uses reqwest; portable uses `HttpClient`. +#[async_trait(?Send)] +pub(crate) trait Exchanger: Send + Sync { + fn check(&self, deadline: Deadline) -> Result; + fn deadline(&self) -> Result; + fn url(&self, store: &str, resource: &str) -> Result; + async fn execute( + &self, + method: Method, + url: Url, + body: Option, + cap: usize, + deadline: Deadline, + kind: ResponseKind, + ) -> Result; +} + +/// A validated exchange. The instance identifies the store's durable state. +#[cfg_attr( + not(all(not(target_arch = "wasm32"), feature = "kv")), + expect( + dead_code, + reason = "only native preparation reads the reported instance" + ) +)] +pub(crate) struct Exchange { + pub body: Option>, + pub instance: Option, +} + +impl fmt::Debug for Exchange { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("Exchange").finish_non_exhaustive() + } +} + +/// What a validated response head still needs. +pub(crate) enum Head { + /// The head alone completes the exchange. + Complete(Exchange), + /// Read at most `cap` body bytes, then call [`body`]. + Body { + cap: usize, + instance: Option, + success: bool, + }, +} + +/// The bearer header for one credential. The value is marked sensitive. +pub(crate) fn authorization(token: &CelldAccessToken) -> Result { + let mut header = HeaderValue::from_str(&format!("Bearer {}", token.expose())) + .map_err(|_error| PreparationError::Credentials)?; + header.set_sensitive(true); + Ok(header) +} + +/// `{endpoint}/v1/stores/{store}/{resource}`, with each segment percent-encoded. +pub(crate) fn store_url( + endpoint: &Url, + store: &str, + resource: &str, +) -> Result { + let mut url = endpoint.clone(); + url.path_segments_mut() + .map_err(|_error| PreparationError::InvalidEndpoint)? + .clear() + .extend(["v1", "stores", store, resource]); + Ok(url) +} + +/// Request headers for one exchange, including a fresh mutation ID when required. +pub(crate) fn request_headers( + kind: ResponseKind, + authorization: Option<&HeaderValue>, + has_body: bool, +) -> Result { + let mut headers = HeaderMap::new(); + headers.insert(ACCEPT_ENCODING, HeaderValue::from_static("identity")); + if let Some(value) = authorization { + headers.insert(AUTHORIZATION, value.clone()); + } + if kind.mutation() { + headers.insert(MUTATION_HEADER, mutation_id()?); + } + #[cfg(feature = "record-wire")] + if kind.record() { + headers.insert(RECORD_HEADER, HeaderValue::from_static("1")); + } + #[cfg(feature = "record-wire")] + if let Some(expected) = kind.expected_instance() { + headers.insert( + EXPECTED_INSTANCE_HEADER, + HeaderValue::from_bytes(&expected).map_err(|_error| PreparationError::Malformed)?, + ); + } + if has_body { + headers.insert( + CONTENT_TYPE, + HeaderValue::from_static(if kind.record() { + "application/json" + } else { + "application/octet-stream" + }), + ); + } + Ok(headers) +} + +/// Validates a response head. A `None` body means a validated miss, never a protocol +/// failure. Successful responses must name the store instance. +pub(crate) fn head( + kind: ResponseKind, + method: &Method, + status: StatusCode, + headers: &HeaderMap, + cap: usize, +) -> Result { + let success = status + == if kind.mutation() { + StatusCode::NO_CONTENT + } else { + StatusCode::OK + }; + let missing = status == StatusCode::NOT_FOUND; + let instance = validated_instance(headers, kind, method, status, success)?; + + // A mutation acknowledgement carries no body, so it has no media type. + if status == StatusCode::NO_CONTENT && success { + if headers + .get(CONTENT_LENGTH) + .is_some_and(|length| length.as_bytes() != b"0") + { + return Err(PreparationError::Malformed); + } + return Ok(Head::Complete(Exchange { + body: Some(Vec::new()), + instance, + })); + } + // The wire HEAD contract has no error body, including non-404 errors. + if *method == Method::HEAD { + return if success { + Ok(Head::Complete(Exchange { + body: Some(Vec::new()), + instance, + })) + } else if missing { + Ok(Head::Complete(Exchange { + body: None, + instance, + })) + } else { + Err(status_error(status).map_or(PreparationError::Malformed, |(_, error)| error)) + }; + } + let expected_type = if !success || kind.json() { + "application/json" + } else { + "application/octet-stream" + }; + validate_content_type(headers, expected_type)?; + Ok(Head::Body { + cap: if success { cap } else { ERROR_CAP }, + instance, + success, + }) +} + +/// Completes an exchange from its collected body. Sets `definitive_rejection` only for a +/// validated 4xx error body, which proves the service rejected the request. +pub(crate) fn body( + kind: ResponseKind, + status: StatusCode, + instance: Option, + success: bool, + bytes: Vec, + definitive_rejection: &mut bool, +) -> Result { + if success { + return Ok(Exchange { + body: Some(bytes), + instance, + }); + } + let error = validated_error(kind, status, &bytes)?; + if status.is_client_error() { + *definitive_rejection = true; + } + if status == StatusCode::NOT_FOUND && kind.optional() { + return Ok(Exchange { + body: None, + instance, + }); + } + Err(error) +} + +/// Applies the mutation outcome rule: after dispatch, only a definitive rejection is +/// definitive. Every other record-mutation failure may have committed. +#[cfg(feature = "record-wire")] +pub(crate) fn finish( + kind: ResponseKind, + result: Result, + definitive_rejection: bool, +) -> Result { + if matches!(kind, ResponseKind::RecordMutation(_)) && !definitive_rejection { + return result.map_err(|_error| PreparationError::MutationUncertain); + } + result +} + +/// Without record mutations there is no uncertain outcome to classify. +#[cfg(not(feature = "record-wire"))] +pub(crate) fn finish( + _kind: ResponseKind, + result: Result, + _definitive_rejection: bool, +) -> Result { + result +} + +fn validated_instance( + headers: &HeaderMap, + kind: ResponseKind, + method: &Method, + status: StatusCode, + success: bool, +) -> Result, PreparationError> { + validate_headers(headers)?; + #[cfg(feature = "record-wire")] + if kind.record() { + let mut versions = headers.get_all(RECORD_HEADER).iter(); + if versions.next().is_none_or(|value| value.as_bytes() != b"1") || versions.next().is_some() + { + return Err(PreparationError::UnsupportedVersion); + } + } + let observed = instance(headers)?; + if let Some(expected) = kind.expected_instance() + && observed + .as_ref() + .is_some_and(|value| value.as_bytes() != expected) + { + return Err(PreparationError::InstanceChanged); + } + let logical_miss = + status == StatusCode::NOT_FOUND && (*method == Method::HEAD || kind.optional()); + if (success || logical_miss || (kind.record() && status == StatusCode::PRECONDITION_FAILED)) + && observed.is_none() + { + return Err(PreparationError::Malformed); + } + Ok(observed) +} + +fn validated_error( + kind: ResponseKind, + status: StatusCode, + bytes: &[u8], +) -> Result { + if status == StatusCode::PRECONDITION_FAILED && !kind.record() { + return Err(PreparationError::Malformed); + } + let parsed: ErrorBody = + serde_json::from_slice(bytes).map_err(|_error| PreparationError::Malformed)?; + #[cfg(feature = "record-wire")] + let record_error = match (kind, status, parsed.error.as_str()) { + ( + ResponseKind::RecordMutation(_), + StatusCode::PRECONDITION_FAILED, + "precondition_failed", + ) => Some(PreparationError::PreconditionFailed), + (_, StatusCode::SERVICE_UNAVAILABLE, "instance_changed") if kind.record() => { + Some(PreparationError::InstanceChanged) + } + _ => None, + }; + #[cfg(not(feature = "record-wire"))] + let record_error = None; + let error = if let Some(error) = record_error { + error + } else { + let (expected, error) = status_error(status).ok_or(PreparationError::Malformed)?; + if parsed.error != expected { + return Err(PreparationError::Malformed); + } + error + }; + + Ok(error) +} + +/// A fresh 128-bit mutation ID. It is never reused, including after a failure. +fn mutation_id() -> Result { + let mut bytes = [0_u8; 16]; + getrandom::fill(&mut bytes).map_err(|_error| PreparationError::Unavailable)?; + HeaderValue::from_str(&URL_SAFE_NO_PAD.encode(bytes)) + .map_err(|_error| PreparationError::Unavailable) +} + +fn instance(headers: &HeaderMap) -> Result, PreparationError> { + let mut values = headers.get_all(INSTANCE_HEADER).iter(); + let Some(value) = values.next() else { + return Ok(None); + }; + let bytes = value.as_bytes(); + if values.next().is_some() + || bytes.len() != 22 + || !bytes + .iter() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_')) + { + return Err(PreparationError::Malformed); + } + Ok(Some( + String::from_utf8(bytes.to_vec()).map_err(|_error| PreparationError::Malformed)?, + )) +} + +fn validate_headers(headers: &HeaderMap) -> Result<(), PreparationError> { + let mut versions = headers.get_all(VERSION_HEADER).iter(); + if versions.next().is_none_or(|value| value.as_bytes() != b"1") || versions.next().is_some() { + return Err(PreparationError::UnsupportedVersion); + } + let mut encodings = headers.get_all(CONTENT_ENCODING).iter(); + if encodings + .next() + .is_some_and(|value| !value.as_bytes().eq_ignore_ascii_case(b"identity")) + || encodings.next().is_some() + { + return Err(PreparationError::Malformed); + } + Ok(()) +} + +fn validate_content_type(headers: &HeaderMap, expected: &str) -> Result<(), PreparationError> { + let mut types = headers.get_all(CONTENT_TYPE).iter(); + if types + .next() + .is_none_or(|value| value.as_bytes() != expected.as_bytes()) + || types.next().is_some() + { + return Err(PreparationError::Malformed); + } + Ok(()) +} + +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct ErrorBody { + error: String, +} + +fn status_error(status: StatusCode) -> Option<(&'static str, PreparationError)> { + Some(match status.as_u16() { + 400 => ("invalid_input", PreparationError::InvalidResource), + 401 => ("unauthenticated", PreparationError::Unauthenticated), + 403 => ("forbidden", PreparationError::Forbidden), + 404 => ("not_found", PreparationError::Missing), + 413 => ("limit_exceeded", PreparationError::SizeLimit), + 426 => ("unsupported_version", PreparationError::UnsupportedVersion), + 503 => ("unavailable", PreparationError::Unavailable), + 504 => ("deadline", PreparationError::Deadline), + _ => return None, + }) +} diff --git a/crates/edgezero-test-harness/fixtures/request-fidelity/Cargo.lock b/crates/edgezero-test-harness/fixtures/request-fidelity/Cargo.lock index f46b36eff..43e32b482 100644 --- a/crates/edgezero-test-harness/fixtures/request-fidelity/Cargo.lock +++ b/crates/edgezero-test-harness/fixtures/request-fidelity/Cargo.lock @@ -342,6 +342,18 @@ version = "1.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "75b325c5dbd37f80359721ad39aca5a29fb04c89279657cffdda8736d0c0b9d2" +[[package]] +name = "edgezero-adapter" +version = "0.1.0" +dependencies = [ + "edgezero-core", + "edgezero-store-aws", + "edgezero-store-celld", + "serde", + "thiserror 2.0.21", + "toml", +] + [[package]] name = "edgezero-adapter-cloudflare" version = "0.1.0" @@ -374,6 +386,7 @@ dependencies = [ "brotli", "bytes", "chrono", + "edgezero-adapter", "edgezero-core", "fastly", "fastly-shared", @@ -467,6 +480,26 @@ dependencies = [ "validator", ] +[[package]] +name = "edgezero-store-aws" +version = "0.1.0" +dependencies = [ + "percent-encoding", + "serde", + "thiserror 2.0.21", + "url", + "web-time", +] + +[[package]] +name = "edgezero-store-celld" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", + "url", +] + [[package]] name = "either" version = "1.18.0" diff --git a/crates/edgezero-test-harness/fixtures/reusable-app/Cargo.lock b/crates/edgezero-test-harness/fixtures/reusable-app/Cargo.lock index b01cf66c9..f10ce9bbe 100644 --- a/crates/edgezero-test-harness/fixtures/reusable-app/Cargo.lock +++ b/crates/edgezero-test-harness/fixtures/reusable-app/Cargo.lock @@ -104,6 +104,18 @@ version = "1.5.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" +[[package]] +name = "aws-credential-types" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e93964ffdaf57857f544be3666a5f57570bb699e934700f11b49708f61bb556e" +dependencies = [ + "aws-smithy-async", + "aws-smithy-runtime-api", + "aws-smithy-types", + "zeroize", +] + [[package]] name = "aws-lc-rs" version = "1.17.0" @@ -126,6 +138,106 @@ dependencies = [ "fs_extra", ] +[[package]] +name = "aws-sigv4" +version = "1.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2312577f088c9fbf4206dfdb884cf1de9407b43e1a923cbed5237775116fc24b" +dependencies = [ + "aws-credential-types", + "aws-smithy-http", + "aws-smithy-runtime-api", + "aws-smithy-types", + "bytes", + "form_urlencoded", + "hex", + "hmac", + "http", + "percent-encoding", + "sha2 0.11.1", + "time", + "tracing", +] + +[[package]] +name = "aws-smithy-async" +version = "1.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "de681a9df7ff79823b759ee17061076ec049cd61a8fa28ece4293d89c9f6964e" +dependencies = [ + "futures-util", + "pin-project-lite", + "tokio", +] + +[[package]] +name = "aws-smithy-http" +version = "0.64.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba8960956e0ee0ca3f3161e62913a61bc65a7ef638ca3ef1d4c7159f8443e398" +dependencies = [ + "aws-smithy-runtime-api", + "aws-smithy-types", + "bytes", + "bytes-utils", + "futures-core", + "futures-util", + "http", + "http-body", + "http-body-util", + "percent-encoding", + "pin-project-lite", + "tracing", +] + +[[package]] +name = "aws-smithy-runtime-api" +version = "1.19.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06788004dea79018413f381891da6dcca23196acd79c4d51b767fbdacc76eae4" +dependencies = [ + "aws-smithy-async", + "aws-smithy-runtime-api-macros", + "aws-smithy-types", + "bytes", + "http", + "pin-project-lite", + "tokio", + "tracing", + "zeroize", +] + +[[package]] +name = "aws-smithy-runtime-api-macros" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce237f890a2283c9b328955c3b0918d2d5bf66a1cb6ceccd36a0047246fbc6e6" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "aws-smithy-types" +version = "1.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "55752025c39c0e094962fd73f1c57014b191f678612e517f219468e575af9822" +dependencies = [ + "base64-simd", + "bytes", + "bytes-utils", + "http", + "http-body", + "http-body-util", + "itoa", + "num-integer", + "pin-project-lite", + "ryu", + "serde", + "time", +] + [[package]] name = "axum" version = "0.8.9" @@ -190,6 +302,16 @@ version = "0.22.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" +[[package]] +name = "base64-simd" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "339abbe78e73178762e23bea9dfd08e697eb3f3301cd4be981c0f78ba5859195" +dependencies = [ + "outref", + "vsimd", +] + [[package]] name = "bitflags" version = "1.3.2" @@ -253,6 +375,16 @@ version = "1.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" +[[package]] +name = "bytes-utils" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7dafe3a8757b027e2be6e4e5601ed563c55989fcf1546e933c66c8eb3a058d35" +dependencies = [ + "bytes", + "either", +] + [[package]] name = "cc" version = "1.2.63" @@ -310,6 +442,12 @@ dependencies = [ "cc", ] +[[package]] +name = "cmov" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a" + [[package]] name = "colored" version = "3.1.1" @@ -405,6 +543,15 @@ dependencies = [ "hybrid-array", ] +[[package]] +name = "ctutils" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "261af4dc7a06ea8a527a8717d8cbba3417530d6ea14e1edb3de6b67806be474f" +dependencies = [ + "cmov", +] + [[package]] name = "darling" version = "0.20.11" @@ -468,6 +615,7 @@ dependencies = [ "block-buffer 0.12.1", "const-oid", "crypto-common", + "ctutils", ] [[package]] @@ -493,6 +641,18 @@ version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813" +[[package]] +name = "edgezero-adapter" +version = "0.1.0" +dependencies = [ + "edgezero-core", + "edgezero-store-aws", + "edgezero-store-celld", + "serde", + "thiserror 2.0.20", + "toml", +] + [[package]] name = "edgezero-adapter-axum" version = "0.1.0" @@ -502,6 +662,7 @@ dependencies = [ "async-trait", "axum", "bytes", + "edgezero-adapter", "edgezero-core", "edgezero-store-aws", "edgezero-store-celld", @@ -561,7 +722,10 @@ dependencies = [ "brotli", "bytes", "chrono", + "edgezero-adapter", "edgezero-core", + "edgezero-store-aws", + "edgezero-store-celld", "fastly", "fastly-shared", "fastly-sys", @@ -658,17 +822,34 @@ dependencies = [ name = "edgezero-store-aws" version = "0.1.0" dependencies = [ + "async-trait", + "aws-credential-types", + "aws-sigv4", + "base64", + "bytes", + "edgezero-core", + "futures-util", "percent-encoding", "serde", + "serde_json", "thiserror 2.0.20", "url", + "web-time", ] [[package]] name = "edgezero-store-celld" version = "0.1.0" dependencies = [ + "async-trait", + "base64", + "bytes", + "edgezero-core", + "futures-util", + "getrandom 0.4.2", "serde", + "serde_json", + "sha2 0.11.1", "thiserror 2.0.20", "url", ] @@ -1094,6 +1275,21 @@ version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "hmac" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f" +dependencies = [ + "digest 0.11.3", +] + [[package]] name = "http" version = "1.4.2" @@ -1546,6 +1742,15 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" +[[package]] +name = "num-integer" +version = "0.1.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b" +dependencies = [ + "num-traits", +] + [[package]] name = "num-traits" version = "0.2.19" @@ -1582,6 +1787,12 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe" +[[package]] +name = "outref" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e" + [[package]] name = "percent-encoding" version = "2.3.2" @@ -2693,6 +2904,12 @@ version = "0.9.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" +[[package]] +name = "vsimd" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c3082ca00d5a5ef149bb8b555a72ae84c9c59f7250f013ac822ac2e49b19c64" + [[package]] name = "walkdir" version = "2.5.0" diff --git a/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/Cargo.toml b/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/Cargo.toml index ca4e842b4..6d739d1cb 100644 --- a/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/Cargo.toml +++ b/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/Cargo.toml @@ -10,6 +10,12 @@ qualification = ["progress"] progress = ["fixture-core/qualification", "fixture-core/native-body-witness", "edgezero-adapter-fastly/test-utils"] readiness = ["dep:fastly-sys"] records = ["edgezero-core/test-utils"] +# The canonical Fastly path with both portable record providers compiled in. +portable-records = [ + "records", + "edgezero-adapter-fastly/aws-dynamodb-records", + "edgezero-adapter-fastly/celld-records", +] [dependencies] edgezero-core.workspace = true @@ -91,5 +97,10 @@ name = "fixture-fastly-record-contract" path = "src/bin/record_contract.rs" required-features = ["records"] +[[bin]] +name = "fixture-fastly-record-contract-portable" +path = "src/bin/record_contract_portable.rs" +required-features = ["portable-records"] + [lints] workspace = true diff --git a/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/src/bin/record_contract_portable.rs b/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/src/bin/record_contract_portable.rs new file mode 100644 index 000000000..82608f474 --- /dev/null +++ b/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/src/bin/record_contract_portable.rs @@ -0,0 +1,208 @@ +//! Run the shared record contract against the portable DynamoDB and celld providers +//! through the canonical Fastly path: the `edgezero_store_bindings` Config Store +//! document, logical Secret Store credentials and the adapter's per-request KV registry. +//! No provider is constructed here; a receipt proves the adapter selected it. + +use edgezero_core::app::{App, Hooks, StoreMetadata, StoresMetadata}; +use edgezero_core::body::Body; +use edgezero_core::context::RequestContext; +use edgezero_core::error::EdgeError; +use edgezero_core::http::{Response, response_builder}; +use edgezero_core::key_value_store::{KvError, KvHandle}; +use edgezero_core::record_store::{ + RecordKeyLayout, RecordWrite, RecordWriteMode, RecordWriteOutcome, + contract::assert_record_contract, +}; +use edgezero_core::{action, router::RouterService}; + +#[path = "../record_cases.rs"] +mod record_cases; + +/// KV ID, receipt provider label and the record format its provider must report. +const PROVIDERS: [(&str, &str, &str); 2] = [ + ( + "dynamodb_records", + "dynamodb-portable", + "edgezero-dynamodb-records-v1", + ), + ("celld_records", "celld-portable", "celld-store-records-v1"), +]; + +/// The native Fastly suite's layout, so both suites exercise the same keys. +struct FixtureLayout; + +impl RecordKeyLayout for FixtureLayout { + fn id(&self) -> &str { + "fastly-record-contract" + } + + fn version(&self) -> u32 { + 1 + } + + fn validate(&self) -> Result<(), KvError> { + Ok(()) + } + + fn partition_prefix<'a>(&self, key: &'a str) -> Result<&'a str, KvError> { + key.find('/') + .filter(|index| *index > 0 && *index + 1 < key.len()) + .map(|index| &key[..=index]) + .ok_or_else(|| KvError::Validation("invalid fixture record key".to_owned())) + } + + fn validate_partition(&self, prefix: &str) -> Result<(), KvError> { + if prefix.ends_with('/') && prefix.len() > 1 && prefix.matches('/').count() == 1 { + Ok(()) + } else { + Err(KvError::Validation("invalid fixture partition".to_owned())) + } + } +} + +struct PortableRecordsApp; + +impl Hooks for PortableRecordsApp { + fn stores() -> StoresMetadata { + StoresMetadata { + config: None, + kv: Some(StoreMetadata { + default: "dynamodb_records", + ids: &["dynamodb_records", "celld_records"], + }), + secrets: Some(StoreMetadata { + default: "stores", + ids: &["stores"], + }), + } + } + + fn configure(app: &mut App) -> Result<(), EdgeError> { + for (id, _, _) in PROVIDERS { + app.require_record_store(id, FixtureLayout)?; + } + Ok(()) + } + + fn routes() -> Result { + Ok(RouterService::builder() + .get("/record-ready", ready) + .get("/record-contract/{id}", contract) + .get("/record-native/{id}", native) + .get("/record/{id}/{*rest}", cases) + .build()) + } +} + +fn receipt(value: serde_json::Value) -> Result { + response_builder() + .header( + fixture_core::launch::HEADER, + fixture_core::launch::value().unwrap_or("unconfigured"), + ) + .header("content-type", "application/json") + .body(Body::from(value.to_string())) + .map_err(EdgeError::internal) +} + +/// The adapter-selected handle for one portable KV ID, with its provider label. +fn bound(ctx: &RequestContext) -> Result<(KvHandle, &'static str), EdgeError> { + let id = ctx.path_params().get("id").unwrap_or_default(); + let (id, label, format) = PROVIDERS + .into_iter() + .find(|(candidate, _, _)| *candidate == id) + .ok_or_else(|| EdgeError::bad_request("unknown portable KV ID"))?; + let kv = ctx + .kv_store(id) + .ok_or_else(|| EdgeError::service_unavailable("portable KV handle absent"))?; + // A Fastly KV fallback would report the native format; refuse it outright. + let records = kv.require_records().map_err(EdgeError::from)?; + if records.binding().format != format { + return Err(EdgeError::service_unavailable( + "KV ID is not served by its portable provider", + )); + } + Ok((kv, label)) +} + +/// Read-only launch attestation. It never opens a store. +#[action] +async fn ready() -> Result { + receipt(serde_json::json!({ + "record_ready": true, + "providers": PROVIDERS.map(|(_, label, _)| label), + })) +} + +#[action] +async fn contract(ctx: RequestContext) -> Result { + let (kv, label) = bound(&ctx)?; + // A failed assertion traps before this receipt. + assert_record_contract(&kv, "group/").await; + let value = serde_json::json!({ + "record_contract": "passed", + "provider": label, + "executed_suites": 1, + }); + println!("{value}"); + receipt(value) +} + +/// Reads the row the orchestrator wrote natively, then deletes it through this provider. +#[action] +async fn native(ctx: RequestContext) -> Result { + let (kv, label) = bound(&ctx)?; + let records = kv.require_records().map_err(EdgeError::from)?; + let seeded = records + .lookup("native/seed") + .await + .map_err(EdgeError::from)? + .ok_or_else(|| EdgeError::service_unavailable("native seed row absent"))?; + let matched = + seeded.body.as_ref() == b"native-seed" && seeded.metadata.as_deref() == Some("native"); + // The native generation must gate a portable CAS on the same row. + let cas = records + .insert( + "native/seed", + RecordWrite { + body: b"portable-cas", + metadata: None, + ttl: None, + mode: RecordWriteMode::IfGenerationMatch(seeded.generation), + }, + ) + .await + .map_err(EdgeError::from)?; + records + .delete("native/seed") + .await + .map_err(EdgeError::from)?; + let absent = !records + .exists_strong("native/seed") + .await + .map_err(EdgeError::from)?; + receipt(serde_json::json!({ + "record_native": if matched && cas == RecordWriteOutcome::Written && absent { "passed" } else { "failed" }, + "provider": label, + "native_body_matched": matched, + "native_generation_cas": cas == RecordWriteOutcome::Written, + "deleted": absent, + })) +} + +/// The native suite's race, existence and cleanup cases, against one portable ID. +#[action] +async fn cases(ctx: RequestContext) -> Result { + let (kv, label) = bound(&ctx)?; + let rest = ctx.path_params().get("rest").unwrap_or_default(); + let mut value = record_cases::run(&kv, &format!("/{rest}")) + .await + .map_err(EdgeError::from)?; + value["provider"] = serde_json::Value::from(label); + receipt(value) +} + +fn main() -> Result<(), fastly::Error> { + fixture_fastly::initialize_launch(env!("CARGO_BIN_NAME")); + edgezero_adapter_fastly::run_app::() +} diff --git a/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/src/record_cases.rs b/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/src/record_cases.rs index e4f430dd7..bb6b3c513 100644 --- a/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/src/record_cases.rs +++ b/crates/edgezero-test-harness/fixtures/reusable-app/crates/fixture-fastly/src/record_cases.rs @@ -127,9 +127,20 @@ pub async fn run(kv: &KvHandle, path: &str) -> Result { ) } ["record-cases", "clean"] => { - let page = kv.list_keys_page("", None, 1).await?; - assert!(page.keys.is_empty() && page.cursor.is_none()); - Ok(json!({"record_cases":"clean","remaining_keys":0})) + // Drain the whole global listing. Some providers keep internal rows, such + // as DynamoDB generation allocators, that yield empty pages with a cursor. + let mut cursor = None; + let mut cursors = HashSet::new(); + let mut pages = 0_usize; + loop { + let page = kv.list_keys_page("", cursor.as_deref(), 1000).await?; + pages += 1; + assert!(page.keys.is_empty(), "logical keys remain after cleanup"); + cursor = page.cursor; + let Some(next) = &cursor else { break }; + assert!(cursors.insert(next.clone()), "repeated cleanup cursor"); + } + Ok(json!({"record_cases":"clean","remaining_keys":0,"pages":pages})) } _ => Err(invalid_route()), } diff --git a/crates/edgezero-test-harness/src/evidence/cutover/reviewed_owners.json b/crates/edgezero-test-harness/src/evidence/cutover/reviewed_owners.json index 527ed1ed9..afbcde89b 100644 --- a/crates/edgezero-test-harness/src/evidence/cutover/reviewed_owners.json +++ b/crates/edgezero-test-harness/src/evidence/cutover/reviewed_owners.json @@ -1,9 +1,9 @@ { "src/main.rs:outbound_lifetimes_selects_exactly_one_explicit_provider": "db8098c65fe1d4c32b4c7572883e02b1267d6ddaa99b751d35a087052409942c", "src/main.rs:outbound_wire_suite_is_explicit_and_selects_one_supported_provider": "5e6bd8b1f347422d0030acab5e43a8c0d9fffbad7f304d7171847fc7e4e04ae7", - "src/main.rs:parse_from": "5c8bd05e2331f4794feccd592bc22308272ce1bb1afeff7a3bea4c9ec1c0f2a9", + "src/main.rs:parse_from": "6c9b55060b145d60570e3ccf0b7a80514553c3a22f527f836d661de0542e451f", "src/main.rs:run": "744c16f7b155adb4d27933eed21ab7b6d0adcc40ac81b787e2b8e164b2b78fb5", - "src/runners.rs:fastly": "5ec7f89c5669eb077f5b81cb57a21f62f9d55869ef2f84255155d0442728e330", + "src/runners.rs:fastly": "dd9dc51867351e1a7127c6eb2e432cf0db93bf7f498dd26f25b890fd5a3f63dd", "src/runners.rs:provider": "611830f75cbb95179b853a39f49ba9839a9cb06c2967b769a7d9300a40536f5b", "src/runners/ci.rs:phase_with_exit": "071915332c0cd8d29aeade1fc89ed79d35b38037c76d41e55160c11f7f31e76e", "src/runners/ci.rs:run": "ce639c2a76850fd428db8319d94de3ec2c7a3c7e96a5963e79f0aec1b2d37d2a", diff --git a/crates/edgezero-test-harness/src/main.rs b/crates/edgezero-test-harness/src/main.rs index 350366483..6dc8b9aa2 100644 --- a/crates/edgezero-test-harness/src/main.rs +++ b/crates/edgezero-test-harness/src/main.rs @@ -95,6 +95,7 @@ impl Args { "benchmark", "assembly", "record-contract", + "portable-record-contract", "outbound-readiness", "outbound-client-progress", "outbound-progress", @@ -110,7 +111,10 @@ impl Args { "unknown suite", )?; require( - a.suite != "record-contract" || a.adapter == "fastly", + !matches!( + a.suite.as_str(), + "record-contract" | "portable-record-contract" + ) || a.adapter == "fastly", "record contract requires --adapter fastly", )?; require( @@ -1066,11 +1070,12 @@ mod argument_tests { #[test] fn record_contract_suite_selects_only_fastly() { - for adapter in ["fastly", "axum", "cloudflare", "spin", "all"] { - let result = Args::parse_from( - ["--adapter", adapter, "--suite", "record-contract"].map(str::to_owned), - ); - assert_eq!(result.is_ok(), adapter == "fastly", "{adapter}"); + for suite in ["record-contract", "portable-record-contract"] { + for adapter in ["fastly", "axum", "cloudflare", "spin", "all"] { + let result = + Args::parse_from(["--adapter", adapter, "--suite", suite].map(str::to_owned)); + assert_eq!(result.is_ok(), adapter == "fastly", "{suite} {adapter}"); + } } } diff --git a/crates/edgezero-test-harness/src/runners.rs b/crates/edgezero-test-harness/src/runners.rs index a9a8d3ff5..f5d63b03d 100644 --- a/crates/edgezero-test-harness/src/runners.rs +++ b/crates/edgezero-test-harness/src/runners.rs @@ -381,6 +381,9 @@ pub fn fastly(args: &Args, run: &Path, records: &mut Records) -> Result<()> { if args.suite == "record-contract" { return record_contract::run(&exe, run, records); } + if args.suite == "portable-record-contract" { + return record_contract::run_portable(&exe, run, records); + } if args.suite == "outbound-wire" { return wire::run("fastly", run, records); } diff --git a/crates/edgezero-test-harness/src/runners/record_contract.rs b/crates/edgezero-test-harness/src/runners/record_contract.rs index a25705089..dbb1bf0f8 100644 --- a/crates/edgezero-test-harness/src/runners/record_contract.rs +++ b/crates/edgezero-test-harness/src/runners/record_contract.rs @@ -292,6 +292,332 @@ pub(super) fn run(exe: &Path, parent: &Path, records: &mut Records) -> Result<() ) } +const PORTABLE_BIN: &str = "fixture-fastly-record-contract-portable"; +/// Each portable KV ID and the provider label its receipts must carry. +const PORTABLE: [(&str, &str); 2] = [ + ("dynamodb_records", "dynamodb-portable"), + ("celld_records", "celld-portable"), +]; + +fn validate_portable_ready(reply: &Value) -> Result<()> { + let ready = guest(reply)?; + require( + ready["record_ready"] == true + && ready["providers"] == json!(PORTABLE.map(|(_, label)| label)) + && ready.get("record_contract").is_none() + && ready.get("executed_suites").is_none(), + "invalid read-only portable record readiness response", + ) +} + +fn validate_portable_receipt(receipt: &Value, provider: &str) -> Result<()> { + require( + receipt["record_contract"] == "passed" + && receipt["provider"] == provider + && receipt["executed_suites"] == 1, + "missing or invalid portable record contract receipt", + ) +} + +/// One provider's evidence of `event`; exactly one must exist. +fn only<'a>( + events: &'a [Value], + event: &str, + provider: &str, + mode: Option<&str>, +) -> Result<&'a Value> { + let matching = events + .iter() + .filter(|record| { + record["event"] == event + && record["provider"] == provider + && mode.is_none_or(|expected| record["mode"] == expected) + }) + .collect::>(); + require( + matching.len() == 1 && matching[0]["status"] == "pass", + format!("missing or duplicate {event} evidence for {provider}"), + )?; + Ok(matching[0]) +} + +/// Every portable provider needs its own complete, passing evidence. One provider's +/// receipts never satisfy another's, and no other provider label may appear. +pub(super) fn validate_portable_events(events: &[Value]) -> Result<()> { + require( + !events.iter().any(|event| event["status"] == "fail"), + "failed portable record contract evidence", + )?; + let labels = PORTABLE.map(|(_, label)| label); + require( + events + .iter() + .filter_map(|event| event["provider"].as_str()) + .all(|provider| labels.contains(&provider)), + "unexpected provider in portable record evidence", + )?; + for label in labels { + let suite = only(events, "portable-record-contract", label, None)?; + require( + suite["executed_suites"] == 1, + "portable record contract suite did not execute once", + )?; + validate_portable_receipt(&suite["receipt"], label)?; + for mode in ["add", "cas"] { + let race = only(events, "portable-record-race", label, Some(mode))?; + require( + race["independent_writers"] == 2 + && race["written"] == 1 + && race["precondition_failed"] == 1, + format!("missing portable {mode} race evidence for {label}"), + )?; + } + let pages = &only(events, "portable-record-existence", label, None)?["receipt"]; + require( + pages["descendants"] == 1001 + && pages["native_pages"] + .as_u64() + .is_some_and(|count| count >= 2) + && pages["exact_absent_before"] == true + && pages["exact_present"] == true + && pages["exact_absent_after"] == true, + format!("missing portable exact-existence continuation evidence for {label}"), + )?; + let native = &only(events, "portable-record-native-read", label, None)?["receipt"]; + require( + native["record_native"] == "passed" + && native["native_body_matched"] == true + && native["native_generation_cas"] == true + && native["deleted"] == true, + format!("missing native-to-portable interop evidence for {label}"), + )?; + let cleanup = only(events, "portable-record-cleanup", label, None)?; + require( + cleanup["receipt"]["remaining_keys"] == 0, + format!("missing portable cleanup evidence for {label}"), + )?; + } + Ok(()) +} + +/// The native suite's cases against one portable KV ID, under `/record/{id}`. +fn run_portable_cases(port: u16, id: &str, label: &str, records: &mut Records) -> Result<()> { + let base = format!("/record/{id}"); + let prepared = guest(&req(port, &format!("{base}/record-race/prepare"))?)?; + require( + prepared["record_race"] == "prepared", + "portable race preparation failed", + )?; + let generation = prepared["generation"] + .as_u64() + .ok_or("missing portable race generation")?; + for mode in ["add", "cas"] { + let path = |writer| { + if mode == "add" { + format!("{base}/record-race/add/{writer}") + } else { + format!("{base}/record-race/cas/{writer}/{generation}") + } + }; + let replies = race_clients(port, [path("a"), path("b")])?; + let written = replies + .iter() + .filter(|reply| reply["outcome"] == "written") + .count(); + let rejected = replies + .iter() + .filter(|reply| reply["outcome"] == "precondition-failed") + .count(); + require( + replies.iter().all(|reply| reply["record_race"] == mode) + && written == 1 + && rejected == 1, + format!("portable {mode} race for {label} did not have exactly one winner"), + )?; + let winner = replies + .iter() + .find(|reply| reply["outcome"] == "written") + .ok_or("missing portable race winner")?; + let stored = guest(&req(port, &format!("{base}/record-race/result/{mode}"))?)?; + require( + stored["body"] == winner["writer"], + "portable race stored the losing value", + )?; + records.push( + json!({"event":"portable-record-race","status":"pass","provider":label, + "mode":mode,"independent_writers":2,"written":1,"precondition_failed":1, + "winner":winner["writer"],"clients":replies,"stored":stored,"qualification":false}), + )?; + } + let cleaned = guest(&req(port, &format!("{base}/record-race/cleanup"))?)?; + require( + cleaned["record_race"] == "cleaned", + "portable race cleanup failed", + )?; + + // Batch fixture setup and cleanup across requests. This is not a provider + // operation-budget claim or a production mutation retry policy. + for operation in ["seed", "cleanup"] { + for start in (0..1001).step_by(100) { + let end = (start + 100).min(1001); + let reply = guest(&req( + port, + &format!("{base}/record-existence/{operation}/{start}/{end}"), + )?)?; + require( + reply["record_existence"] == operation && reply["count"] == end - start, + "portable existence batch incomplete", + )?; + } + if operation == "seed" { + let receipt = guest(&req(port, &format!("{base}/record-existence/check"))?)?; + require( + receipt["record_existence"] == "passed", + "portable exact existence failed", + )?; + records.push(json!({"event":"portable-record-existence","status":"pass", + "provider":label,"receipt":receipt,"qualification":false}))?; + } + } + let receipt = guest(&req(port, &format!("{base}/record-cases/clean"))?)?; + require( + receipt["record_cases"] == "clean" && receipt["remaining_keys"] == 0, + "portable fixture cleanup failed", + )?; + records.push( + json!({"event":"portable-record-cleanup","status":"pass","provider":label, + "receipt":receipt,"qualification":false}), + ) +} + +/// An absolute regular file named by `name`; the suite never guesses inputs. +fn explicit_file(name: &str) -> Result { + let path = std::env::var_os(name) + .map(PathBuf::from) + .ok_or_else(|| format!("{name} is required; the portable suite never skips"))?; + require( + path.is_absolute() && path.is_file(), + format!("{name} must name an absolute file"), + )?; + Ok(path) +} + +/// Portable DynamoDB and celld providers through the canonical Fastly path. The caller +/// provisions the services and supplies the Viceroy configuration and trust root. +pub(super) fn run_portable(exe: &Path, parent: &Path, records: &mut Records) -> Result<()> { + let run = parent.join("portable-record-contract"); + fs::create_dir_all(&run)?; + let supplied = explicit_file("EDGEZERO_PORTABLE_RECORDS_CONFIG")?; + let trust = explicit_file("EDGEZERO_PORTABLE_RECORDS_CA")?; + + let output = Command::new(exe).arg("--version").output()?; + require(output.status.success(), "Viceroy version command failed")?; + let version = String::from_utf8(output.stdout)?.trim().to_owned(); + let pins = fs::read_to_string(repository_root().join(".tool-versions"))?; + let pin = pins + .lines() + .find_map(|line| line.strip_prefix("viceroy ")) + .map(str::trim) + .ok_or("missing Viceroy pin")?; + require( + version.split_whitespace().nth(1) == Some(pin), + "portable record contract requires the pinned Viceroy runtime", + )?; + + let mut build = cargo_build()?; + if let Some(target) = std::env::var_os("CARGO_TARGET_DIR") { + build.env("CARGO_TARGET_DIR", target); + } + let output = build + .args([ + "build", + "--locked", + "--offline", + "--release", + "-p", + "fixture-fastly", + "--features", + "portable-records", + "--bin", + PORTABLE_BIN, + "--target", + "wasm32-wasip1", + "--message-format=json-render-diagnostics", + ]) + .stderr(Stdio::from(fs::File::create(run.join("build.log"))?)) + .output()?; + fs::write(run.join("build.jsonl"), &output.stdout)?; + require( + output.status.success(), + "portable Fastly record fixture build failed", + )?; + let wasm = stage(&built_executable(&output.stdout, PORTABLE_BIN)?, &run)?; + // The configuration carries test-only credentials. Record its identity, not a copy. + records.push(json!({ + "event":"build", "adapter":"fastly", "suite":"portable-record-contract", + "variant":"fastly-portable-record-contract", "target":"wasm32-wasip1", + "artifact":artifact(&wasm)?, "config":artifact(&supplied)?["fnv1a64"], + "trust_root":artifact(&trust)?, "runtime":artifact(exe)?, "runtime_version":version, + }))?; + + let log = run.join("runtime.log"); + let outcome = (|| -> Result<()> { + let port = net::port()?; + let mut command = fastly_command(exe, &supplied, &run, "record-contract-portable", port)?; + // Only Viceroy trusts the test root, and only for this run. + command.env("SSL_CERT_FILE", &trust); + let mut process = Process::start(&mut command, &log, port)?; + let ready = req(port, "/record-ready")?; + validate_portable_ready(&ready)?; + records.push(json!({ + "event":"portable-record-ready", "status":"pass", "client":ready, + "qualification":false, + }))?; + for (id, label) in PORTABLE { + // Read, CAS and delete the natively written row first: the shared contract + // asserts the exact global listing, so no foreign row may remain. + let native = guest(&req(port, &format!("/record-native/{id}"))?)?; + require( + native["record_native"] == "passed" && native["provider"] == label, + format!("native-to-portable interop failed for {label}"), + )?; + records.push( + json!({"event":"portable-record-native-read","status":"pass", + "provider":label,"receipt":native,"qualification":false}), + )?; + let reply = req(port, &format!("/record-contract/{id}"))?; + let receipt = guest(&reply)?; + validate_portable_receipt(&receipt, label)?; + records.push(json!({ + "event":"portable-record-contract", "adapter":"fastly", "status":"pass", + "provider":label, "executed_suites":1, "receipt":receipt, "client":reply, + "qualification":false, + }))?; + run_portable_cases(port, id, label, records)?; + } + process.finish()?; + Ok(()) + })(); + // The launch configuration copies test credentials; do not keep it as evidence. + for entry in fs::read_dir(&run)?.flatten() { + if entry.file_name().to_string_lossy().starts_with("launch-") { + fs::remove_file(entry.path())?; + } + } + settle( + records, + &log, + json!({"adapter":"fastly","suite":"portable-record-contract","qualification":false}), + json!({"phase":"portable-record-contract"}), + outcome, + )?; + // Judge the persisted evidence, not only the in-process control flow. + validate_portable_events(&super::ci::read_events( + &parent.join("events.jsonl"), + super::ci::CI_ARTIFACT_RECORDS, + )?) +} + #[cfg(test)] mod tests { use super::*; @@ -384,4 +710,107 @@ mod tests { assert!(validate_reply(&reply(200, json!({}))).is_err()); assert!(validate_reply(&json!({"status":200,"body":"not json"})).is_err()); } + + fn portable_events() -> Vec { + let mut events = Vec::new(); + for (_, label) in PORTABLE { + events.push(json!({"event":"portable-record-contract","status":"pass","provider":label, + "executed_suites":1,"receipt":{"record_contract":"passed","provider":label,"executed_suites":1}})); + for mode in ["add", "cas"] { + events.push( + json!({"event":"portable-record-race","status":"pass","provider":label, + "mode":mode,"independent_writers":2,"written":1,"precondition_failed":1}), + ); + } + events.push( + json!({"event":"portable-record-existence","status":"pass","provider":label, + "receipt":{"descendants":1001,"native_pages":3,"exact_absent_before":true, + "exact_present":true,"exact_absent_after":true}}), + ); + events.push( + json!({"event":"portable-record-native-read","status":"pass","provider":label, + "receipt":{"record_native":"passed","native_body_matched":true, + "native_generation_cas":true,"deleted":true}}), + ); + events.push( + json!({"event":"portable-record-cleanup","status":"pass","provider":label, + "receipt":{"remaining_keys":0}}), + ); + } + events + } + + #[test] + fn portable_evidence_requires_every_provider_independently() { + let events = portable_events(); + assert!(validate_portable_events(&events).is_ok()); + assert!(validate_portable_events(&[]).is_err()); + for index in 0..events.len() { + let mut missing = events.clone(); + missing.remove(index); + assert!( + validate_portable_events(&missing).is_err(), + "missing {index}" + ); + let mut duplicate = events.clone(); + duplicate.push(events[index].clone()); + assert!( + validate_portable_events(&duplicate).is_err(), + "duplicate {index}" + ); + // One provider's evidence relabelled as the other cannot satisfy both. + let mut substituted = events.clone(); + let other = if events[index]["provider"] == "dynamodb-portable" { + "celld-portable" + } else { + "dynamodb-portable" + }; + substituted[index]["provider"] = json!(other); + assert!( + validate_portable_events(&substituted).is_err(), + "substituted {index}" + ); + } + let mut failed = events.clone(); + failed.push(json!({"status":"fail"})); + assert!(validate_portable_events(&failed).is_err()); + let mut foreign = events.clone(); + foreign.push(json!({"event":"client_completed","provider":"fastly-native"})); + assert!(validate_portable_events(&foreign).is_err()); + for (field, value) in [ + ("executed_suites", json!(0)), + ("executed_suites", json!("1")), + ] { + let mut wrong = events.clone(); + wrong[0]["receipt"][field] = value; + assert!(validate_portable_events(&wrong).is_err()); + } + let mut two_winners = events.clone(); + two_winners[1]["written"] = json!(2); + two_winners[1]["precondition_failed"] = json!(0); + assert!(validate_portable_events(&two_winners).is_err()); + let mut one_page = events.clone(); + one_page[3]["receipt"]["native_pages"] = json!(1); + assert!(validate_portable_events(&one_page).is_err()); + let mut unread = events; + unread[4]["receipt"]["native_body_matched"] = json!(false); + assert!(validate_portable_events(&unread).is_err()); + } + + #[test] + fn portable_readiness_names_both_providers_without_contract_fields() { + let ready = |body: Value| json!({"status":200,"body":body.to_string()}); + assert!( + validate_portable_ready(&ready(json!({"record_ready":true, + "providers":["dynamodb-portable","celld-portable"]}))) + .is_ok() + ); + for body in [ + json!({"record_ready":true,"providers":["dynamodb-portable"]}), + json!({"record_ready":true,"providers":["dynamodb-portable","celld-portable"],"executed_suites":1}), + json!({"record_ready":false,"providers":["dynamodb-portable","celld-portable"]}), + ] { + assert!(validate_portable_ready(&ready(body)).is_err()); + } + } } diff --git a/docs/guide/cli-reference.md b/docs/guide/cli-reference.md index 630462bae..7cd2e8a2a 100644 --- a/docs/guide/cli-reference.md +++ b/docs/guide/cli-reference.md @@ -319,6 +319,46 @@ Reads the Fastly API token from `FASTLY_API_TOKEN` in the environment. A production rollback emits `rolled-back-to=` (the version it activated). Exits non-zero with a one-line diagnostic on error. +### edgezero config bindings pin + +Preflight the providers in a portable bindings file and pin their observed backing +identities. This command is untyped and runs in both the bundled `edgezero` binary +and generated app CLIs. It does not read app-config TOML or upload to Fastly. + +```sh +edgezero config bindings pin --adapter fastly --store-bindings portable-stores.toml +``` + +- `--adapter ` selects the target. Only `fastly` is accepted. +- `--store-bindings ` selects the version 1 portable bindings document to + update. It may be unpinned on the first run. + +For `aws-dynamodb-records`, native preflight uses the AWS SDK credential chain, +DescribeTable and the binding's explicit or regional endpoint. It pins the table +ARN and optional TableId. For `celld-records`, preflight reads capabilities using +the token in `KV____CELLD_TOKEN`, where `` is the uppercased logical KV ID. +For example, `sessions` reads `KV__SESSIONS__CELLD_TOKEN` from the operator process's +environment, even though the runtime binding uses `token_secret`. + +Every selected binding must pass before the file changes. The command updates +only `pinned`, preserving comments, ordering, endpoints and runtime credential +references. It never creates credentials or writes secret values. Failure leaves +the input unchanged and reports the binding ID and a fixed provider failure +category, without URLs, response payloads or credentials. + +The CLI default feature `bindings-pin` includes the native preflight dependencies. +A CLI built without it still recognizes the command but reports that pinning +support is not compiled. Rebuild with `--features bindings-pin` to enable it. +When running from the source workspace, select `--bin edgezero` with `cargo run`. + +After pinning, run the offline validation below and upload the document manually +as described in [portable providers on Fastly](./kv-records#portable-providers-on-fastly). +Pinning alone does not check manifest declarations or prove runtime IAM, write +permissions or hosted latency. + +Exit status is `0` on success and non-zero on failure. Successful output lists +only the pinned logical KV IDs. + ### edgezero config validate `config validate` checks every adapter declared in the manifest and compiled @@ -355,6 +395,34 @@ edgezero config validate app-demo-cli config validate --strict ``` +#### Bindings-only validation + +With `--adapter` and `--store-bindings`, validation reads the selected bindings +file instead of typed app configuration: + +```sh +edgezero config validate --adapter fastly \ + --store-bindings portable-stores.toml --manifest edgezero.toml + +edgezero config validate --adapter axum \ + --store-bindings /etc/my-app/native-stores.toml --manifest edgezero.toml +``` + +Fastly validation uses `[stores.kv]` and `[stores.secrets]` declarations and +`[adapters.fastly.build] features` from the manifest. It requires pins and logical +credential references, validates lowercase `[a-z0-9_]` KV IDs and authenticated +HTTPS for celld, and rejects native-only providers or providers absent from those +build features. The entry must fit 8,000 characters. It never reads tokens, +contacts services, invokes Cargo or uploads configuration. This validates the +manifest's selections, not the contents of an already built WASM binary. + +Axum keeps structural native validation. Its bindings file must be absolute. +`--target`, `--target-features`, `--target-all-features` and +`--target-no-default-features` normalize native target controls without invoking +Cargo or proving compiled provider availability. These controls are not accepted +for Fastly bindings validation. `--app-config` is incompatible with either +bindings-only path. No typed app-config struct is required in either CLI. + **Exit codes:** `0` on success, non-zero with a one-line diagnostic on the first failure (the loader / validator returns early at the first mismatch). ### edgezero config push diff --git a/docs/guide/dynamodb-kv.md b/docs/guide/dynamodb-kv.md index 9cbabcbf1..dc31a331b 100644 --- a/docs/guide/dynamodb-kv.md +++ b/docs/guide/dynamodb-kv.md @@ -1,8 +1,10 @@ -# Native DynamoDB KV +# DynamoDB KV -This page describes the ordinary `aws-dynamodb` format. For native conditional -records, partitioned storage and global Scan, see [conditional KV records](./kv-records). -The two modes are explicit and do not migrate each other's rows. +The native sections below describe the ordinary `aws-dynamodb` format. For +conditional records, partitioned storage and global Scan, see +[conditional KV records](./kv-records) and the +[portable DynamoDB records](#portable-dynamodb-records) section below. +The ordinary and record formats are explicit and do not migrate each other's rows. DynamoDB is an optional live KV provider for native Axum apps. It uses the existing `Kv` extractor, `KvHandle` and per-ID registry. Config and Secrets Manager stores @@ -20,9 +22,12 @@ features = ["aws-dynamodb"] ``` `aws-stores` retains its existing AppConfig Agent and Secrets Manager membership. -Use `aws-stores,aws-dynamodb` to enable all three. DynamoDB is off by default and -its SDK is absent from settings-only, ordinary CLI/Axum, Agent-only and WASM -normal dependency graphs. +Use `aws-stores,aws-dynamodb` to enable all three. Native DynamoDB is off by +default on adapters. Its SDK is absent from settings-only, minimal CLI/Axum, +Agent-only and WASM portable-provider graphs. The bundled CLI's default +`bindings-pin` feature intentionally includes the native SDK for operator-run +preflight. An SDK-free CLI build uses +`--no-default-features --features cli,edgezero-adapter-axum`. Declare a portable KV ID in the application as usual, then select its native provider in an absolute bindings file: @@ -123,6 +128,97 @@ flowchart TD KV --> SDK[One bounded live DynamoDB operation] ``` +## Portable DynamoDB records + +Fastly can use `provider = "aws-dynamodb-records"` with the default-off generated +adapter feature `aws-dynamodb-records`. The standalone provider crate feature is +`dynamodb-records-portable`. It implements DynamoDB JSON 1.0 with SigV4 over +EdgeZero outbound HTTP, without the AWS SDK or a native executor on WASM. Native +Axum keeps the SDK-backed `dynamodb-records` transport. Both transports use the +same record rows, allocator state and cursor scope. + +Follow [portable providers on Fastly](./kv-records#portable-providers-on-fastly) +for the complete manifest, Config Store document, secrets and upload steps. +A DynamoDB binding declares `region`, `table`, `namespace`, +`credentials = { secrets = "" }` and a preflight-generated +`pinned` table ARN and optional TableId. Runtime credentials come from +`KV____AWS_ACCESS_KEY_ID`, `KV____AWS_SECRET_ACCESS_KEY` and optional +`KV____AWS_SESSION_TOKEN` in that logical secrets store. They are read on first +use per request, never retained across requests. An STS rotator can update those +keys with short-lived credentials. + +### Endpoints and pinned identity + +Portable bindings accept an optional `endpoint`. Without it, EdgeZero derives the +regional DynamoDB endpoint from `region`, including the China partition suffix. +Use HTTPS. Plain HTTP is accepted only on a literal loopback IP for DynamoDB Local, +for example `endpoint = "http://127.0.0.1:18000"`. Userinfo, paths, queries and +fragments are rejected. Axum rejects the binding's `endpoint` and `credentials` +fields; its native SDK endpoint/credential sources remain unchanged. + +`edgezero config bindings pin --adapter fastly --store-bindings ` uses the +AWS SDK credential chain and DescribeTable at that same explicit or regional +endpoint. It verifies table shape, captures ARN/TableId, checks the observed +endpoint identity and writes only `pinned`. It does not insert an endpoint or +credentials into the file, create a table or test write permissions. + +The portable runtime makes no DescribeTable call and addresses the table by name. +Pins bind cursors to the configured identity, but do not detect same-name table +recreation at runtime. Native startup does reject a pin that differs from its +preflight observation. Do not recreate a bound table in place: recreation discards +allocator rows and can make old generation tokens collide. If it is unavoidable, +re-pin and redeploy bindings before serving, and invalidate outstanding generations. +Converting the table to a global table after pinning is unsupported because Add/CAS +requires the validated single-region table behavior. + +### Runtime IAM + +For a portable record binding on `ts-identity`, grant these six runtime actions +on one table ARN. Replace the account, region and table with the reviewed target: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "dynamodb:GetItem", + "dynamodb:UpdateItem", + "dynamodb:PutItem", + "dynamodb:DeleteItem", + "dynamodb:Query", + "dynamodb:Scan" + ], + "Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/ts-identity" + } + ] +} +``` + +DescribeTable belongs to the operator's preflight role and native preparation, +not the portable runtime role. Table creation, TTL configuration and permission +administration remain operator responsibilities. Global listing uses Scan, which +reads broadly across the table before namespace/format/prefix filtering. A +partition-only Query policy cannot support that listing path. This policy example +does not qualify hosted IAM or capacity. + +### Deadlines and failures + +Portable DynamoDB defaults to a 1,000 ms operation deadline and 250 ms connect +timeout. A strict per-binding `[kv..limits]` table may override timeout values +and lower the payload cap. Positive timeout values must satisfy +`connect_timeout_ms <= attempt_timeout_ms <= operation_timeout_ms`. +Native defaults remain 5,000 ms operation and 1,000 ms connect. + +Every record insert makes UpdateItem then PutItem under one shared deadline, +including Add/CAS. Neither call is automatically retried. A definitive condition +failure is `PreconditionFailed`; failure before value dispatch or a definitive +service rejection is `Unavailable`. A dispatched value write with an uncertain +outcome returns `MutationUncertain`, never a successful miss or an automatic +replay. See [deadlines and uncertain writes](./kv-records#deadlines-and-uncertain-writes) +for reconciliation guidance and the pending real Fastly latency evidence. + ## Diagnostics and verification scope EdgeZero-owned errors/debug output do not retain SDK response details or raw diff --git a/docs/guide/kv-records.md b/docs/guide/kv-records.md index a5413e4f7..a1c9cd145 100644 --- a/docs/guide/kv-records.md +++ b/docs/guide/kv-records.md @@ -5,8 +5,13 @@ existence and strongly consistent partition pages. It uses the same value rows a ordinary `KvHandle` operations. It is not a second store or registry. Built-in implementations are Fastly KV and Axum's persistent redb, DynamoDB and -celld record modes. Cloudflare and Spin built-ins reject record requirements during -application construction. Ordinary-only KV bindings keep their existing behavior. +celld record modes. Fastly can also select the portable DynamoDB and celld record +providers described below. Their row formats match the native transports. +Cloudflare and Spin built-ins still reject record requirements during application +construction. The portable providers compile for `wasm32-unknown-unknown` and +`wasm32-wasip2`; runtime wiring belongs to [#479](https://github.com/IABTechLab/edgezero/issues/479) +and [#484](https://github.com/IABTechLab/edgezero/issues/484). +Ordinary-only KV bindings keep their existing behavior. ## Declare grouping before preparation @@ -205,8 +210,8 @@ and retained allocator SKs contain the unchanged full key under separate `r#` an then uses conditional or unconditional PutItem. Gaps and out-of-allocation-order commits are valid. No namespace-wide item is updated by every insert. -The runtime needs DescribeTable, GetItem, UpdateItem, PutItem, DeleteItem, Query -and Scan on the reviewed table. Scan's broad read access differs from a +The native runtime needs DescribeTable for preparation, then GetItem, UpdateItem, +PutItem, DeleteItem, Query and Scan on the reviewed table. Scan's broad read access differs from a partition-only policy. This is not hosted IAM or capacity qualification. For celld, select `celld-records` instead: @@ -242,6 +247,177 @@ requires records. The standalone provider features are `dynamodb-records` and on this line. Settings-only, ordinary-only and WASM builds do not gain native SDK/runtime dependencies. +## Portable providers on Fastly + +Declare the logical KV and secrets IDs, and enable the provider code in +`edgezero.toml`: + +```toml +[stores.kv] +ids = ["identity", "sessions"] +default = "identity" + +[stores.secrets] +ids = ["stores"] + +[adapters.fastly.build] +features = ["aws-dynamodb-records", "celld-records"] +``` + +`edgezero build`, `edgezero serve` and `edgezero deploy` pass these build features +through `EDGEZERO_BUILD_FEATURES` to the generated `fastly.toml` build script. +Running `fastly compute build` directly does not read `edgezero.toml` or forward +its features. Use the EdgeZero commands, or set the generated script's build +features yourself. + +Create and link a Fastly Config Store named `edgezero_store_bindings` to the +service. Its `EDGEZERO__STORE_BINDINGS` entry holds a version 1 TOML document, +not an app-config blob envelope. This example shows the document after pinning. +The pin values are illustrative. Omit both `pinned` lines for the first preflight +and let the pin command insert the observed identities. + +```toml +version = 1 + +[kv.identity] +provider = "aws-dynamodb-records" +region = "us-east-1" +table = "ts-identity" +namespace = "ts-prod/identity" +pinned = { table_arn = "arn:aws:dynamodb:us-east-1:111122223333:table/ts-identity", table_id = "replace-with-preflight-table-id" } +credentials = { secrets = "stores" } + +[kv.sessions] +provider = "celld-records" +endpoint = "https://celld.example.net" +store = "sessions" +pinned = { instance = "AAAAAAAAAAAAAAAAAAAAAA" } +access = { mode = "authenticated", token_secret = { secrets = "stores" } } +``` + +The document selects a provider per logical KV ID. IDs without a binding stay on +Fastly KV. A missing Config Store or entry also leaves those IDs on Fastly KV. +A malformed document, unsupported provider, missing pin or provider feature absent +from the binary fails application assembly. There is no fallback for an explicit +binding, and read/open failures are not treated as missing configuration. + +Portable-provider KV IDs must be nonempty lowercase ASCII letters, digits or +underscores, `[a-z0-9_]`. Every bound ID and logical secrets reference must be +declared in the manifest. Native-only providers and `[config]`, `[secrets]` or +`[limits]` bindings sections are not supported on Fastly. The complete entry must +fit Fastly's 8,000-character limit; bindings are not chunked. + +```mermaid +flowchart TB + Document[Config Store bindings document] --> Prepared[Validate and retain settings and pins] + Prepared --> Request[Bind the request's outbound HTTP client] + Secrets[Logical Secret Store] --> Credentials[Resolve credentials on first use] + Request --> Credentials + Credentials --> Provider[Portable provider core] + Provider --> HTTP[Signed DynamoDB or authenticated celld HTTP] +``` + +### Credentials and rotation + +The `credentials.secrets` and `token_secret.secrets` fields name a logical +`[stores.secrets]` ID. On Fastly, bind that ID to the Secret Store holding these +keys. Key names derive from the KV ID, not from arbitrary names in the document: + +| KV ID | Secret keys | +| ---------- | -------------------------------------------------------------------------------------------------------------------- | +| `identity` | `KV__IDENTITY__AWS_ACCESS_KEY_ID`, `KV__IDENTITY__AWS_SECRET_ACCESS_KEY`, optional `KV__IDENTITY__AWS_SESSION_TOKEN` | +| `sessions` | `KV__SESSIONS__CELLD_TOKEN` | + +Each provider reads credentials on its first operation in a request and reuses +that result only within that request. Prepared state never caches credentials +across requests. Rotation or revocation takes effect on the next request, subject +to the platform Secret Store exposing the update. An STS rotator can push +short-lived access keys, secret keys and session tokens into the derived keys +without changing provider code. Never put credential values in the TOML document. + +### Pin and validate before upload + +Save the document as `portable-stores.toml`. The bundled CLI and generated app CLI +both support this untyped command: + +```sh +edgezero config bindings pin --adapter fastly --store-bindings portable-stores.toml +edgezero config validate --adapter fastly \ + --store-bindings portable-stores.toml --manifest edgezero.toml +``` + +Pinning uses the AWS SDK credential chain to call DescribeTable through the +binding's explicit or regional endpoint. It reads the celld preflight token from +the environment variable named exactly like the derived key, here +`KV__SESSIONS__CELLD_TOKEN`, and reads the service capabilities. These are read-only +preflights, not write probes. They verify the same table/service shape as native +preparation. + +All selected preflights must succeed before the file changes. The command writes +only `pinned`, preserving endpoints, runtime credential references, comments and +unrelated fields. It never writes token values, reads typed app config or uploads +to Fastly. The CLI's default `bindings-pin` feature supplies native preflight; +SDK-free builds retain the command but report that support is not compiled. +Validation stays offline and checks declarations, portable settings, pins and the +manifest's Fastly build features without reading secrets or invoking Cargo. + +DynamoDB pins contain the table ARN and optional TableId. They scope record +bindings and cursors; the portable runtime addresses the table by name and does +no identity discovery. Native startup rejects a mismatched pin. Do not recreate a +bound table in place. Recreation discards allocator rows, so old generation tokens +can collide just as they can after deleting allocator state. If recreation is +unavoidable, re-pin and redeploy the bindings before serving, and treat every +outstanding generation as invalid. Converting a pinned table to a global table +is unsupported. + +celld pins contain the store instance. Every record request carries that expected +instance. A reset or replacement store fails the check until you re-pin and +redeploy the bindings. This does not detect rollback of a snapshot that retains +the same instance. + +### Upload the bindings document + +Uploading remains an operator action. After creating and linking the Config Store, +set `BINDINGS_STORE_ID` to its physical Fastly store ID. Create the entry once: + +```sh +fastly config-store-entry create --store-id="$BINDINGS_STORE_ID" \ + --key=EDGEZERO__STORE_BINDINGS --stdin < portable-stores.toml +``` + +For later updates, or an idempotent create/update: + +```sh +fastly config-store-entry update --store-id="$BINDINGS_STORE_ID" \ + --key=EDGEZERO__STORE_BINDINGS --upsert --stdin < portable-stores.toml +``` + +`config push` publishes typed app configuration, not this bindings document. + +### Deadlines and uncertain writes + +Portable providers default to a 1,000 ms whole-operation deadline and a 250 ms +connect timeout. DynamoDB per-binding `[kv..limits]` may override those values; +celld uses the defaults. Native defaults remain 5,000 ms and 1,000 ms. +A DynamoDB insert allocates a generation with UpdateItem, then writes the value +with PutItem. Both sequential calls share one deadline, including Add and CAS. +A celld write makes one service call. Neither portable transport retries. + +| Outcome | Meaning | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `PreconditionFailed` | Definitive Add/CAS rejection. Reload, merge or retry only according to application policy. | +| `Unavailable` | A read failed, a value mutation was not dispatched, or the service definitively rejected it. This is not a successful miss. | +| `MutationUncertain` | A dispatched value mutation may have committed, for example after a timeout, reset, 5xx or unreadable acknowledgement. Reconcile before deciding whether to issue another write. | + +Pending before merge: real Fastly conditional-write p50/p95 measurements for both +providers against `us-east-1` have not been recorded. Add the named POP, sampling +method and build/config identity under `docs/audits/evidence/`. Local and Viceroy +results do not substitute for that latency evidence. + +See [DynamoDB KV](./dynamodb-kv#portable-dynamodb-records) for endpoint and IAM +requirements, and [celld stores](./native-celld-stores#portable-celld-records-on-fastly) +for authenticated HTTPS setup. + ## Binding limits Existing portable key, body, TTL and page validation still applies, followed by diff --git a/docs/guide/native-celld-stores.md b/docs/guide/native-celld-stores.md index e4735e663..9ab29bda1 100644 --- a/docs/guide/native-celld-stores.md +++ b/docs/guide/native-celld-stores.md @@ -1,6 +1,6 @@ -# Native celld stores +# celld stores -The native `celld-kv` provider gives an Axum application live KV backed by [celld](https://celld.dev). It talks over HTTP to the EdgeZero store service, a small Worker and Durable Object application in [`services/celld-store`](https://github.com/IABTechLab/edgezero/tree/main/services/celld-store) that the official celld release runs unmodified. +The native `celld-kv` provider gives an Axum application live KV backed by [celld](https://celld.dev). It talks over HTTP to the EdgeZero store service, a small Worker and Durable Object application in [`services/celld-store`](https://github.com/IABTechLab/edgezero/tree/main/services/celld-store) that the official celld release runs unmodified. Fastly can use the same service through the [portable celld record provider](#portable-celld-records-on-fastly). This page targets celld v0.6.3. Local tests do not establish fleet capacity, production bucket durability or deployment security. @@ -42,8 +42,8 @@ a fresh generation. No-TTL replacements remove prior expiry. The namespace allocator survives value deletion and sweeping. Conditional writes and physical existence use the retained row, while lookup/list filter -expired values until physical cleanup. Native celld retries are answered from -the mutation ledger, including the original precondition rejection; the Rust +expired values until physical cleanup. celld's internal redeliveries are answered +from the mutation ledger, including the original precondition rejection; the Rust client never retries automatically. Same-instance snapshot rollback is still not detected. @@ -51,6 +51,79 @@ See [conditional KV records](./kv-records) for the shared API, limits and pagination contract. The generated feature is `celld-records`; the provider crate feature is `records`. No celld config provider is added. +## Portable celld records on Fastly + +Enable the generated Fastly adapter's default-off `celld-records` feature: + +```toml +[adapters.fastly.build] +features = ["celld-records"] +``` + +The standalone store crate feature is `portable-records`; native Axum continues +using `records`. Both transports share record API version 1, `rows-v1` encoding, +metadata limits, mutation IDs and cursor validation. No celld server, V8, reqwest +or native executor is linked into the portable provider. + +Use this unpinned input alongside the logical `[stores.kv]` ID `sessions` and +`[stores.secrets]` ID `stores` in the application manifest: + +```toml +version = 1 + +[kv.sessions] +provider = "celld-records" +endpoint = "https://celld.example.net" +store = "sessions" +access = { mode = "authenticated", token_secret = { secrets = "stores" } } +``` + +Portable celld accepts only authenticated HTTPS with `token_secret`. +`trusted-network` and `token_env` are native-only. Axum rejects `token_secret` and +keeps its startup environment token source. For authenticated access, put a TLS +terminator with a valid certificate in front of stock celld. Authentication does +not disable certificate verification. + +For preflight, supply `KV__SESSIONS__CELLD_TOKEN` through the operator process's +environment, then run: + +```sh +edgezero config bindings pin --adapter fastly --store-bindings portable-stores.toml +edgezero config validate --adapter fastly \ + --store-bindings portable-stores.toml --manifest edgezero.toml +``` + +The environment variable name is exactly the derived runtime secret key for this +KV ID. Pinning calls the read-only capabilities endpoint and inserts +`pinned = { instance = "" }` without changing the +`token_secret` reference. It never probes with a write or stores the token value. +Validation is offline and reads no token. + +At runtime, the logical Fastly Secret Store supplies `KV__SESSIONS__CELLD_TOKEN` +on the provider's first operation per request. It is reused within that request +only. The next request reads the current value, so updates and revocation do not +wait for a cached token in a retained application. Service policy changes still +follow celld's deployment adoption described below. + +Every record request sends `x-edgezero-expected-instance` with the pinned instance. +A store reset or replacement fails requests until the bindings are re-pinned and +redeployed. Restoring a snapshot with the same instance is not detected. +The Fastly runtime does no capabilities discovery or other preparation I/O. + +Portable celld uses a 1,000 ms operation deadline and a 250 ms connect timeout, +compared with native defaults of 5,000 ms and 1,000 ms. A write is one service call; +the portable client never retries it. A definitive Add/CAS rejection is +`PreconditionFailed`. A failure before dispatch or definitive service rejection is +`Unavailable`; a dispatched value mutation whose result is unknown is +`MutationUncertain`. Reconcile before issuing a new write. + +Follow [portable providers on Fastly](./kv-records#portable-providers-on-fastly) +for the Config Store entry, build-feature forwarding, manual upload, no-fallback +rules and pending hosted latency evidence. The provider also compiles for +Cloudflare and Spin targets; their runtime wiring remains +[#479](https://github.com/IABTechLab/edgezero/issues/479) and +[#484](https://github.com/IABTechLab/edgezero/issues/484). + ## Bind a logical store The application declares logical IDs in `edgezero.toml`: diff --git a/docs/superpowers/plans/2026-11-19-portable-record-providers.md b/docs/superpowers/plans/2026-11-19-portable-record-providers.md new file mode 100644 index 000000000..934190e25 --- /dev/null +++ b/docs/superpowers/plans/2026-11-19-portable-record-providers.md @@ -0,0 +1,328 @@ +# Portable record providers implementation plan + +Status, 2026-11-19: implemented on this branch through `ed552e83`; local and real-service acceptance passes. Open before merge: real Fastly p50/p95 latency evidence (P11), which needs a separately authorized scratch Fastly service, and review. The native Fastly KV CAS/Add emulator limitation remains a separately disclosed baseline result. + +Worktree: `/home/pav/worktrees/feat-474-portable-record-providers`, branch `feat/474-portable-record-providers`, based on `origin/feat/portable-client-info` at `10ed38035cfa1ab2c88005f113720ff99a233893`. This already includes outbound HTTP and the native record contract. No merge is needed. + +The [agreed design](../specs/2026-11-19-portable-record-providers-design.md) owns behavior. This file owns implementation tasks and verification. Deliver one EdgeZero PR for [#474](https://github.com/IABTechLab/edgezero/issues/474), stacked on #517. Do not push, open a PR, merge or deploy without separate permission. + +## Delivery contract + +- One row/cursor/validation/error-classification core per provider, with native and portable transports beneath it. Existing Axum callers and unpinned native bindings keep their behavior. +- Portable celld requires HTTPS and bearer authentication. Portable DynamoDB uses JSON 1.0 and `aws-sigv4`, not the AWS SDK. Neither transport retries. +- Fastly selects each declared KV ID from the runtime bindings document. Unbound IDs remain Fastly KV. Invalid or unavailable configured providers fail without fallback. +- Prepared settings, pins and secret references live on the retained App. The bound provider and lazy credentials belong to one request. No runtime DescribeTable, capabilities call or preparation write. +- Portable defaults are a 1,000 ms whole-operation deadline and 250 ms connect timeout. DynamoDB allocation and value mutation share that deadline. Native defaults stay 5,000/1,000 ms. +- Required proof includes two-way native/portable interoperability, both portable providers' Viceroy contracts, independent Add/CAS races, 1001-key pages, required CI, three-target compilation and real Fastly latency evidence before merge. +- Cloudflare and Spin receive provider compile checks only. Their runtime wiring, native store replacement, migration and hosted IAM/capacity qualification stay outside this PR. + +## Execution order + +```mermaid +flowchart TB + A[0. Facts and baseline] --> B[1. Shared provider cores and native transports] + B --> C[2. Shared settings and strict bindings] + C --> D[3. Portable celld] + C --> E[4. Portable DynamoDB] + D --> F[5. Fastly request binding and secrets] + E --> F + C --> G[6. Offline pin command] + F --> H[7. Interop and Viceroy acceptance] + G --> H + H --> I[8. Dependency checks and required CI] + I --> J[9. Docs, hosted evidence and stable gates] +``` + +Each numbered unit ends with its focused tests before the next dependent unit. Run affected `cargo test` selections after code changes. Keep one command owner per Cargo target directory, generated workspace and mutable service fixture. Reuse passing checks while their relevant inputs remain unchanged. New feature, module and test names below are planned names, not existing APIs. + +## 0. Confirm facts and establish the baseline + +- [x] Read the complete agreed spec, `gh issue view 474`, the record guide and the referenced native provider, Fastly, Axum and runner code. +- [x] Confirm HEAD and the local parent ref both equal `10ed38035cfa1ab2c88005f113720ff99a233893`. The supplied design spec was the only untracked input at arrival. +- [x] Confirm `aws-sigv4 1.6.0` with `sign-http,http1` builds for `wasm32-wasip1`, `wasm32-unknown-unknown` and `wasm32-wasip2`. Execute timestamp/signing probes in WASI Preview 1, Preview 2 and a JavaScript host. +- [x] Execute a pinned Viceroy Config Store, Secret Store and wall-clock smoke request using the exact runtime names and derived secret-key shape from the spec. +- [x] Confirm prepared state fits existing `App::insert_state(Arc)` and `App::state::>()`, retained through `Sandbox`. Record evidence and qualifications in the spec. +- [x] After approval, run focused native provider and startup baselines before extraction. Capture commands, counts, code identity and logs in this plan. +- [x] Reproduce the existing Fastly `record-contract` suite once on the unchanged baseline with the pinned Viceroy. The earlier record plan records a native CAS two-winner failure in Viceroy `0.21.0`, and `scripts/run_tests.sh` runs `--adapter fastly --suite ci`, which includes that suite. Record the failure signature, or a pass, before any change. Treat it as a known baseline result, not a regression from this work. + +Fact-check output and source are retained under `/home/pav/.cache/edgezero-474-facts/`. Rust is `+1.98.1`. Wasmtime is `48.0.2`. Use the explicit pinned/repaired Viceroy from the spec, not the PATH `0.17.0` executable. These probes establish dependency, clock and local-store support, not record-provider acceptance. + +Exit: no contradictory fact is known. If implementation uncovers one, stop and report it rather than substitute a different design. + +## 1. Extract provider cores while preserving native behavior + +Files: + +- `crates/edgezero-store-aws/src/dynamodb_records.rs`, `dynamodb_kv.rs`, settings/preparation and record tests. +- `crates/edgezero-store-celld/src/records.rs`, `client.rs`, settings/preparation and record tests. +- Both provider `Cargo.toml` files and `src/lib.rs` feature gates. + +Work: + +- [x] Separate provider policy from SDK/reqwest mechanics. Each core owns row encoding, generation handling, limits, kind checks, scope and cursor validation, and normalized failure classification. +- [x] Add a small SDK-free DynamoDB attribute model for the record format's strings, numbers and binary bytes. Define only the six operation inputs/results the existing core needs. Native conversion rejects unsupported/malformed types; do not expose `AttributeValue`, SDK builders or `SdkError` to the core. +- [x] Keep AWS preparation, SDK configuration and timeout execution native. Preserve strong GetItem/Query, unordered Scan, retained `g#` allocators, `r#` values, exact cursor encoding and the endpoint/ARN/optional TableId/region/table/namespace scope tuple. +- [x] Separate celld exchange construction and response validation from reqwest send/stream mechanics. Reuse version/instance/content-type/strict-JSON checks, caps, mutation IDs, and no-redirect/no-decompression/no-retry policy for both transports. +- [x] Give transport failures enough dispatch/status information for the shared classifier. Preserve native classification, including conservative treatment of malformed acknowledgements and allocator-only interruption. Do not turn every error into a definitive mutation failure. +- [x] Expose native read-only identity preflight independently of RecordLayout/handle creation. Pinning must reuse validators, not invent a layout or parse `RecordBinding.scope`. +- [x] Preserve ordinary-only DynamoDB/celld paths and existing public native preparation entry points. Keep native-only runtime dependencies behind native gates. +- [x] Replace `std::time` clock reads in code shared with WASM by `web_time` equivalents. Today `DynamoDbKvLimits::validate` and `AwsPreparationLimits::validate` call `std::time::Instant::now()` (`settings.rs`), and record TTL calls `std::time::SystemTime::now()` (`dynamodb_records.rs`). Both panic on `wasm32-unknown-unknown`. `web_time` re-exports `std::time` on native targets, so Axum behavior is unchanged. + +Checks: native AWS record and legacy unit/wire tests; celld record, client and ordinary tests; affected Axum startup tests; exact row/cursor golden tests before and after extraction. Run DynamoDB Local and official-stock-celld native checks at this checkpoint so the refactor is proved through real native transports, not only doubles. + +Exit: the same native callers, rows, cursor bytes, deadlines and error outcomes work before adding portable behavior. + +## 2. Share the bindings document and distinguish validated states + +Files: + +- New feature-gated `crates/edgezero-adapter/src/store_bindings.rs` and its manifest/module export. +- Provider-owned pure settings/pin types in the two store crates. +- `crates/edgezero-adapter-axum/src/native_bindings.rs`, `native_stores.rs`, and startup tests. +- `crates/edgezero-cli/src/config.rs` and binding validation tests. + +Work: + +- [x] Extract the strict version 1 document/provider dispatch into a settings-only shared module. Keep Axum file I/O and native source selection in Axum, retaining existing public type reexports and error behavior. Fastly must not depend on the native Axum adapter. +- [x] Add an optional DynamoDB record `endpoint`, pinned identity and logical `credentials.secrets`; add celld pinned instance and authenticated `token_secret.secrets`. Keep old ordinary provider tags and fields unchanged. Reject unknown/mixed fields. +- [x] When `endpoint` is absent, derive the partition-aware regional endpoint from `region`. The spec's example binding has no endpoint, so this default is required. Normalize it with the same `endpoint_identity` function native preparation applies to its observed request URI, because the identity is part of `RecordBinding.scope` and every cursor. A mismatched string would break cursor interop. +- [x] Separate parsing a preflight input from constructing a ready portable binding. The pin command can consume an unpinned file; Fastly-ready validation requires its pins, appropriate credential source and compiled provider capability. +- [x] Validate that bound KV IDs and referenced secrets IDs are declared. Portable-provider KV IDs contain only nonempty lowercase ASCII `[a-z0-9_]`. Derive keys in one place from the KV ID; accept no arbitrary secret key field. +- [x] Reject `trusted-network` and environment-token sources for portable celld. Require HTTPS. Keep native env/SDK-chain sources; Axum rejects `credentials`, `token_secret` and the DynamoDB `endpoint`, accepts pins, and compares them with native preflight identity before publishing stores. +- [x] Preserve the optional native TableId representation and its scope encoding. Never manufacture a TableId for DynamoDB Local. Include a configured endpoint in native SDK client-cache identity if endpoint support reaches that path. +- [x] Resolve portable 1,000/250 ms defaults separately from native defaults. Keep user-specified limits validated consistently, including AWS attempt/connect/operation ordering, without resetting deadlines between requests in a single operation. +- [x] On Fastly, accept only the `aws-dynamodb-records` and `celld-records` KV providers. Reject Axum-only entries such as `aws-dynamodb`, `celld-kv`, `[config]` AppConfig and `[secrets]` Secrets Manager bindings with a typed unsupported-provider error. +- [x] Extend `config validate --adapter fastly --store-bindings ` with structural, declaration, pin and target-feature checks only. It must not read tokens, contact services, invoke Cargo or upload configuration. + +Checks: parser/feature-off tests, native binding tests, offline CLI tests with absent credentials/unreachable endpoints, typed redaction tests and pinned-mismatch startup tests. Test missing/unknown providers, undeclared secret IDs, uppercase/colliding IDs, missing pins, mixed source fields and unchanged Axum ordinary bindings. Verify the shared schema introduces no SDK/live transport into settings-only consumers. + +## 3. Add portable celld + +Files: celld core/transport modules, pure settings, manifest and focused tests. Add standalone feature `portable-records`; retain native `records` and `kv` features. + +- [x] Add prepared `Send + Sync` state holding validated settings, pin, RecordBinding and the logical secret reference. `bind(HttpClient)` returns a cheap request-bound KvStore with a fresh lazy token cache. +- [x] Use `HttpClient` for bounded exchanges. Share core request/response policy with native reqwest, including fresh mutation IDs, expected-instance header on every record call, strict metadata/base64/generation checks, content type, size limits and cursor binding. +- [x] Read the namespaced bearer token only on the first operation and reuse that result for that request. Preparation, binding and `require_records()` read no secret and perform no HTTP. +- [x] Apply the portable operation deadline and connect timeout, disabling redirects and decompression. No capability probe, retry or downgrade at runtime. +- [x] Make randomness and monotonic/wall-clock dependencies compile on all three WASM targets without adding an executor. The workspace pins `getrandom 0.4.2`; on `wasm32-unknown-unknown` it needs its `wasm_js` feature, enabled only for that target. Keep native behavior and credential sources unchanged. +- [x] Send requests with `HttpClient::send`, never `follow`, so redirects are returned, not followed. Set `ResponseDecoding` so bodies are not decoded, send `Accept-Encoding: identity`, and keep the existing rejection of non-identity `Content-Encoding`. Set `max_response_bytes` from the record or page cap, since the outbound default is 1 MiB and the celld page cap is 2 MiB. + +Checks: shared validation tests with both transports; outbound request/response fixtures for headers, errors, malformed/oversized bodies, redirects, compressed responses, stale instances and postdispatch uncertainty; no-retry request counts; no-I/O acquisition; lazy token read counts. Run native neighbors after extraction changes and compile `portable-records` for all three targets. + +## 4. Add portable DynamoDB + +Files: AWS core/portable transport/signing modules, pure settings, workspace dependencies and focused tests. Add standalone feature `dynamodb-records-portable`; retain native `dynamodb-records` and `dynamodb-kv` features. + +- [x] Build JSON 1.0 GetItem, UpdateItem, PutItem, DeleteItem, Query and Scan requests from the shared operation model. Use exact binary base64 and decimal generation/TTL representations. Preserve native projection/filter/condition expressions and continuation semantics. +- [x] Sign with the confirmed `aws-sigv4` HTTP features, service `dynamodb`, configured region, actual endpoint and payload bytes. Use portable wall time converted to the signer's `std::time::SystemTime`. Include the optional session token. +- [x] Add prepared/bound state matching celld's lifetime model. Resolve the derived access key, secret key and optional session token once on first use per request. No AWS credential chain on WASM. +- [x] Share one absolute operation deadline across UpdateItem allocation and PutItem. Match native classification: any allocation failure is Unavailable, because it cannot change a value row; an exhausted budget before PutItem dispatch is Unavailable; a definitive 4xx on PutItem is Unavailable; a transport error, timeout, 5xx or unreadable response after PutItem dispatch is MutationUncertain, as is an acknowledgement observed after the deadline expired. No automatic retry of either call. +- [x] Apply the same `send`, response-decoding and response-size settings as portable celld. Allow `http` endpoints only on loopback, for DynamoDB Local; require `https` otherwise. This mirrors the existing celld loopback rule and is a recorded decision. +- [x] Parse service error `__type` and map definitive conditional rejection only for Add/CAS. Use the shared native classifier for other failures, redacting response bodies and credentials from errors/logs. +- [x] Keep consistent-read flags, native TTL visibility, item/payload caps, allocator exhaustion checks, Query membership checks and filtered/empty Scan continuation unchanged. + +Checks: deterministic signing vectors, session-token/no-token cases, all six wire shapes, native/portable normalization parity, conditional-error spellings, predispatch failure, transport reset, 4xx/5xx, unreadable acknowledgements, one shared two-call deadline and request-count assertions. Compile the portable feature for all three WASM targets. + +## 5. Wire Fastly prepared providers and request-local secrets + +Files: + +- `crates/edgezero-adapter-fastly/src/lib.rs`, `request.rs`, `config_store.rs`, a focused new bindings module, and tests. +- Adapter `Cargo.toml` and `crates/edgezero-adapter-fastly/src/templates/Cargo.toml.hbs`. + +- [x] Add default-off `aws-dynamodb-records` and `celld-records` adapter features forwarding to the portable provider features. Add matching forwarding features to the generated Fastly crate template and generator tests, like the existing Axum forwarding assertions in `crates/edgezero-cli/src/generator.rs`. The bindings parser must still recognize and reject configured providers absent from the binary. +- [x] Make `[adapters.fastly.build] features` reach the WASM `cargo build`. Today only Axum forwards manifest build features to Cargo (`crates/edgezero-cli/src/adapter.rs`, which checks `eq_ignore_ascii_case("axum")`). The Fastly path runs `fastly compute build`, whose `[scripts] build` command in the generated `fastly.toml` has no features. The app-demo already declares `features = ["fastly"]` for Fastly without effect. Choose the forwarding mechanism in this unit and prove it with a generated-project build that enables both provider features. +- [x] Read optional Config Store `edgezero_store_bindings`, entry `EDGEZERO__STORE_BINDINGS`, reusing existing optional-open/error distinctions and the platform's 8,000-character entry model. Missing configuration means native bindings; parse/open/read failures must not masquerade as missing configuration. +- [x] After App construction and sealed record declarations, validate and install `Arc` with `App::insert_state`. Keep only settings, pins, bindings and logical/stateless secret references there. Leave Sandbox lifecycle unchanged. +- [x] Defer canonical manifest KV binding until request preparation extensions have merged into the core request. Clone that request's effective HttpClient, including a hook-supplied override, and bind portable providers there. Do not create a second unrelated client before the hook runs. +- [x] Construct each request's KV registry with portable providers for explicit bindings and the existing declared FastlyKvStore for absent bindings. Keep explicit FastlyService/manual handle precedence unchanged. Validate record requirements after binding. +- [x] Resolve declared logical Secret Store aliases using existing stateless SecretHandle/BoundSecretStore support. Cache plaintext/results only inside the newly bound provider, never on App or in a global. Ensure the lazy cache meets KvStore's Send + Sync bounds and concurrent first-use behavior. +- [x] Validate the bindings document in `build_target_app`. A document that fails to parse, or names a provider absent from the binary, fails App assembly with a typed error. Every request then receives the existing assembly-error response, and `Sandbox` retries construction on the next request. Never fall back to Fastly KV, and never include secret values in diagnostics. + +Checks: missing/valid/malformed bindings, provider feature combinations, mixed native/portable IDs, declared-record validation, hook-selected client identity, unused bindings causing no secret reads or HTTP, successful-only App retention, credential read counts, and rotation/revocation across multiple requests to the same retained App. Include actual canonical adapter wiring in Viceroy acceptance, not just direct provider construction. + +## 6. Implement native bindings pin preflight + +Files: CLI `args.rs`, `main.rs`, `lib.rs`, a focused bindings/preflight module, `config.rs`, manifest/features, generated CLI template and tests. + +- [x] Add untyped `edgezero config bindings pin --adapter fastly --store-bindings ` in bundled and generated CLIs. It does not need an AppConfig type. +- [x] Keep native preflight dependencies behind an explicit `bindings-pin` Cargo feature. Enable it for the normal bundled CLI build and provide generated CLI feature forwarding. Preserve the existing SDK-free `--no-default-features --features cli,edgezero-adapter-axum` graph; a minimal binary reports that pinning support is not compiled. +- [x] Use the existing AWS SDK credential chain and shared DescribeTable validation. Send DescribeTable to the binding's explicit or derived endpoint, so preflight describes the same table the runtime uses. Check that the endpoint identity native observes equals the identity the portable runtime will derive, and fail on mismatch. Capture the native ARN/TableId representation. +- [x] For celld, use the same capabilities/instance validators, never a write probe. Read the preflight token from an environment variable named after the derived secret key, for example `KV__SESSIONS__CELLD_TOKEN`. This needs no new flag, and the binding keeps its runtime `token_secret` reference. +- [x] Preflight every selected record binding before changing the file. Write only `pinned` back, as the spec states, without dropping unrelated TOML fields or comments. On failure leave the input unchanged. Do not replace runtime credential references with env sources. +- [x] Keep errors and success output secret-free. Do not add Config Store upload or change offline validation into online preparation. + +Checks: CLI parse/help and generated consumer tests; mock preflight failures and input preservation; malformed/unsupported targets; absent env token; exact identity capture; no mutation calls; successful pin followed by offline validation; real local native preflight against the services used in acceptance; Axum rejects stale pins. + +## 7. Prove interop and the Viceroy record contracts + +Files: + +- Native provider integration tests and the existing AWS/celld integration scripts and Node tests. +- `crates/edgezero-test-harness/src/runners/record_contract.rs`, Fastly/CI dispatch and evidence tests. +- Reusable fixture `fixture-fastly` manifest, `fastly.toml`, `src/bin/record_contract.rs`, `src/record_cases.rs`, and relevant fixture core hooks/routes. +- Root, standalone harness and reusable fixture lockfiles as required. + +- [x] Reuse pinned DynamoDB Local `3.3.1` at the existing digest and official stock celld `0.6.3` plus EdgeZero's store service. Each run owns disposable state, ports, process cleanup and artifacts. No Floci or modified celld binary. +- [x] Establish authenticated HTTPS from Viceroy to local celld early. Reuse the local TLS terminator and use process-local CA trust through Viceroy's native-root loader if supported. Prove valid cert/auth success and invalid-cert failure. Do not disable certificate checks or use trusted-network mode on WASM. +- [x] Add mandatory nonzero two-way interop tests per provider against the same table/namespace or celld store/instance. Native-write/portable-read and portable-write/native-read must preserve body, metadata, generations, conditions, ordinary access, partition/global pages and compatible cursors. Run them as Axum adapter integration tests, which have both native transports and a real EdgeZero outbound client. Enable the portable provider features there as dev-dependency features only. +- [x] In the Viceroy portable suite, also read one natively written row per provider, so the shipping Fastly path is covered by interop, not only by host tests. +- [x] Add a separate `portable-record-contract` suite to the record runner for `dynamodb-portable` and `celld-portable` receipts. Keep the existing `record-contract` suite and its `fastly-native` receipt unchanged. Each suite validates its own exact provider set, so the known native Viceroy CAS result can neither fail nor be hidden by the portable job. Portable variants use the real Config Store, logical secrets and adapter registry path. Readiness is read-only and distinct from the single mutating contract execution. +- [x] Require exactly one passing shared suite per expected provider, numeric `executed_suites = 1`, independent two-writer Add and CAS with one write/one rejection and stored-winner readback, 1001 descendants over at least two pages, all exact-existence transitions and zero remaining logical keys after cleanup. +- [x] Drain global cleanup pages to exhaustion, including empty pages with cursors, and detect repeated continuation. Never delete DynamoDB allocator rows to make cleanup pass. +- [x] Put provider identity on every relevant receipt/event. Add negative validator tests for missing, duplicate, failed, substituted, zero-count and malformed evidence. One provider's success must not satisfy another provider's requirements. +- [x] Retain staged WASM/config/runtime hashes, exact runtime version, service identity, build/runtime logs and `qualification = false`. Add real transport uncertainty/no-replay proofs without representing emulator timings as POP latency. +- [x] Preserve existing native Fastly assertions. The historical Viceroy CAS two-winner limitation remains a separately disclosed baseline issue unless new direct evidence clears it. Do not repair Viceroy, weaken one-winner assertions or present portable receipts as clearing native CAS. +- [x] If controller functions change, inspect those changes and explicitly review/update ownership fingerprints and tests. Do not blindly regenerate fingerprints or loosen evidence bounds. + +Checks: runner/fixture unit tests and negative receipts, extended Node runner tests, required nonzero native/portable interop tests, pinned Viceroy `portable-record-contract` suite, then the `record-contract` and full Fastly `ci` suites compared with the task 0 baseline. Failed/skipped/zero-test service execution is not a pass. + +## 8. Enforce portable dependencies, compilation and required CI + +Files: `scripts/check_native_store_dependency_contract.sh`, existing dependency-policy tests, `scripts/run_tests.sh`, `.github/workflows/test.yml` and any focused new portable-record runner script/tests. + +- [x] Extend isolated graphs for each portable provider feature, individually and together on Fastly. Check all three WASM targets and default-off/native-only builds. Require signing dependencies only when the portable DynamoDB feature is enabled. +- [x] Preserve bans on aws-config/aws-sdk*, reqwest, server celld and native runtimes in portable graphs. Preserve the core-wide Tokio ban and existing Tokio-feature-aware checks outside core. Do not add broad exemptions or version allowlists. +- [x] Add compile-only CI commands for the two portable provider features on `wasm32-unknown-unknown` and `wasm32-wasip2`, plus Fastly `wasm32-wasip1`. Feature-off settings checks alone cannot satisfy P12. +- [x] Add an unconditional CI job `portable-record-contracts`, named `Portable record contracts (Fastly)`, with pinned Viceroy, DynamoDB Local and official celld. Run the `portable-record-contract` suite, independent races, pages, cleanup and interop with strict receipts. The existing native suite stays in its current job. +- [x] CI does not provision official celld today; the existing celld runner only requires a local `CELLD_BIN`. Download the pinned `0.6.3` release in CI and verify its SHA256 before use, with the same version and hash checks `scripts/run_native_celld_integration.mjs` applies. Cache it like the existing Viceroy step. +- [x] Integrate the new runner into the prescribed local suite and artifact validation. Preserve exact nonzero execution checks, failure propagation and service cleanup; upload evidence on failure too. + +Branch-protection required-check configuration is a repository setting, not a workflow file. Report `Portable record contracts (Fastly)` for maintainers to mark as required. Do not modify GitHub settings without permission. + +## 9. Document operations, collect hosted evidence and run stable gates + +Files: `docs/guide/kv-records.md`, `docs/guide/dynamodb-kv.md`, `docs/guide/native-celld-stores.md`, relevant CLI documentation, and a new receipt under `docs/audits/evidence/`. + +- [x] Document Fastly build features, runtime TOML, the optional DynamoDB endpoint and its regional default, pinned identities, the preflight command and its derived token variable, logical Secret Store declaration and all derived keys. Include optional AWS session token and next-request rotation/revocation. +- [x] Give a least-privilege runtime IAM policy for GetItem, UpdateItem, PutItem, DeleteItem, Query and Scan on one table. DescribeTable belongs to offline preflight/native preparation, not portable runtime. Document Scan's broad read cost and unsupported post-pin global-table changes. +- [x] Document manual `fastly config-store-entry` upload, 8,000-character entry size, no-fallback behavior, stale celld instance handling and refreshing pins. Upload remains operator-owned. +- [x] Explain native versus portable timeout defaults, two sequential DynamoDB calls under one deadline, one celld call, error/uncertainty semantics and no automatic retries. +- [ ] With separately approved scratch-service access, measure real Fastly conditional writes for both providers against `us-east-1`. Record named POP, exact build/config, operation type, sample counts, successes/failures/timeouts, p50 and p95, and sampling method without secrets. Link evidence from the guide. Do not substitute local/Viceroy measurements or claim the 1,000 ms budget alone proves latency. +- [x] Run stable checks below, inspect the combined diff against `10ed3803`, and record exact counts, outcomes, evidence paths and remaining limitations here. Keep failure/uncertainty evidence separate from passes. +- [ ] Present the completed commits, checks and unverified requirements. Recheck parent/public heads before any requested publication. No push, PR, merge or deployment is authorized by plan approval alone. + +### Focused and stable command record + +All implementation commands use `+1.98.1` and locked/offline mode after intentional lockfile updates. Newly named features/tests must exist before these commands count as proof. + +```sh +# Wrappers spawn plain cargo, so select the same compiler/network policy for them. +export RUSTUP_TOOLCHAIN=1.98.1 +export CARGO_NET_OFFLINE=true + +# Native behavior and portable host-side tests. +cargo +1.98.1 test --locked --offline -p edgezero-store-aws --no-default-features --features dynamodb-records +cargo +1.98.1 test --locked --offline -p edgezero-store-celld --no-default-features --features records +cargo +1.98.1 test --locked --offline -p edgezero-store-aws --no-default-features --features dynamodb-records-portable +cargo +1.98.1 test --locked --offline -p edgezero-store-celld --no-default-features --features portable-records +cargo +1.98.1 test --locked --offline -p edgezero-adapter-axum --features aws-dynamodb-records,celld-records,test-utils +# CLI tests assume non-TTY stdin; the earlier record plan needed both settings. +RUST_TEST_THREADS=1 cargo +1.98.1 test --locked --offline -p edgezero-cli Config Store edgezero_store_bindings
entry EDGEZERO__STORE_BINDINGS"] --> P["Prepared state, Send + Sync
settings and pinned identity
kept on the retained App"] + S["Logical secrets ID
KV__ID__AWS_* or KV__ID__CELLD_TOKEN"] --> R + P --> R["Per request: bind(HttpClient) returns impl KvStore"] + R --> C["Provider core
rows, cursors, validation, error classifier"] + C --> T1["Portable transport over HttpClient
DynamoDB JSON 1.0 + SigV4, celld HTTPS + bearer"] + C --> T2["Native transport on Axum, unchanged
aws-sdk-dynamodb, reqwest"] +``` + +### Provider core and transports + +Split `dynamodb_records.rs` and celld `records.rs` into a pure core and a transport. The core owns partition keys, sort keys, allocator items, cursor encoding, size checks, value-kind checks and the error classifier. The transport exposes the provider calls the core needs and nothing else. The native transport wraps the existing SDK and `reqwest` code. Axum behavior does not change. + +The DynamoDB core cannot use SDK types such as `AttributeValue` or `SdkError` once it compiles for WASM. It needs its own small attribute model that both transports convert to and from. + +### Portable transports + +DynamoDB builds JSON 1.0 requests with `X-Amz-Target: DynamoDB_20120810.`, signs them with `aws-sigv4` using wall-clock time, and sends them through `HttpClient`. Response errors parse `__type` so `ConditionalCheckFailedException` maps to `PreconditionFailed`. + +celld reuses the existing request and response checks in `client.rs` (version headers, instance header, content type, strict JSON, size caps) over `HttpClient` instead of `reqwest`. + +Both transports set an outbound deadline and connect timeout from the binding limits. Both disable redirects and decompression to match native behavior. + +### API shape + +Each portable provider has two parts. + +- A prepared state that is `Send + Sync`. It holds parsed settings, the pinned identity, the `RecordBinding` and the secrets reference. The Fastly adapter builds it once per sandbox from the bindings document and keeps it on the retained `App`. +- `bind(HttpClient) -> impl KvStore`, which is cheap. The adapter calls it while building the per-request KV registry, with the same `HttpClient` it builds for that request. + +The provider never reads `ctx`. `record_binding()` comes from configuration, so `require_records()` stays I/O-free. DynamoDB reports the configured payload budget. celld reports its fixed 1024-byte metadata limit. + +### Bindings on Fastly + +`edgezero.toml` only enables code: + +```toml +[adapters.fastly.build] +features = ["aws-dynamodb-records", "celld-records"] +``` + +At runtime the adapter reads the optional Config Store `edgezero_store_bindings`, entry `EDGEZERO__STORE_BINDINGS`. The entry holds the same `version = 1` schema Axum reads from its file, extended with `pinned`, `credentials`, `token_secret` and the DynamoDB `endpoint`: + +```toml +version = 1 + +[kv.identity] +provider = "aws-dynamodb-records" +region = "us-east-1" +table = "ts-identity" +namespace = "ts-prod/identity" +pinned = { table_arn = "arn:aws:dynamodb:us-east-1:111122223333:table/ts-identity", table_id = "…" } +credentials = { secrets = "stores" } + +[kv.sessions] +provider = "celld-records" +endpoint = "https://celld.example.net" +store = "sessions" +pinned = { instance = "…" } +access = { mode = "authenticated", token_secret = { secrets = "stores" } } +``` + +A Config Store entry holds at most 8,000 characters. Bindings hold no secret values, so this is enough. Parse errors and unknown providers fail the request with a typed error. They never fall back to Fastly KV. + +### Pinned identity and preflight + +`edgezero config bindings pin --adapter fastly --store-bindings ` runs native preparation from the operator's machine. DynamoDB uses DescribeTable with the AWS SDK credential chain. celld uses `/capabilities` with a token from an environment variable. The command rejects tables and services that native preparation rejects, then writes `pinned` back into the file. `config validate` stays offline. + +At runtime: + +- DynamoDB builds `RecordBinding.scope` from endpoint, pinned ARN and ID, region, table and namespace, the same tuple native builds. Cursors stay bound to one physical table. +- celld sends the pinned instance as `x-edgezero-expected-instance` on every record request. After a store reset, requests fail on instance mismatch until the binding is updated. + +Runtime IAM no longer needs DescribeTable. Converting the table to a global table after preflight breaks Add and CAS and is documented as an unsupported operator change. + +Uploading the file uses the `fastly config-store-entry` commands, documented in the guide. + +### Credentials + +`credentials = { secrets = "" }` names a declared `[stores.secrets]` ID. EdgeZero derives key names from the KV logical ID: + +| Provider | Keys for `[kv.identity]` | +| -------- | ------------------------ | +| DynamoDB | `KV__IDENTITY__AWS_ACCESS_KEY_ID`, `KV__IDENTITY__AWS_SECRET_ACCESS_KEY`, `KV__IDENTITY__AWS_SESSION_TOKEN` (optional) | +| celld | `KV__IDENTITY__CELLD_TOKEN` | + +Bindings cannot name arbitrary keys, so a binding cannot read another component's secret. The prefix keeps keys apart on adapters with flat secrets. On Fastly the logical ID also maps to its own Secret Store. KV IDs that use these providers must match `[a-z0-9_]`, so uppercasing cannot make two IDs collide. + +The provider reads credentials on the first operation of a request and reuses them for the rest of that request. Nothing is cached across requests, so rotation and revocation take effect on the next request. + +### Axum handling of the new fields + +Axum rejects `credentials` and `token_secret`, because it keeps env and SDK-chain sources. It accepts `pinned`. Startup fails if native preparation sees a different table ARN, table ID or celld instance. + +### Errors and retries + +One classifier serves both transports. + +| Outcome | Result | +| ------- | ------ | +| `ConditionalCheckFailedException`, celld precondition rejection | `PreconditionFailed` | +| Failure before dispatch (binding, signing, backend creation, validation), definitive 4xx | `Unavailable` | +| Any failure after dispatch on a mutation (timeout, reset, 5xx, unreadable body) | `MutationUncertain` | + +There are no automatic retries. + +### Latency budget + +The enforced default for portable bindings is a 1,000 ms operation deadline and a 250 ms connect timeout. Native keeps 5,000 ms and 1,000 ms. A DynamoDB Add or CAS makes two sequential calls under one shared deadline. A celld write is one call. + +Expected cost is about 2 × POP-to-region RTT plus signing for DynamoDB and 1 × RTT for celld. Before merge, a scratch Fastly service against `us-east-1` records p50 and p95 for both providers with the POP named. The evidence goes in `docs/audits/evidence/` and the guide links it. + +### Verification + +- The Viceroy record contract runner gains `dynamodb-portable` and `celld-portable` receipts, with Add/CAS races, existence pages and cleanup for each. +- `fastly.toml` `[local_server]` supplies `edgezero_store_bindings` and fake credentials through `[local_server.secret_stores]`. +- DynamoDB Local uses the image already pinned in `run_native_aws_integration.mjs`. celld uses the official binary and the EdgeZero store service, as in the existing celld proofs. +- Interop tests cover native writes read by portable and the reverse, for both providers. +- Compile-only CI checks for `wasm32-unknown-unknown` and `wasm32-wasip2`. +- `scripts/check_native_store_dependency_contract.sh` allows the new WASM dependencies only behind the portable features. + +### Docs + +Update `docs/guide/kv-records.md`, `docs/guide/dynamodb-kv.md` and `docs/guide/native-celld-stores.md`. Cover Fastly bindings, preflight, credentials keys, the IAM policy, the upload steps and the latency evidence. + +## Facts to confirm during implementation + +Findings recorded on 2026-11-19 against `10ed38035cfa1ab2c88005f113720ff99a233893`. No factual contradiction with the agreed design was found. These checks used disposable probes outside the repository, not an implementation of the providers. + +| Fact | Finding and evidence | +| ---- | -------------------- | +| SigV4 target support | Executed. The existing lockfile's `aws-sigv4 1.6.0`, with `default-features = false` and `features = ["sign-http", "http1"]`, builds and links for all three targets using Rust `1.98.1`. The probe uses `aws-credential-types 1.3.0`, JSON request bytes, the DynamoDB signing name, `us-east-1` and an optional session token. Signing returns a 64-character signature. No SDK, HTTP client or executor is needed. The transitive Tokio features are `default,sync`, not runtime or native I/O features; the existing feature-aware dependency policy permits them outside core. | +| Wall-clock time | Executed. `web-time 1.1.0` supplies `SystemTime` on all three targets. Convert its duration since `web_time::SystemTime::UNIX_EPOCH` to `std::time::UNIX_EPOCH + duration` for the signer's input. This avoids `std::time::SystemTime::now()` on `wasm32-unknown-unknown`, where it panics. The signing probe runs under Wasmtime `48.0.2` for Preview 1 and Preview 2, and under Node `24.20.0` with `wasm-bindgen 0.2.128` for the JavaScript target. A separate Preview 1 probe reads wall time in Viceroy `0.21.0`. These are local host checks, not hosted Fastly latency evidence or Cloudflare/Spin runtime wiring. | +| Viceroy stores | Executed. Viceroy `0.21.0`, using the repaired binary recorded in the earlier record implementation plan, reads `[local_server.config_stores.edgezero_store_bindings]` with `format = "inline-toml"` and a string `EDGEZERO__STORE_BINDINGS` entry under `.contents`. It also reads `[[local_server.secret_stores.stores]]` with `key = "KV__IDENTITY__AWS_ACCESS_KEY_ID"` and fake inline `data`. One HTTP request returns `config_store=passed secret_store=passed wall_clock_epoch_s=1795123743`. The existing reusable Fastly fixture already uses these store forms. The pinned source enforces the 8,000-character entry limit in `config/dictionaries.rs`, using `DICTIONARY_ITEM_VALUE_MAX_LEN` from `config/limits.rs`. | +| Retained prepared state | Source and call path confirmed. `App::insert_state` and `App::state` already store and borrow typed `Clone + Send + Sync + 'static` state through the router. Install an `Arc` of the prepared provider map in `build_target_app` after record-declaration validation. `serve_app_with_hooks` retains that exact `App` in `Sandbox`; `Sandbox::initialize` retains successful construction only. No new App field, global cache or Sandbox lifecycle is needed. Runtime retention and credential-rotation regression tests remain implementation work. | + +### Reproduction and implementation consequences + +The local evidence is retained under `/home/pav/.cache/edgezero-474-facts/`. It includes the probe manifests, lockfiles and sources, `confirmed.log`, `js-probe.log`, and `viceroy/response.txt`. The disposable build directories are `/tmp/ez474-facts/` and `/tmp/ez474-viceroy-facts/`. The signing probe started from a copy of the repository lockfile; no repository dependency or source file changed for these checks. + +```sh +# In /tmp/ez474-facts, once its retained probe sources are in place. +for target in wasm32-wasip1 wasm32-unknown-unknown wasm32-wasip2; do + cargo +1.98.1 build --locked --offline --bin ez474-facts --target "$target" +done +# Execute the Preview 1 and Preview 2 binaries with Wasmtime 48.0.2. +# Generate the JavaScript library with wasm-bindgen 0.2.128, then: +node -e 'require("./js/ez474_facts.js").run()' +``` + +The successful WASI runs each reported `wall_clock_epoch_s=1795123812 sigv4_hex_len=64`. The JavaScript run reported `unknown-unknown web-time and SigV4 passed`. The scratch library also produces a harmless unused-main warning on WASI. Initial probe attempts hit a missing Wasmtime shim version and two scratch-code SDK type errors; explicit installed executables and corrected probe code produced the results above. These were not provider build failures. + +The Viceroy executable used was `/home/pav/.cache/rc-refresh-20261110/target-viceroy-repair/debug/viceroy`, SHA256 `c846e8db180beeb1477fb504ec1d89c09251203633cd98c7fd9d97abbd7b9755`. The PATH executable reports `0.17.0` and must not be used as the pinned runtime. No Viceroy patch or pin changed. + +Source locations for retention are `crates/edgezero-core/src/app.rs`, methods `insert_state` and `state`; `crates/edgezero-adapter-fastly/src/lib.rs`, functions `build_target_app` and `serve_app_with_hooks`; and `crates/edgezero-adapter-fastly/src/lifecycle.rs`, `Sandbox::initialize`. + +Two request/test details must be preserved during implementation: + +- The canonical KV registry is currently assembled before the request's `HttpClient` exists. Bind portable stores after request preparation extensions have merged, so they clone the same effective client as `ctx.http_client()`, including a hook-supplied client. +- DynamoDB cleanup must drain global Scan continuation even when a page has no logical keys. Allocator rows remain after value deletion. The fixture's current first-page-only cleanup assertion is Fastly-specific; do not delete allocators to satisfy it. +- Code shared with WASM must read clocks through `web_time`. The AWS settings validators call `std::time::Instant::now()` and DynamoDB record TTL calls `std::time::SystemTime::now()`; both panic on `wasm32-unknown-unknown`. +- `[adapters.fastly.build] features` is not forwarded to Cargo today. Only the Axum path forwards manifest build features, so Fastly needs that wiring before the example in this spec takes effect. + +Authenticated local celld TLS through Viceroy still needs an executed trust-path check. Viceroy loads native certificate roots through `rustls-native-certs`; a process-local test CA is a candidate without disabling certificate verification. The historical native Fastly CAS emulator limitation recorded in the earlier record implementation plan is not cleared by these probes. Neither limitation changes the settled provider contract. diff --git a/examples/app-demo/Cargo.lock b/examples/app-demo/Cargo.lock index 63d8f5b3c..240165d79 100644 --- a/examples/app-demo/Cargo.lock +++ b/examples/app-demo/Cargo.lock @@ -177,6 +177,15 @@ dependencies = [ "validator", ] +[[package]] +name = "arc-swap" +version = "1.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "84a22b5d51209f6de83d37a0b33d320acb8da88823e42a94c075140708f032a5" +dependencies = [ + "rustversion", +] + [[package]] name = "async-compression" version = "0.4.43" @@ -234,6 +243,49 @@ version = "1.5.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" +[[package]] +name = "aws-config" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8d7b388a9fc3a6db15a5ec778c38b354eff1364882c94d08e0252f7a47dcaa4" +dependencies = [ + "aws-credential-types", + "aws-runtime", + "aws-sdk-sso", + "aws-sdk-ssooidc", + "aws-sdk-sts", + "aws-smithy-async", + "aws-smithy-http", + "aws-smithy-json", + "aws-smithy-runtime", + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "aws-types", + "bytes", + "fastrand", + "hex", + "http 1.4.2", + "sha1", + "time", + "tokio", + "tracing", + "url", + "zeroize", +] + +[[package]] +name = "aws-credential-types" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e93964ffdaf57857f544be3666a5f57570bb699e934700f11b49708f61bb556e" +dependencies = [ + "aws-smithy-async", + "aws-smithy-runtime-api", + "aws-smithy-types", + "zeroize", +] + [[package]] name = "aws-lc-rs" version = "1.18.1" @@ -257,6 +309,356 @@ dependencies = [ "pkg-config", ] +[[package]] +name = "aws-runtime" +version = "1.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b8a9911551b4ea6ca13805ef52ed96f7d2bbb43cc3b4a14cb0776a71f33cfaa" +dependencies = [ + "aws-credential-types", + "aws-sigv4", + "aws-smithy-async", + "aws-smithy-http", + "aws-smithy-runtime", + "aws-smithy-runtime-api", + "aws-smithy-types", + "aws-types", + "bytes", + "bytes-utils", + "fastrand", + "http 1.4.2", + "http-body", + "percent-encoding", + "pin-project-lite", + "tracing", + "uuid", +] + +[[package]] +name = "aws-sdk-dynamodb" +version = "1.120.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f578638cafe182113da770e9798e7063d6de96cbbfe06f647d0026f197c9b97c" +dependencies = [ + "arc-swap", + "aws-credential-types", + "aws-runtime", + "aws-smithy-async", + "aws-smithy-http", + "aws-smithy-json", + "aws-smithy-observability", + "aws-smithy-runtime", + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "aws-types", + "bytes", + "fastrand", + "http 0.2.12", + "http 1.4.2", + "regex-lite", + "tracing", + "url", +] + +[[package]] +name = "aws-sdk-sso" +version = "1.114.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "12be2f9c8eef7f5fc919c96d538e629698469a02b4cb75408b26b1bd984ebe79" +dependencies = [ + "arc-swap", + "aws-credential-types", + "aws-runtime", + "aws-smithy-async", + "aws-smithy-http", + "aws-smithy-json", + "aws-smithy-observability", + "aws-smithy-runtime", + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "aws-types", + "bytes", + "fastrand", + "http 1.4.2", + "regex-lite", + "tracing", +] + +[[package]] +name = "aws-sdk-ssooidc" +version = "1.116.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d7645db8724ea3b82fdccfb67e1b0f637c9d8ab0e7ef29d84884d8d8d73f805d" +dependencies = [ + "arc-swap", + "aws-credential-types", + "aws-runtime", + "aws-smithy-async", + "aws-smithy-http", + "aws-smithy-json", + "aws-smithy-observability", + "aws-smithy-runtime", + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "aws-types", + "bytes", + "fastrand", + "http 1.4.2", + "regex-lite", + "tracing", +] + +[[package]] +name = "aws-sdk-sts" +version = "1.119.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03e490aa904849b38e770922faac779dd245f5cf8be81f19065acf18d276e4ad" +dependencies = [ + "arc-swap", + "aws-credential-types", + "aws-runtime", + "aws-smithy-async", + "aws-smithy-http", + "aws-smithy-json", + "aws-smithy-observability", + "aws-smithy-query", + "aws-smithy-runtime", + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "aws-smithy-xml", + "aws-types", + "fastrand", + "http 1.4.2", + "regex-lite", + "tracing", +] + +[[package]] +name = "aws-sigv4" +version = "1.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2312577f088c9fbf4206dfdb884cf1de9407b43e1a923cbed5237775116fc24b" +dependencies = [ + "aws-credential-types", + "aws-smithy-http", + "aws-smithy-runtime-api", + "aws-smithy-types", + "bytes", + "form_urlencoded", + "hex", + "hmac", + "http 1.4.2", + "percent-encoding", + "sha2 0.11.1", + "time", + "tracing", +] + +[[package]] +name = "aws-smithy-async" +version = "1.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "de681a9df7ff79823b759ee17061076ec049cd61a8fa28ece4293d89c9f6964e" +dependencies = [ + "futures-util", + "pin-project-lite", + "tokio", +] + +[[package]] +name = "aws-smithy-http" +version = "0.64.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "639b4d8f8555f24a9be649811c3eb0b4d4616f4d61daf0c32e28873bc1ea9af1" +dependencies = [ + "aws-smithy-runtime-api", + "aws-smithy-types", + "bytes", + "bytes-utils", + "futures-core", + "futures-util", + "http 1.4.2", + "http-body", + "http-body-util", + "percent-encoding", + "pin-project-lite", + "pin-utils", + "tracing", +] + +[[package]] +name = "aws-smithy-http-client" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "51c89cc3f1f281d659a67a519a1b5c6d445b5ce09fa7e5aee40c2c2707e9509d" +dependencies = [ + "aws-smithy-async", + "aws-smithy-runtime-api", + "aws-smithy-types", + "h2", + "http 1.4.2", + "hyper", + "hyper-rustls", + "hyper-util", + "pin-project-lite", + "rustls", + "rustls-native-certs", + "rustls-pki-types", + "tokio", + "tokio-rustls", + "tower", + "tracing", +] + +[[package]] +name = "aws-smithy-json" +version = "0.63.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3385d469edbe8b60cc72002784652b5efca39178192aa9cc4b44c9875c6bdc18" +dependencies = [ + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", +] + +[[package]] +name = "aws-smithy-observability" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e86338c869539a581bf161247762a6e87f92c5c075060057b5ed6d06632ed0c" +dependencies = [ + "aws-smithy-runtime-api", +] + +[[package]] +name = "aws-smithy-query" +version = "0.62.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1d1d71f6562be974caa85442ecd90194c40fdb5df045f182a6c2e872ce95056" +dependencies = [ + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "aws-smithy-xml", + "urlencoding", +] + +[[package]] +name = "aws-smithy-runtime" +version = "1.16.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6e302ac1d88b99652489df31abdec6ac42a2ab2ac3982ad0ac49f64dfaf28ba" +dependencies = [ + "aws-smithy-async", + "aws-smithy-http", + "aws-smithy-http-client", + "aws-smithy-observability", + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "bytes", + "fastrand", + "http 1.4.2", + "http-body", + "http-body-util", + "pin-project-lite", + "pin-utils", + "tokio", + "tracing", +] + +[[package]] +name = "aws-smithy-runtime-api" +version = "1.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c0730c16f91124c6a2abb4932c77e299288b3dd9f967ea2e9ec48cc6731e87a4" +dependencies = [ + "aws-smithy-async", + "aws-smithy-runtime-api-macros", + "aws-smithy-types", + "bytes", + "http 1.4.2", + "pin-project-lite", + "tokio", + "tracing", + "zeroize", +] + +[[package]] +name = "aws-smithy-runtime-api-macros" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce237f890a2283c9b328955c3b0918d2d5bf66a1cb6ceccd36a0047246fbc6e6" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "aws-smithy-schema" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e8f395d93304280b64b7632fea798d177e74897fe7f063416ce627cd6fa24829" +dependencies = [ + "aws-smithy-runtime-api", + "aws-smithy-types", + "http 1.4.2", +] + +[[package]] +name = "aws-smithy-types" +version = "1.9.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aff4bf014c512840b2bba80a20417b723cbd6a0a65c02e2d81f50b4268aedfc7" +dependencies = [ + "base64-simd", + "bytes", + "bytes-utils", + "futures-core", + "http 1.4.2", + "http-body", + "http-body-util", + "itoa", + "pin-project-lite", + "ryu", + "serde", + "time", + "tokio", + "tokio-util", +] + +[[package]] +name = "aws-smithy-xml" +version = "0.62.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b932c8d6dc127fc980eecd78f8694ae9b9551b69a93a7def2a199c1c0033daf" +dependencies = [ + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "xmlparser", +] + +[[package]] +name = "aws-types" +version = "1.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "209f3a6d82a6e9e5f94abbed94c7a26e1c052341002bf57a5fb5481f625896fc" +dependencies = [ + "aws-credential-types", + "aws-smithy-async", + "aws-smithy-runtime-api", + "aws-smithy-schema", + "aws-smithy-types", + "rustc_version", + "tracing", +] + [[package]] name = "axum" version = "0.8.9" @@ -267,7 +669,7 @@ dependencies = [ "bytes", "form_urlencoded", "futures-util", - "http", + "http 1.4.2", "http-body", "http-body-util", "hyper", @@ -298,7 +700,7 @@ checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1" dependencies = [ "bytes", "futures-core", - "http", + "http 1.4.2", "http-body", "http-body-util", "mime", @@ -327,6 +729,16 @@ version = "0.23.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5" +[[package]] +name = "base64-simd" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "339abbe78e73178762e23bea9dfd08e697eb3f3301cd4be981c0f78ba5859195" +dependencies = [ + "outref", + "vsimd", +] + [[package]] name = "bitflags" version = "1.3.2" @@ -348,6 +760,15 @@ dependencies = [ "generic-array", ] +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + [[package]] name = "block-buffer" version = "0.12.1" @@ -400,6 +821,16 @@ version = "1.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" +[[package]] +name = "bytes-utils" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7dafe3a8757b027e2be6e4e5601ed563c55989fcf1546e933c66c8eb3a058d35" +dependencies = [ + "bytes", + "either", +] + [[package]] name = "cc" version = "1.5.1" @@ -497,6 +928,12 @@ dependencies = [ "cc", ] +[[package]] +name = "cmov" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a" + [[package]] name = "colorchoice" version = "1.0.5" @@ -589,6 +1026,16 @@ dependencies = [ "cfg-if", ] +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + [[package]] name = "crypto-common" version = "0.2.2" @@ -608,6 +1055,15 @@ dependencies = [ "linktime-proc-macro", ] +[[package]] +name = "ctutils" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "261af4dc7a06ea8a527a8717d8cbba3417530d6ea14e1edb3de6b67806be474f" +dependencies = [ + "cmov", +] + [[package]] name = "darling" version = "0.20.11" @@ -726,6 +1182,16 @@ dependencies = [ "generic-array", ] +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer 0.10.4", + "crypto-common 0.1.7", +] + [[package]] name = "digest" version = "0.11.3" @@ -734,7 +1200,8 @@ checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2" dependencies = [ "block-buffer 0.12.1", "const-oid", - "crypto-common", + "crypto-common 0.2.2", + "ctutils", ] [[package]] @@ -766,9 +1233,12 @@ version = "0.1.0" dependencies = [ "base16ct", "edgezero-core", + "edgezero-store-aws", + "edgezero-store-celld", "serde", "serde_json", "sha2 0.11.1", + "thiserror 2.0.21", "toml", "walkdir", ] @@ -790,7 +1260,7 @@ dependencies = [ "futures", "futures-util", "getrandom 0.4.2", - "http", + "http 1.4.2", "http-body", "hyper", "hyper-util", @@ -832,7 +1302,7 @@ dependencies = [ "tempfile", "toml_edit", "walkdir", - "wasm-streams", + "wasm-streams 0.6.0", "web-sys", "worker", ] @@ -906,6 +1376,8 @@ dependencies = [ "edgezero-adapter-fastly", "edgezero-adapter-spin", "edgezero-core", + "edgezero-store-aws", + "edgezero-store-celld", "futures", "handlebars", "log", @@ -913,8 +1385,11 @@ dependencies = [ "serde_json", "similar", "simple_logger", + "tempfile", "thiserror 2.0.21", + "tokio", "toml", + "toml_edit", "validator", ] @@ -940,7 +1415,7 @@ dependencies = [ "flate2", "futures", "futures-util", - "http", + "http 1.4.2", "http-body", "log", "matchit 0.9.2", @@ -979,18 +1454,38 @@ dependencies = [ name = "edgezero-store-aws" version = "0.1.0" dependencies = [ + "async-trait", + "aws-config", + "aws-sdk-dynamodb", + "aws-smithy-runtime-api", + "aws-types", + "bytes", + "edgezero-core", "percent-encoding", "serde", + "serde_json", "thiserror 2.0.21", + "tokio", "url", + "web-time", ] [[package]] name = "edgezero-store-celld" version = "0.1.0" dependencies = [ + "async-trait", + "base64 0.22.1", + "bytes", + "edgezero-core", + "futures-util", + "getrandom 0.4.2", + "reqwest", "serde", + "serde_json", + "sha2 0.11.1", "thiserror 2.0.21", + "tokio", "url", ] @@ -1051,7 +1546,7 @@ dependencies = [ "fastly-macros", "fastly-shared", "fastly-sys", - "http", + "http 1.4.2", "itertools", "mime", "serde", @@ -1083,7 +1578,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "191c2cf082f5d17f4ca0685cedaa0642ad4ade949fac8d1dbdd62ff756b13500" dependencies = [ "bitflags 1.3.2", - "http", + "http 1.4.2", ] [[package]] @@ -1094,7 +1589,7 @@ checksum = "239c77706cf9110b423a89b6b03b8011729b144390d2a7f641d95ef66b2768b8" dependencies = [ "bitflags 1.3.2", "fastly-shared", - "http", + "http 1.4.2", "wasip2", "wit-bindgen 0.51.0", ] @@ -1290,6 +1785,25 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "h2" +version = "0.4.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7d29020232d6aa3fb1daca64c1127cf662cf97f254ae16c18c05b8ab635fc118" +dependencies = [ + "atomic-waker", + "bytes", + "fnv", + "futures-core", + "futures-sink", + "http 1.4.2", + "indexmap", + "slab", + "tokio", + "tokio-util", + "tracing", +] + [[package]] name = "handlebars" version = "6.4.4" @@ -1330,6 +1844,32 @@ version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "hmac" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f" +dependencies = [ + "digest 0.11.3", +] + +[[package]] +name = "http" +version = "0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "601cbb57e577e2f5ef5be8e7b83f0f63994f25aa94d673e54a92d5c516d101f1" +dependencies = [ + "bytes", + "fnv", + "itoa", +] + [[package]] name = "http" version = "1.4.2" @@ -1347,7 +1887,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c" dependencies = [ "bytes", - "http", + "http 1.4.2", ] [[package]] @@ -1358,7 +1898,7 @@ checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c" dependencies = [ "bytes", "futures-core", - "http", + "http 1.4.2", "http-body", "pin-project-lite", ] @@ -1392,8 +1932,10 @@ checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c" dependencies = [ "atomic-waker", "bytes", + "futures-channel", "futures-core", - "http", + "h2", + "http 1.4.2", "http-body", "httparse", "httpdate", @@ -1410,10 +1952,11 @@ version = "0.27.10" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "dfa8e654703247911e29c23fbeaa261834bd9bb74efba2f9acddc37bfb127f53" dependencies = [ - "http", + "http 1.4.2", "hyper", "hyper-util", "rustls", + "rustls-native-certs", "tokio", "tokio-rustls", "tower-service", @@ -1429,7 +1972,7 @@ dependencies = [ "bytes", "futures-channel", "futures-util", - "http", + "http 1.4.2", "http-body", "httparse", "hyper", @@ -1876,6 +2419,12 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe" +[[package]] +name = "outref" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e" + [[package]] name = "percent-encoding" version = "2.3.2" @@ -1950,6 +2499,12 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "pin-utils" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13bee6c73da26345c729282832b60b0363cf3dd9f4bfd81d8551b7a1c889a113" + [[package]] name = "pkg-config" version = "0.3.34" @@ -2152,6 +2707,12 @@ dependencies = [ "regex-syntax", ] +[[package]] +name = "regex-lite" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cab834c73d247e67f4fae452806d17d3c7501756d98c8808d7c9c7aa7d18f973" + [[package]] name = "regex-syntax" version = "0.8.11" @@ -2169,7 +2730,7 @@ dependencies = [ "futures-channel", "futures-core", "futures-util", - "http", + "http 1.4.2", "http-body", "http-body-util", "hyper", @@ -2188,12 +2749,14 @@ dependencies = [ "sync_wrapper", "tokio", "tokio-rustls", + "tokio-util", "tower", "tower-http", "tower-service", "url", "wasm-bindgen", "wasm-bindgen-futures", + "wasm-streams 0.5.0", "web-sys", ] @@ -2483,6 +3046,17 @@ dependencies = [ "serde", ] +[[package]] +name = "sha1" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "digest 0.10.7", +] + [[package]] name = "sha2" version = "0.9.9" @@ -2608,7 +3182,7 @@ dependencies = [ "anyhow", "bytes", "futures", - "http", + "http 1.4.2", "http-body", "http-body-util", "spin-macro", @@ -2867,6 +3441,20 @@ dependencies = [ "tokio", ] +[[package]] +name = "tokio-util" +version = "0.7.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e464cf451ba96ebfc6f9b6542f17ee8b8956e33f1e40d9690624e59d7a7f8a4b" +dependencies = [ + "bytes", + "futures-core", + "futures-sink", + "libc", + "pin-project-lite", + "tokio", +] + [[package]] name = "toml" version = "1.1.6+spec-1.1.0" @@ -2944,7 +3532,7 @@ dependencies = [ "bitflags 2.13.2", "bytes", "futures-util", - "http", + "http 1.4.2", "http-body", "pin-project-lite", "tower", @@ -3045,6 +3633,12 @@ dependencies = [ "serde", ] +[[package]] +name = "urlencoding" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da" + [[package]] name = "utf8_iter" version = "1.0.4" @@ -3057,6 +3651,16 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" +[[package]] +name = "uuid" +version = "1.29.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3c14b15dffa2f4bd712103e857140aa04a4f2ff6e955c77d7eb8e53ee02a3b64" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + [[package]] name = "validator" version = "0.21.0" @@ -3097,6 +3701,12 @@ version = "0.9.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" +[[package]] +name = "vsimd" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c3082ca00d5a5ef149bb8b555a72ae84c9c59f7250f013ac822ac2e49b19c64" + [[package]] name = "walkdir" version = "2.5.0" @@ -3147,7 +3757,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d1657e9f48c63d6c3f143f70d5c6e2be7d463371a7af1ed939a5b83d3ca080d0" dependencies = [ "bytes", - "http", + "http 1.4.2", "http-body", "thiserror 2.0.21", "wit-bindgen 0.63.0", @@ -3253,6 +3863,19 @@ dependencies = [ "wasmparser 0.262.0", ] +[[package]] +name = "wasm-streams" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb" +dependencies = [ + "futures-util", + "js-sys", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", +] + [[package]] name = "wasm-streams" version = "0.6.0" @@ -3678,7 +4301,7 @@ dependencies = [ "chrono", "futures-channel", "futures-util", - "http", + "http 1.4.2", "http-body", "js-sys", "matchit 0.7.3", @@ -3692,7 +4315,7 @@ dependencies = [ "url", "wasm-bindgen", "wasm-bindgen-futures", - "wasm-streams", + "wasm-streams 0.6.0", "web-sys", "worker-macros", "worker-sys", @@ -3732,6 +4355,12 @@ version = "0.6.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" +[[package]] +name = "xmlparser" +version = "0.13.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "66fee0b777b0f5ac1c69bb06d361268faafa61cd4682ae064a171c16c433e9e4" + [[package]] name = "yoke" version = "0.8.3" diff --git a/examples/geo-kv-prototype/Cargo.lock b/examples/geo-kv-prototype/Cargo.lock index f304b74c0..852c6d133 100644 --- a/examples/geo-kv-prototype/Cargo.lock +++ b/examples/geo-kv-prototype/Cargo.lock @@ -939,6 +939,7 @@ dependencies = [ "thiserror", "tokio", "url", + "web-time", ] [[package]] diff --git a/scripts/check_native_store_dependency_contract.sh b/scripts/check_native_store_dependency_contract.sh index 344153462..308694a70 100755 --- a/scripts/check_native_store_dependency_contract.sh +++ b/scripts/check_native_store_dependency_contract.sh @@ -13,6 +13,21 @@ assert_no_sdk() { fi } +assert_sigv4() { + local expected="$1" graph + shift + graph="$(cargo tree --offline --locked --edges normal --prefix none "$@")" + if grep -Eq '^aws-sigv4 v' <<< "$graph"; then + if [[ "$expected" == absent ]]; then + printf 'AWS signing dependency leaked into isolated graph: %s\n' "$*" >&2 + exit 1 + fi + elif [[ "$expected" == present ]]; then + printf 'Portable DynamoDB signing dependency is missing: %s\n' "$*" >&2 + exit 1 + fi +} + assert_no_native_runtime() { local scope="$1" graph forbidden shift @@ -38,6 +53,28 @@ assert_no_native_runtime wasm -p edgezero-adapter-spin --target wasm32-wasip2 -- assert_no_native_runtime wasm -p edgezero-store-aws --target wasm32-wasip1 --no-default-features --features dynamodb-records assert_no_native_runtime wasm -p edgezero-store-celld --target wasm32-wasip1 --no-default-features --features records +for target in wasm32-wasip1 wasm32-unknown-unknown wasm32-wasip2; do + assert_no_native_runtime wasm -p edgezero-store-aws --target "$target" --no-default-features --features dynamodb-records-portable + assert_no_native_runtime wasm -p edgezero-store-celld --target "$target" --no-default-features --features portable-records + assert_sigv4 present -p edgezero-store-aws --target "$target" --no-default-features --features dynamodb-records-portable + assert_sigv4 absent -p edgezero-store-aws --target "$target" --no-default-features + assert_sigv4 absent -p edgezero-store-celld --target "$target" --no-default-features --features portable-records + assert_sigv4 absent -p edgezero-store-celld --target "$target" --no-default-features --features records +done +assert_sigv4 present -p edgezero-store-aws --no-default-features --features dynamodb-records-portable +assert_sigv4 absent -p edgezero-store-aws --no-default-features +assert_sigv4 absent -p edgezero-store-celld --no-default-features --features portable-records +assert_sigv4 absent -p edgezero-store-celld --no-default-features --features records +assert_sigv4 absent -p edgezero-adapter-cloudflare --target wasm32-unknown-unknown --features cloudflare +assert_sigv4 absent -p edgezero-adapter-fastly --target wasm32-wasip1 --features fastly +assert_sigv4 absent -p edgezero-adapter-spin --target wasm32-wasip2 --features spin +# Native DynamoDB's AWS SDK also requires aws-sigv4; do not ban it there. +for features in fastly,aws-dynamodb-records fastly,celld-records fastly,aws-dynamodb-records,celld-records; do + assert_no_native_runtime wasm -p edgezero-adapter-fastly --target wasm32-wasip1 --features "$features" +done +assert_sigv4 present -p edgezero-adapter-fastly --target wasm32-wasip1 --features fastly,aws-dynamodb-records +assert_sigv4 absent -p edgezero-adapter-fastly --target wasm32-wasip1 --features fastly,celld-records + assert_no_sdk -p edgezero-cli --no-default-features --features cli,edgezero-adapter-axum assert_no_sdk -p edgezero-store-aws --no-default-features assert_no_sdk -p edgezero-store-aws --no-default-features --features appconfig-agent diff --git a/scripts/fetch_official_celld.mjs b/scripts/fetch_official_celld.mjs new file mode 100644 index 000000000..d59edb9f5 --- /dev/null +++ b/scripts/fetch_official_celld.mjs @@ -0,0 +1,68 @@ +#!/usr/bin/env node +import { execFile } from "node:child_process"; +import { createHash } from "node:crypto"; +import { chmod, mkdir, readFile, writeFile } from "node:fs/promises"; +import { homedir } from "node:os"; +import { join, resolve } from "node:path"; +import { pathToFileURL } from "node:url"; +import { promisify } from "node:util"; +import { gunzip } from "node:zlib"; + +// Official denoland/celld v0.6.3 release asset and GitHub release SHA256 digest. +// Confirmed with `gh release view v0.6.3 -R denoland/celld`. +// Binary identity: docs/superpowers/specs/2026-11-16-stock-celld-store-service-design.md:158, +// which also records the archive hash prefix/suffix and attestation verification. +export const CELLD_RELEASE_URL = "https://github.com/denoland/celld/releases/download/v0.6.3/celld-x86_64-unknown-linux-gnu.gz"; +export const CELLD_ARCHIVE_SHA256 = "5084a083472cf036551a7eac63fa24d22bb9a56323c517f63205724c12783047"; +export const CELLD_BINARY_SHA256 = "eb0a8158421b69d68dd5d28f2298a7d411dde498295833deeb1cc5ce53b7eb75"; +export const CELLD_VERSION = "celld 0.6.3"; + +export function verifyDigest(bytes, expected, label) { + const actual = createHash("sha256").update(bytes).digest("hex"); + if (actual !== expected) { + throw new Error(`${label} SHA256 mismatch: expected ${expected}, got ${actual}`); + } +} + +async function download(url) { + const response = await fetch(url); + if (!response.ok) throw new Error(`celld download failed: HTTP ${response.status}`); + return Buffer.from(await response.arrayBuffer()); +} + +// stdout is reserved for the absolute CELLD_BIN path. Every cache restore is +// reverified, and the executable is recreated from the verified archive. +export async function provisionCelld({ + cacheDirectory = join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "edgezero-stock-celld", "v0.6.3"), + fetchArchive = download, +} = {}) { + const directory = resolve(cacheDirectory); + const archivePath = join(directory, "celld-x86_64-unknown-linux-gnu.gz"); + const binaryPath = join(directory, "celld"); + let archive; + try { + archive = await readFile(archivePath); + } catch (error) { + if (error.code !== "ENOENT") throw error; + archive = await fetchArchive(CELLD_RELEASE_URL); + } + verifyDigest(archive, CELLD_ARCHIVE_SHA256, "celld archive"); + const binary = await promisify(gunzip)(archive); + verifyDigest(binary, CELLD_BINARY_SHA256, "celld binary"); + await mkdir(directory, { recursive: true }); + await writeFile(archivePath, archive); + await writeFile(binaryPath, binary); + await chmod(binaryPath, 0o755); + const { stdout } = await promisify(execFile)(binaryPath, ["--version"], { timeout: 10_000 }); + if (stdout.trim() !== CELLD_VERSION) { + throw new Error(`celld version mismatch: expected ${CELLD_VERSION}, got ${stdout.trim()}`); + } + return binaryPath; +} + +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { + provisionCelld({ cacheDirectory: process.argv[2] }).then( + (binary) => console.log(binary), + (error) => { console.error(error.message); process.exitCode = 1; }, + ); +} diff --git a/scripts/fetch_official_celld.test.mjs b/scripts/fetch_official_celld.test.mjs new file mode 100644 index 000000000..498f3255c --- /dev/null +++ b/scripts/fetch_official_celld.test.mjs @@ -0,0 +1,65 @@ +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { + CELLD_ARCHIVE_SHA256, + CELLD_BINARY_SHA256, + CELLD_RELEASE_URL, + provisionCelld, + verifyDigest, +} from "./fetch_official_celld.mjs"; + +test("accepts matching bytes and rejects changed archive or binary bytes", () => { + const bytes = Buffer.from("offline verification fixture"); + const digest = createHash("sha256").update(bytes).digest("hex"); + assert.doesNotThrow(() => verifyDigest(bytes, digest, "fixture")); + for (const [label, expected] of [ + ["celld archive", CELLD_ARCHIVE_SHA256], + ["celld binary", CELLD_BINARY_SHA256], + ]) { + assert.throws( + () => verifyDigest(bytes, expected, label), + (error) => error.message.startsWith(`${label} SHA256 mismatch:`), + ); + } +}); + +test("rejects a bad download before decompression or binary use", async (t) => { + const directory = await mkdtemp(join(tmpdir(), "edgezero-celld-download-")); + t.after(() => rm(directory, { recursive: true, force: true })); + let downloads = 0; + await assert.rejects( + provisionCelld({ + cacheDirectory: directory, + fetchArchive: async (url) => { + downloads += 1; + assert.equal(url, CELLD_RELEASE_URL); + return Buffer.from("not gzip, must fail the digest check first"); + }, + }), + /celld archive SHA256 mismatch:/, + ); + assert.equal(downloads, 1); + await assert.rejects(readFile(join(directory, "celld")), { code: "ENOENT" }); + await assert.rejects(readFile(join(directory, "celld-x86_64-unknown-linux-gnu.gz")), { code: "ENOENT" }); +}); + +test("rechecks a cached archive and never trusts an existing executable", async (t) => { + const directory = await mkdtemp(join(tmpdir(), "edgezero-celld-cache-")); + t.after(() => rm(directory, { recursive: true, force: true })); + await writeFile(join(directory, "celld-x86_64-unknown-linux-gnu.gz"), "changed archive"); + const binary = join(directory, "celld"); + const marker = join(directory, "executed"); + await writeFile(binary, `#!/bin/sh\ntouch '${marker}'\necho 'celld 0.6.3'\n`, { mode: 0o755 }); + await assert.rejects( + provisionCelld({ + cacheDirectory: directory, + fetchArchive: () => assert.fail("cached archive must be verified without downloading"), + }), + /celld archive SHA256 mismatch:/, + ); + await assert.rejects(readFile(marker), { code: "ENOENT" }); +}); diff --git a/scripts/portable_dependency_checks.test.mjs b/scripts/portable_dependency_checks.test.mjs index 4bf29c925..7db9bbd50 100644 --- a/scripts/portable_dependency_checks.test.mjs +++ b/scripts/portable_dependency_checks.test.mjs @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; -import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; @@ -10,6 +10,35 @@ const helper = fileURLToPath( new URL("./portable_dependency_checks.sh", import.meta.url), ); +const signingAssertion = readFileSync( + new URL("./check_native_store_dependency_contract.sh", import.meta.url), + "utf8", +).match(/^assert_sigv4\(\) \{\n[\s\S]*?^\}/m)[0]; + +for (const [expected, graph, status, diagnostic] of [ + ["present", "aws-sigv4 v1.6.0\n", 0, ""], + ["absent", "serde v1.0.228\n", 0, ""], + ["present", "serde v1.0.228\n", 1, "signing dependency is missing"], + ["absent", "aws-sigv4 v1.6.0\n", 1, "signing dependency leaked"], +]) { + test(`signing policy ${expected} checks ${JSON.stringify(graph)}`, () => { + const result = spawnSync( + "bash", + [ + "-c", + `set -euo pipefail\ncargo() { printf '%s' "$FAKE_GRAPH"; }\n${signingAssertion}\nassert_sigv4 "$1" -p test-provider`, + "bash", + expected, + ], + { encoding: "utf8", env: { ...process.env, FAKE_GRAPH: graph } }, + ); + assert.equal(result.status, status, result.stderr); + assert.equal(result.stdout, ""); + assert.ok(result.stderr.includes(diagnostic), result.stderr); + if (status !== 0) assert.match(result.stderr, /-p test-provider/); + }); +} + function check(graph) { return spawnSync( "bash", diff --git a/scripts/run_portable_record_contract.mjs b/scripts/run_portable_record_contract.mjs new file mode 100755 index 000000000..868c19ab8 --- /dev/null +++ b/scripts/run_portable_record_contract.mjs @@ -0,0 +1,316 @@ +#!/usr/bin/env node +// Disposable real-service acceptance. CELLD_BIN must select official celld 0.6.3. +// VICEROY_BIN is required unless --skip-viceroy is used for staged host checks. +import { spawn } from "node:child_process"; +import { createHash, randomBytes } from "node:crypto"; +import { createWriteStream } from "node:fs"; +import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import net from "node:net"; +import { tmpdir } from "node:os"; +import { isAbsolute, join, resolve } from "node:path"; +import { setTimeout as delay } from "node:timers/promises"; +import { fileURLToPath, pathToFileURL } from "node:url"; +import { fixtureClient } from "./native_aws_test_admin.mjs"; +import { publishedEndpoint } from "./run_native_aws_integration.mjs"; + +const root = fileURLToPath(new URL("../", import.meta.url)); +// DynamoDB Local 3.3.1, same multi-architecture index digest as the native runner. +export const DYNAMODB_IMAGE = "amazon/dynamodb-local@sha256:ff89bd48ff32cd8d9be5fee8873b65b8854dc408f1afe881be6eb00247bc0dab"; +const accessKey = "AKIDPORTABLEFIXTURE"; +const secretKey = "portable-fixture-secret"; + +export function parseArgs(argv) { + const options = { skipViceroy: false }; + for (let index = 0; index < argv.length; index += 1) { + const name = argv[index]; + if (name === "--skip-viceroy") options.skipViceroy = true; + else if (name === "--output" && argv[index + 1] && !argv[index + 1].startsWith("--")) options.output = resolve(argv[++index]); + else throw new Error("usage: run_portable_record_contract.mjs [--skip-viceroy] [--output DIR]"); + } + return options; +} + +export function requireTestCount(output, count) { + const summaries = [...output.matchAll(/^test result: ok\. (\d+) passed; 0 failed; 0 ignored;/gm)]; + if (summaries.length !== 1 || Number(summaries[0][1]) !== count) { + throw new Error(`expected exactly ${count} passing tests in one nonignored summary`); + } +} + +const quoted = (value) => JSON.stringify(value); +export function renderBindings({ dynamodbEndpoint, celldEndpoint, table }) { + return `version = 1 + +[kv.dynamodb_records] +provider = "aws-dynamodb-records" +region = "us-east-1" +table = ${quoted(table)} +namespace = "portable-contract" +endpoint = ${quoted(dynamodbEndpoint)} +credentials = { secrets = "stores" } + +[kv.celld_records] +provider = "celld-records" +endpoint = ${quoted(celldEndpoint)} +store = "records" +access = { mode = "authenticated", token_secret = { secrets = "stores" } } +`; +} + +export function renderFastly(document, token) { + // A TOML basic string safely escapes arbitrary document contents, including quotes. + return `manifest_version = 3 +name = "portable-record-contract" +language = "rust" +[local_server] +[local_server.backends] +[local_server.config_stores.edgezero_store_bindings] +format = "inline-toml" +[local_server.config_stores.edgezero_store_bindings.contents] +EDGEZERO__STORE_BINDINGS = ${quoted(document)} +[[local_server.secret_stores.stores]] +key = "KV__DYNAMODB_RECORDS__AWS_ACCESS_KEY_ID" +data = ${quoted(accessKey)} +[[local_server.secret_stores.stores]] +key = "KV__DYNAMODB_RECORDS__AWS_SECRET_ACCESS_KEY" +data = ${quoted(secretKey)} +[[local_server.secret_stores.stores]] +key = "KV__CELLD_RECORDS__CELLD_TOKEN" +data = ${quoted(token)} +`; +} + +export function fixtureEnvironment(source, { work, bindings, ca, dynamodbEndpoint, token, config }) { + const env = {}; + for (const [name, value] of Object.entries(source)) { + if (["PATH", "HOME", "CARGO_HOME", "RUSTUP_HOME", "RUSTC", "RUSTDOC", "RUSTFLAGS", "CARGO_BUILD_JOBS", "CARGO_TARGET_DIR", "EDGEZERO_GENERATED_TEST_TARGET_DIR", "VICEROY_BIN"].includes(name)) env[name] = value; + } + return { + ...env, RUSTUP_TOOLCHAIN: "1.98.1", CARGO_NET_OFFLINE: "true", RUST_TEST_THREADS: "1", + TMPDIR: work, AWS_ACCESS_KEY_ID: accessKey, AWS_SECRET_ACCESS_KEY: secretKey, + AWS_REGION: "us-east-1", AWS_DEFAULT_REGION: "us-east-1", AWS_EC2_METADATA_DISABLED: "true", + AWS_CONFIG_FILE: join(work, "empty-aws-config"), AWS_SHARED_CREDENTIALS_FILE: join(work, "empty-aws-credentials"), + AWS_ENDPOINT_URL_DYNAMODB: dynamodbEndpoint, AWS_IGNORE_CONFIGURED_ENDPOINT_URLS: "false", + AWS_ACCOUNT_ID_ENDPOINT_MODE: "disabled", SSL_CERT_FILE: ca, + KV__CELLD_RECORDS__CELLD_TOKEN: token, EDGEZERO_PORTABLE_RECORDS_BINDINGS: bindings, + EDGEZERO_PORTABLE_RECORDS_CONFIG: config, EDGEZERO_PORTABLE_RECORDS_CA: ca, + }; +} + +export function renderWrangler(token) { + const policy = { version: 1, stores: [{ alias: "records", namespace: "portable-contract" }], access: { + mode: "authenticated", tokens: [{ id: "portable-contract", sha256: createHash("sha256").update(token).digest("hex"), + grants: [{ store: "records", operations: ["read", "write", "delete", "list"] }] }], + } }; + return JSON.stringify({ name: "edgezero-store", main: "src/index.js", no_bundle: true, + compatibility_date: "2026-10-01", durable_objects: { bindings: [{ name: "EDGEZERO_STORE", class_name: "EdgeZeroStore" }] }, + migrations: [{ tag: "v1", new_sqlite_classes: ["EdgeZeroStore"] }], vars: { EDGEZERO_STORE_POLICY: JSON.stringify(policy) }, + }, null, 2); +} + +export class Cleanup { + actions = []; + add(action) { this.actions.push(action); } + async run() { + const failures = []; + for (const action of this.actions.splice(0).reverse()) { + try { await action(); } catch (error) { failures.push(error); } + } + if (failures.length) throw new AggregateError(failures, "portable service cleanup failed"); + } +} + +export async function withCleanup(body) { + const cleanup = new Cleanup(); + try { return await body(cleanup); } finally { await cleanup.run(); } +} + +function signalGroup(pid, signal) { + if (!Number.isInteger(pid)) return; + try { process.kill(-pid, signal); } catch (error) { if (error.code !== "ESRCH") throw error; } +} + +// Every command owns a process group, including cargo, celld and its descendants. +export class Processes { + children = new Set(); + interrupted; + constructor(redactions = []) { this.redactions = redactions; } + check() { if (this.interrupted) throw new Error(`Interrupted by ${this.interrupted}`); } + interrupt(signal) { + this.interrupted = signal; + for (const child of this.children) signalGroup(child.pid, "SIGTERM"); + this.force ??= setTimeout(() => this.killAll(), 2000); + } + killAll() { for (const child of this.children) signalGroup(child.pid, "SIGKILL"); } + async stop() { + clearTimeout(this.force); + this.killAll(); + await Promise.allSettled([...this.children].map((child) => new Promise((done) => { + child.once("close", done); + }))); + } + start(command, args, { cwd = root, env = process.env, log, timeoutMs = 20 * 60_000 } = {}) { + this.check(); + const child = spawn(command, args, { cwd, env, detached: true, stdio: ["ignore", "pipe", "pipe"] }); + let output = ""; + const sink = log ? createWriteStream(log, { mode: 0o600 }) : undefined; + this.children.add(child); + const consume = (chunk) => { + let text = chunk.toString(); + for (const secret of this.redactions) text = text.replaceAll(secret, "[redacted]"); + output = (output + text).slice(-1024 * 1024); + sink?.write(text); + }; + child.stdout.on("data", consume); + child.stderr.on("data", consume); + const done = new Promise((resolveCommand, reject) => { + const timer = setTimeout(() => { signalGroup(child.pid, "SIGKILL"); }, timeoutMs); + child.once("error", (error) => { clearTimeout(timer); sink?.end(); this.children.delete(child); reject(error); }); + child.once("close", (code, signal) => { + clearTimeout(timer); + sink?.end(); + // Kill descendants even if their immediate parent exited successfully. + signalGroup(child.pid, "SIGKILL"); + this.children.delete(child); + if (code === 0 && !this.interrupted) resolveCommand(output); + else reject(new Error(`${command} failed: ${this.interrupted ?? signal ?? `exit ${code}`}${log ? `; see ${log}` : ""}`)); + }); + }); + // Long-lived services can exit while another command is running. + done.catch(() => {}); + return { child, done, output: () => output }; + } + async run(command, args, options) { return this.start(command, args, options).done; } +} + +async function waitForLine(processes, service, marker) { + const deadline = Date.now() + 120_000; + while (Date.now() < deadline) { + processes.check(); + const line = service.output().split(/\r?\n/).find((item) => item.includes(marker)); + if (line) return line.split(marker)[1].trim().split(/\s/)[0]; + if (service.child.exitCode !== null || service.child.signalCode !== null) throw new Error(`service exited before ${marker}`); + await delay(50); + } + throw new Error(`deadline waiting for ${marker}`); +} + +async function reservePort() { + const listener = net.createServer(); + await new Promise((yes, no) => { listener.once("error", no); listener.listen(0, "127.0.0.1", yes); }); + const port = listener.address().port; + await new Promise((yes) => listener.close(yes)); + return port; +} + +export async function main(argv = process.argv.slice(2), source = process.env) { + const options = parseArgs(argv); + if (!source.CELLD_BIN || !isAbsolute(source.CELLD_BIN)) throw new Error("CELLD_BIN must select an absolute official celld 0.6.3 binary"); + if (!options.skipViceroy && (!source.VICEROY_BIN || !isAbsolute(source.VICEROY_BIN))) throw new Error("VICEROY_BIN must select the pinned Viceroy binary"); + const output = options.output ?? await mkdtemp(join(tmpdir(), "edgezero-portable-evidence-")); + await mkdir(output, { recursive: true }); + console.log(`Portable record evidence: ${output}`); + const token = randomBytes(32).toString("hex"); + const processes = new Processes([token, secretKey]); + const onInt = () => processes.interrupt("SIGINT"); + const onTerm = () => processes.interrupt("SIGTERM"); + process.on("SIGINT", onInt); + process.on("SIGTERM", onTerm); + try { + await withCleanup(async (cleanup) => { + const work = await mkdtemp(join(tmpdir(), "edgezero-portable-")); + cleanup.add(() => rm(work, { recursive: true, force: true })); + const container = `edgezero-portable-${work.split("/").at(-1)}`; + // Register before acquisition, so partial docker starts are also removed. + const docker = (args, timeoutMs = 30_000) => processes.run("docker", args, { timeoutMs }); + let containerCreated = false; + cleanup.add(async () => { + if (containerCreated) { + // Cleanup must still run after an interrupt, independently of command readiness. + const cleaning = new Processes(); + await cleaning.run("docker", ["rm", "-f", container], { timeoutMs: 30_000 }); + } + }); + cleanup.add(() => processes.stop()); + const version = await processes.run(source.CELLD_BIN, ["--version"], { timeoutMs: 10_000 }); + if (version.trim() !== "celld 0.6.3") throw new Error("CELLD_BIN must report celld 0.6.3"); + const help = await processes.run(source.CELLD_BIN, ["--help"], { timeoutMs: 10_000 }); + if (help.includes("--store-api-config")) throw new Error("modified celld builds are not accepted"); + const celldSha256 = createHash("sha256").update(await readFile(source.CELLD_BIN)).digest("hex"); + await writeFile(join(output, "services.json"), JSON.stringify({ celld: version.trim(), celldSha256, dynamodbImage: DYNAMODB_IMAGE, qualification: false }, null, 2)); + await docker(["info"]); + await docker(["pull", DYNAMODB_IMAGE], 180_000); + containerCreated = true; + await docker(["run", "-d", "--name", container, "--publish", "127.0.0.1::8000", DYNAMODB_IMAGE, + "-jar", "DynamoDBLocal.jar", "-inMemory", "-sharedDb", "-disableTelemetry"]); + const dynamodbEndpoint = publishedEndpoint(await docker(["port", container, "8000/tcp"])); + const admin = fixtureClient(dynamodbEndpoint, "dynamodb"); + const deadline = Date.now() + 60_000; + for (;;) { + processes.check(); + try { await admin("ListTables"); break; } catch { + if (Date.now() >= deadline) throw new Error("DynamoDB Local readiness deadline"); + await delay(200); + } + } + const table = "portable-record-contract"; + await admin("CreateTable", { TableName: table, BillingMode: "PAY_PER_REQUEST", + AttributeDefinitions: ["pk", "sk"].map((name) => ({ AttributeName: name, AttributeType: "S" })), + KeySchema: [{ AttributeName: "pk", KeyType: "HASH" }, { AttributeName: "sk", KeyType: "RANGE" }], + }); + const service = join(work, "service"); + await mkdir(join(service, "src"), { recursive: true }); + await copyFile(join(root, "services/celld-store/src/index.js"), join(service, "src/index.js")); + await writeFile(join(service, "wrangler.json"), renderWrangler(token)); + const port = await reservePort(); + const celld = processes.start(source.CELLD_BIN, ["dev", ".", "--no-watch", "--logs", "--port", String(port)], { + cwd: service, env: { PATH: source.PATH, HOME: join(work, "celld-home"), NO_COLOR: "1" }, log: join(output, "celld.log"), + }); + const address = await waitForLine(processes, celld, "celld listening on "); + if (address !== `127.0.0.1:${port}`) throw new Error("unexpected celld listener"); + const ca = join(output, "terminator-cert.pem"); + const key = join(work, "terminator-key.pem"); + const cert = (certPath, keyPath) => processes.run("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "1", + "-subj", "/CN=portable-celld", "-addext", "subjectAltName=IP:127.0.0.1", "-addext", "basicConstraints=critical,CA:FALSE", + "-addext", "extendedKeyUsage=serverAuth", "-keyout", keyPath, "-out", certPath]); + await cert(ca, key); + const wrongCa = join(work, "unrelated-cert.pem"); + await cert(wrongCa, join(work, "unrelated-key.pem")); + const tls = processes.start(process.execPath, [join(root, "scripts/celld_store_tls_terminator.mjs"), "--cert", ca, "--key", key, "--target", address], { log: join(output, "tls.log") }); + const celldEndpoint = `https://${await waitForLine(processes, tls, "listening on ")}`; + const bindings = join(work, "bindings.toml"); + const config = join(work, "fastly.toml"); + await writeFile(bindings, renderBindings({ dynamodbEndpoint, celldEndpoint, table })); + const env = fixtureEnvironment(source, { work, bindings, ca, dynamodbEndpoint, token, config }); + await processes.run("cargo", ["run", "--offline", "--locked", "-p", "edgezero-cli", "--bin", "edgezero", "--", "config", "bindings", "pin", "--adapter", "fastly", "--store-bindings", bindings], { env, log: join(output, "pin.log") }); + const document = await readFile(bindings, "utf8"); + await writeFile(join(output, "bindings.toml"), document); + await writeFile(config, renderFastly(document, token), { mode: 0o600 }); + const tests = async (names, filter, filename, overrides = {}) => { + const result = await processes.run(join(root, "scripts/run_test_nonzero.sh"), [ + "--ignored", names.join("\n"), "cargo", "test", "--offline", "--locked", "-p", "edgezero-adapter-axum", "--test", "portable_interop", filter, + ], { env: { ...env, ...overrides }, log: join(output, filename) }); + requireTestCount(result, names.length); + }; + if (!options.skipViceroy) { + await tests(["portable_native_seed_rows"], "portable_native_seed_rows", "seed.log"); + await processes.run(join(root, "scripts/test_integration.sh"), ["--adapter", "fastly", "--suite", "portable-record-contract", "--output", join(output, "viceroy")], { env, log: join(output, "harness.log") }); + await readFile(join(output, "viceroy/summary.json")); + } + await tests(["portable_celld_real_service_interop", "portable_dynamodb_real_service_interop"], "real_service_interop", "interop.log"); + await tests(["portable_celld_rejects_untrusted_certificate"], "rejects_untrusted_certificate", "untrusted-cert.log", { SSL_CERT_FILE: wrongCa }); + processes.check(); + await writeFile(join(output, "result.json"), JSON.stringify({ hostInterop: "passed", untrustedCertificate: "rejected", viceroy: options.skipViceroy ? "not-run" : "passed", qualification: false }, null, 2)); + }); + processes.check(); + console.log(options.skipViceroy ? "Host interop passed; Viceroy explicitly not run" : "Portable record contracts and host interop passed"); + } finally { + await processes.stop(); + process.off("SIGINT", onInt); + process.off("SIGTERM", onTerm); + } +} + +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { + main().catch((error) => { console.error(error.message); process.exitCode = 1; }); +} diff --git a/scripts/run_portable_record_contract.test.mjs b/scripts/run_portable_record_contract.test.mjs new file mode 100644 index 000000000..af3bf8200 --- /dev/null +++ b/scripts/run_portable_record_contract.test.mjs @@ -0,0 +1,156 @@ +import assert from "node:assert/strict"; +import { execFile, spawn } from "node:child_process"; +import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import test from "node:test"; +import { setTimeout as delay } from "node:timers/promises"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; +import { + Cleanup, DYNAMODB_IMAGE, Processes, fixtureEnvironment, parseArgs, renderBindings, + renderFastly, renderWrangler, requireTestCount, withCleanup, +} from "./run_portable_record_contract.mjs"; + +const exec = promisify(execFile); +const runner = fileURLToPath(new URL("./run_portable_record_contract.mjs", import.meta.url)); + +test("full Viceroy execution is the default; staged host execution is explicit", () => { + assert.deepEqual(parseArgs([]), { skipViceroy: false }); + assert.deepEqual(parseArgs(["--output", "artifacts", "--skip-viceroy"]), { output: resolve("artifacts"), skipViceroy: true }); + for (const args of [["--output"], ["--output", "--skip-viceroy"], ["--skip"], ["extra"]]) assert.throws(() => parseArgs(args), /usage/); +}); + +test("service test summaries must contain the exact expected nonzero count", () => { + const summary = (count) => `test result: ok. ${count} passed; 0 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.02s\n`; + requireTestCount(summary(2), 2); + for (const output of ["", summary(0), summary(1), summary(3), summary(2) + summary(2), summary(2).replace("0 ignored", "1 ignored")]) { + assert.throws(() => requireTestCount(output, 2), /expected exactly 2/); + } +}); + +test("bindings contain portable sources, exact fixture IDs and no hand-written pins", () => { + const document = renderBindings({ dynamodbEndpoint: "http://127.0.0.1:8123", celldEndpoint: "https://127.0.0.1:9443", table: "portable-table" }); + assert.match(document, /\[kv.dynamodb_records\]/); + assert.match(document, /namespace = "portable-contract"/); + assert.match(document, /table = "portable-table"/); + assert.match(document, /credentials = \{ secrets = "stores" \}/); + assert.match(document, /\[kv.celld_records\]/); + assert.match(document, /token_secret = \{ secrets = "stores" \}/); + assert.doesNotMatch(document, /pinned|token_env|trusted-network|secret-key/); +}); + +test("Fastly fragment preserves the entire pinned document and derives secret names", () => { + const document = 'version = 1\n# quotes " and \'\'\'\n[kv.celld_records.pinned]\ninstance = "AAAA"\n'; + const fragment = renderFastly(document, "test-token-quote\"\\value"); + const encoded = fragment.split("\n").find((line) => line.startsWith("EDGEZERO__STORE_BINDINGS = ")).split(" = ").slice(1).join(" = "); + assert.equal(JSON.parse(encoded), document); + assert.match(fragment, /manifest_version = 3/); + assert.match(fragment, /\[local_server.config_stores.edgezero_store_bindings.contents\]/); + for (const name of ["KV__DYNAMODB_RECORDS__AWS_ACCESS_KEY_ID", "KV__DYNAMODB_RECORDS__AWS_SECRET_ACCESS_KEY", "KV__CELLD_RECORDS__CELLD_TOKEN"]) assert.ok(fragment.includes(name)); + assert.match(fragment, /test-token-quote\\"\\\\value/); +}); + +test("celld policy hashes the token and grants exactly the fixture store operations", () => { + const token = "fake-test-token-at-least-thirty-two-bytes"; + const wrangler = JSON.parse(renderWrangler(token)); + const policy = JSON.parse(wrangler.vars.EDGEZERO_STORE_POLICY); + assert.equal(wrangler.main, "src/index.js"); + assert.equal(wrangler.no_bundle, true); + assert.deepEqual(policy.stores, [{ alias: "records", namespace: "portable-contract" }]); + assert.equal(policy.access.mode, "authenticated"); + assert.deepEqual(policy.access.tokens[0].grants, [{ store: "records", operations: ["read", "write", "delete", "list"] }]); + assert.match(policy.access.tokens[0].sha256, /^[0-9a-f]{64}$/); + assert.ok(!JSON.stringify(wrangler).includes(token)); +}); + +test("environment isolates real credentials/proxies and supplies process-local CA trust", () => { + const env = fixtureEnvironment({ PATH: "/bin", HOME: "/home/test", CARGO_TARGET_DIR: "/target", VICEROY_BIN: "/viceroy", AWS_PROFILE: "prod", AWS_SESSION_TOKEN: "prod-token", HTTPS_PROXY: "untrusted", SSL_CERT_FILE: "/wrong", RUSTUP_TOOLCHAIN: "old" }, { + work: "/work", bindings: "/bindings", ca: "/cert", dynamodbEndpoint: "http://127.0.0.1:8123", token: "fake-token", config: "/fastly.toml", + }); + assert.equal(env.CARGO_TARGET_DIR, "/target"); + assert.equal(env.RUSTUP_TOOLCHAIN, "1.98.1"); + assert.equal(env.SSL_CERT_FILE, "/cert"); + assert.equal(env.EDGEZERO_PORTABLE_RECORDS_CA, "/cert"); + assert.equal(env.EDGEZERO_PORTABLE_RECORDS_CONFIG, "/fastly.toml"); + assert.equal(env.EDGEZERO_PORTABLE_RECORDS_BINDINGS, "/bindings"); + assert.equal(env.AWS_ENDPOINT_URL_DYNAMODB, "http://127.0.0.1:8123"); + assert.equal(env.AWS_ACCESS_KEY_ID, "AKIDPORTABLEFIXTURE"); + assert.equal(env.KV__CELLD_RECORDS__CELLD_TOKEN, "fake-token"); + for (const name of ["AWS_PROFILE", "AWS_SESSION_TOKEN", "HTTPS_PROXY"]) assert.equal(env[name], undefined); +}); + +test("cleanup runs in reverse order after failure and still attempts every action", async () => { + const calls = []; + await assert.rejects(withCleanup(async (cleanup) => { + cleanup.add(() => calls.push("directory")); + cleanup.add(() => calls.push("docker")); + cleanup.add(() => calls.push("processes")); + throw new Error("suite failed"); + }), /suite failed/); + assert.deepEqual(calls, ["processes", "docker", "directory"]); + const cleanup = new Cleanup(); + cleanup.add(() => calls.push("last cleanup")); + cleanup.add(() => { throw new Error("cleanup failure"); }); + await assert.rejects(cleanup.run(), /cleanup failed/); + assert.equal(calls.at(-1), "last cleanup"); + await cleanup.run(); +}); + +test("command failure and missing executables reject, never pass or leave owned children", async () => { + const processes = new Processes(); + try { + await assert.rejects(processes.run(process.execPath, ["-e", "process.exit(17)"]), /exit 17/); + await assert.rejects(processes.run("/nonexistent-edgezero-command", []), /ENOENT/); + assert.equal(processes.children.size, 0); + } finally { await processes.stop(); } +}); + +test("required binaries are not silent skips", async () => { + await assert.rejects(exec(process.execPath, [runner], { env: { PATH: "/nonexistent" } }), (error) => error.stderr.includes("CELLD_BIN")); + await assert.rejects(exec(process.execPath, [runner], { env: { PATH: "/nonexistent", CELLD_BIN: "/fake/celld" } }), (error) => error.stderr.includes("VICEROY_BIN")); +}); + +async function fixture(t, hang = false) { + const directory = await mkdtemp(join(tmpdir(), "edgezero-portable-unit-")); + t.after(() => rm(directory, { recursive: true, force: true })); + const temporary = join(directory, "temporary"); + await mkdir(temporary); + const log = join(directory, "docker.log"); + const binary = join(directory, "celld"); + await writeFile(binary, '#!/bin/sh\nif [ "$1" = "--version" ]; then echo "celld 0.6.3"; fi\n', { mode: 0o755 }); + await writeFile(join(directory, "docker"), `#!/bin/sh +printf '%s\\n' "$*" >> "$MOCK_DOCKER_LOG" +case "$1" in + pull) ${hang ? "exit 0" : "exit 17"} ;; + run) printf 'runtime-start\\n' >> "$MOCK_DOCKER_LOG"; sleep 60 ;; + *) exit 0 ;; +esac +`, { mode: 0o755 }); + return { directory, temporary, log, env: { ...process.env, PATH: `${directory}:/usr/bin:/bin`, TMPDIR: temporary, CELLD_BIN: binary, MOCK_DOCKER_LOG: log } }; +} + +test("failed pinned-image acquisition propagates and removes disposable state", async (t) => { + const setup = await fixture(t); + await assert.rejects(exec(process.execPath, [runner, "--skip-viceroy", "--output", join(setup.directory, "evidence")], { env: setup.env }), (error) => error.stderr.includes("exit 17")); + assert.ok((await readFile(setup.log, "utf8")).includes(`pull ${DYNAMODB_IMAGE}`)); + assert.deepEqual(await readdir(setup.temporary), []); +}); + +test("SIGINT kills an in-flight process group, removes a partially-started container and exits nonzero", async (t) => { + const setup = await fixture(t, true); + const child = spawn(process.execPath, [runner, "--skip-viceroy", "--output", join(setup.directory, "evidence")], { env: setup.env, stdio: "ignore" }); + const closed = new Promise((yes, no) => { child.once("error", no); child.once("close", yes); }); + const timer = setTimeout(() => child.kill("SIGKILL"), 10_000); + try { + const deadline = Date.now() + 5000; + while (!(await readFile(setup.log, "utf8").catch(() => "")).includes("runtime-start")) { + assert.ok(Date.now() < deadline, "must reach synthetic docker run"); + await delay(20); + } + child.kill("SIGINT"); + assert.notEqual(await closed, 0); + assert.match(await readFile(setup.log, "utf8"), /rm -f edgezero-portable-/); + assert.deepEqual(await readdir(setup.temporary), []); + } finally { clearTimeout(timer); child.kill("SIGKILL"); await closed; } +});