feat: implement portable outbound HTTP and request lifecycle contracts

.claude/agents/code-architect.md

@@ -16,7 +16,7 @@ architectural principles:
 
 3. **Thin adapters**: each adapter translates platform types to/from core types.
    Business logic never lives in adapters. The adapter file structure is:
-   `context.rs`, `request.rs`, `response.rs`, `proxy.rs`, `logger.rs`, `cli.rs`.
+   `context.rs`, `request.rs`, `response.rs`, `outbound.rs`, `logger.rs`, `cli.rs`.
 
 4. **Contract testing**: every adapter has `tests/contract.rs` that validates
    request/response mapping. New adapters must follow this pattern.

.github/workflows/format.yml

@@ -34,7 +34,7 @@ jobs:
 
       - name: Retrieve Rust version
         id: rust-version
-        run: echo "rust-version=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
+        run: echo "rust-version=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT"
         shell: bash
 
       - name: Set up rust toolchain
@@ -75,28 +75,41 @@ jobs:
         working-directory: examples/app-demo
         run: cargo clippy --workspace --all-targets --all-features -- -D warnings
 
-  adapter-wasm-clippy:
-    name: ${{ matrix.adapter }} wasm clippy
+  adapter-clippy:
+    name: ${{ matrix.check_name }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
         include:
           - adapter: cloudflare
             target: wasm32-unknown-unknown
-            features: cloudflare
+            check_name: cloudflare wasm clippy
+            feature_sets: |-
+              cloudflare
+              cloudflare,test-utils
           - adapter: fastly
             target: wasm32-wasip1
-            features: fastly
-          # The `cli` feature is a valid wasip1 build combination (the CLI host
-          # code compiled for the guest target); gate it so a dead-code or
-          # portability regression there is caught, not only in the fastly-only build.
-          - adapter: fastly
-            target: wasm32-wasip1
-            features: fastly cli
+            check_name: fastly wasm clippy
+            # The `cli` feature is valid on wasip1. Lint it independently so
+            # feature unification cannot mask target-specific cfg mistakes.
+            feature_sets: |-
+              fastly
+              fastly,cli
+              fastly,test-utils
+              fastly,cli,test-utils
           - adapter: spin
             target: wasm32-wasip2
-            features: spin
+            check_name: spin wasm clippy
+            feature_sets: |-
+              spin
+              spin,test-utils
+          - adapter: axum
+            target: native
+            check_name: axum native clippy
+            feature_sets: |-
+              axum
+              axum,test-utils
     steps:
       - uses: actions/checkout@v6
 
@@ -114,7 +127,7 @@ jobs:
 
       - name: Retrieve Rust version
         id: rust-version
-        run: echo "rust-version=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
+        run: echo "rust-version=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT"
         shell: bash
 
       - name: Set up Rust tool chain
@@ -124,13 +137,34 @@ jobs:
           components: clippy
 
       - name: Add wasm target
+        if: matrix.target != 'native'
         run: rustup target add ${{ matrix.target }}
 
       - name: Fetch dependencies (locked)
         run: cargo fetch --locked
 
-      - name: Clippy ${{ matrix.adapter }} (${{ matrix.features }}) on ${{ matrix.target }}
-        run: cargo clippy -p edgezero-adapter-${{ matrix.adapter }} --features "${{ matrix.features }}" --target ${{ matrix.target }} --all-targets -- -D warnings
+      - name: Clippy ${{ matrix.adapter }} feature combinations on ${{ matrix.target }}
+        env:
+          ADAPTER: ${{ matrix.adapter }}
+          FEATURE_SETS: ${{ matrix.feature_sets }}
+          TARGET: ${{ matrix.target }}
+        run: |
+          target_args=()
+          if [[ "${TARGET}" != "native" ]]; then
+            target_args=(--target "${TARGET}")
+          fi
+
+          while IFS= read -r features; do
+            echo "==> edgezero-adapter-${ADAPTER} ${TARGET} features=[${features}]"
+            cargo clippy \
+              --package "edgezero-adapter-${ADAPTER}" \
+              --no-default-features \
+              --features "${features}" \
+              "${target_args[@]}" \
+              --all-targets \
+              -- \
+              -D warnings
+          done <<<"${FEATURE_SETS}"
 
   format-docs:
     runs-on: ubuntu-latest
@@ -144,7 +178,7 @@ jobs:
       - name: Retrieve Node.js version
         id: node-version
         working-directory: .
-        run: echo "node-version=$(grep '^nodejs ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
+        run: echo "node-version=$(grep '^nodejs ' .tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT"
         shell: bash
 
       - name: Use Node.js
@@ -162,3 +196,10 @@ jobs:
 
       - name: Run Prettier (check)
         run: npm run format
+
+      - name: Check outbound documentation contract
+        working-directory: .
+        run: node scripts/check_outbound_docs_contract.mjs
+
+      - name: Build documentation
+        run: npm run build

.github/workflows/test.yml

@@ -35,26 +35,45 @@ jobs:
 
       - name: Retrieve Rust version
         id: rust-version
-        run: echo "rust-version=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
+        run: echo "rust-version=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT"
         shell: bash
 
       - name: Set up Rust tool chain
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
+          components: "clippy, rustfmt"
           toolchain: ${{ steps.rust-version.outputs.rust-version }}
 
       - name: Add wasm targets
         run: rustup target add wasm32-wasip1 wasm32-wasip2 wasm32-unknown-unknown
 
       - name: Fetch dependencies (locked)
-        run: cargo fetch --locked
+        run: |
+          cargo fetch --locked
+          cargo fetch --locked --manifest-path examples/app-demo/Cargo.toml
 
       - name: No placeholder pins
         run: ./scripts/check_no_placeholder_pins.sh
 
       - name: No legacy typed reads
         run: ./scripts/check_no_legacy_typed_reads.sh
 
+      # These roots are the active API surface. Historical design and plan
+      # documents under docs/superpowers intentionally remain immutable.
+      - name: No legacy outbound API
+        run: bash scripts/check_outbound_legacy_api.sh
+
+      - name: Outbound documentation contract
+        run: node scripts/check_outbound_docs_contract.mjs
+
+      - name: Build strict public API documentation
+        env:
+          RUSTDOCFLAGS: -D warnings
+        run: cargo doc --offline --locked --workspace --all-features --no-deps
+
+      - name: Brotli dependency contract
+        run: node scripts/check_brotli_dependency_contract.mjs
+
       - name: Nested AppConfig audit
         run: cargo run -q --bin check_no_nested_app_config --features nested-app-config-check -- examples/app-demo crates/edgezero-cli/src/templates
 
@@ -68,18 +87,38 @@ jobs:
       - name: Run workspace tests
         run: cargo test --workspace --all-targets
 
+      - name: Run native outbound adapter contracts
+        run: |
+          scripts/run_test_nonzero.sh batch_preflight_precedence_and_indices cargo test --offline --locked -p edgezero-adapter-axum --no-default-features --features axum,test-utils --test contract
+          scripts/run_test_nonzero.sh batch_preflight_precedence_and_indices cargo test --offline --locked -p edgezero-adapter-cloudflare --no-default-features --features test-utils --test contract
+          scripts/run_test_nonzero.sh batch_preflight_rejects_streamed_slots_without_poisoning_siblings cargo test --offline --locked -p edgezero-adapter-fastly --no-default-features --features test-utils --test contract
+          scripts/run_test_nonzero.sh batch_preflight_precedence_and_indices cargo test --offline --locked -p edgezero-adapter-spin --no-default-features --features test-utils --test contract
+
       # The adapter CLI dispatch (build/deploy/stage/healthcheck/rollback) and
       # its tests live behind the `cli` feature, which the unfeatured
       # `cargo test --workspace` step above does not enable — so none of those
       # tests compile or run there. Exercise them explicitly.
       - name: Adapter CLI dispatch tests
         run: cargo test -p edgezero-adapter-fastly --all-targets --features cli
 
+      - name: Verify exact outbound capability matrices
+        run: |
+          scripts/run_test_nonzero.sh adapter_capability_matrix_matches_contracts cargo test --offline --locked -p edgezero-adapter-axum --no-default-features --features cli --lib adapter_capability_matrix_matches_contracts
+          scripts/run_test_nonzero.sh adapter_capability_matrix_matches_contracts cargo test --offline --locked -p edgezero-adapter-cloudflare --no-default-features --features cli --lib adapter_capability_matrix_matches_contracts
+          scripts/run_test_nonzero.sh adapter_capability_matrix_matches_contracts cargo test --offline --locked -p edgezero-adapter-fastly --no-default-features --features cli --lib adapter_capability_matrix_matches_contracts
+          scripts/run_test_nonzero.sh adapter_capability_matrix_matches_contracts cargo test --offline --locked -p edgezero-adapter-spin --no-default-features --features cli --lib adapter_capability_matrix_matches_contracts
+
       - name: Check feature compilation
         run: cargo check --workspace --all-targets --features "fastly cloudflare spin"
 
+      - name: Check native adapter feature matrices
+        run: |
+          for adapter in axum cloudflare fastly spin; do
+            bash scripts/check_adapter_feature_matrix.sh "${adapter}" native
+          done
+
       - name: Verify a generated project compiles
-        run: cargo test -p edgezero-cli --test generated_project_builds -- --ignored
+        run: scripts/run_test_nonzero.sh --ignored generated_workspace_compiles cargo test --offline --locked -p edgezero-cli --test generated_project_builds
 
       # `examples/app-demo` is excluded from the root workspace, so
       # `cargo test --workspace` above does not cover it. Run its own
@@ -101,6 +140,13 @@ jobs:
         working-directory: examples/app-demo
         run: cargo test --locked --workspace --all-targets
 
+      - name: Check app-demo wasm targets
+        working-directory: examples/app-demo
+        run: |
+          cargo check --locked -p app-demo-adapter-cloudflare --target wasm32-unknown-unknown --no-default-features --features cloudflare
+          cargo check --locked -p app-demo-adapter-fastly --target wasm32-wasip1 --no-default-features --features fastly
+          cargo check --locked -p app-demo-adapter-spin --target wasm32-wasip2 --no-default-features --features spin
+
   adapter-wasm-tests:
     name: ${{ matrix.adapter }} wasm tests
     runs-on: ubuntu-latest
@@ -112,14 +158,17 @@ jobs:
             target: wasm32-unknown-unknown
             runner_env: CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER
             runner_value: wasm-bindgen-test-runner
+            sentinel: dispatch_runs_router_and_returns_response
           - adapter: fastly
             target: wasm32-wasip1
             runner_env: CARGO_TARGET_WASM32_WASIP1_RUNNER
             runner_value: viceroy run
+            sentinel: dispatch_runs_router_and_returns_response
           - adapter: spin
             target: wasm32-wasip2
             runner_env: CARGO_TARGET_WASM32_WASIP2_RUNNER
-            runner_value: wasmtime run
+            runner_value: wasmtime run -W component-model-async=y -S p3=y -S http=y
+            sentinel: router_dispatches_get_and_returns_response
     steps:
       - uses: actions/checkout@v6
 
@@ -139,7 +188,7 @@ jobs:
 
       - name: Retrieve Rust version
         id: rust-version
-        run: echo "rust-version=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
+        run: echo "rust-version=$(grep '^rust ' .tool-versions | awk '{print $2}')" >> "$GITHUB_OUTPUT"
         shell: bash
 
       - name: Set up Rust tool chain
@@ -213,8 +262,8 @@ jobs:
           echo "$install_dir" >> "$GITHUB_PATH"
           export PATH="$install_dir:$PATH"
           version="${{ steps.wasmtime-version.outputs.version }}"
-          # Compare exact versions so a pin like `44.0.1` does not silently
-          # accept `wasmtime 44.0.10` from a stale cache or runner-provided
+          # Compare exact versions so a pin like `48.0.2` does not silently
+          # accept `wasmtime 48.0.20` from a stale cache or runner-provided
           # binary.
           actual="$(wasmtime --version 2>/dev/null | awk '{print $2}' || true)"
           if [ "$actual" != "$version" ]; then
@@ -235,7 +284,25 @@ jobs:
       - name: Run ${{ matrix.adapter }} wasm tests
         env:
           ${{ matrix.runner_env }}: ${{ matrix.runner_value }}
-        run: cargo test -p edgezero-adapter-${{ matrix.adapter }} --features ${{ matrix.adapter }} --target ${{ matrix.target }} --test contract
+        run: scripts/run_test_nonzero.sh ${{ matrix.sentinel }} cargo test --offline --locked -p edgezero-adapter-${{ matrix.adapter }} --no-default-features --features ${{ matrix.adapter }},test-utils --target ${{ matrix.target }} --test contract
+
+      - name: Run Fastly closed lifecycle wasm sentinel
+        if: matrix.adapter == 'fastly'
+        env:
+          ${{ matrix.runner_env }}: ${{ matrix.runner_value }}
+        run: scripts/run_test_nonzero.sh closed_lifecycle_orders_hooks_and_returns_state_after_delivery cargo test --offline --locked -p edgezero-adapter-fastly --no-default-features --features fastly,test-utils --target wasm32-wasip1 --test contract
+
+      - name: Run Spin WASI HTTP SDK resource tests
+        if: matrix.adapter == 'spin'
+        env:
+          ${{ matrix.runner_env }}: ${{ matrix.runner_value }}
+        run: scripts/run_test_nonzero.sh spin_error_code_table_is_exhaustive cargo test --offline --locked -p edgezero-adapter-spin --no-default-features --features spin,test-utils --target wasm32-wasip2 --test sdk_resources
+
+      - name: Run Cloudflare outbound runtime unit tests
+        if: matrix.adapter == 'cloudflare'
+        env:
+          ${{ matrix.runner_env }}: ${{ matrix.runner_value }}
+        run: scripts/run_test_nonzero.sh streamed_upload_eof_yields_before_final_precedence cargo test --offline --locked -p edgezero-adapter-cloudflare --no-default-features --features cloudflare,test-utils --target wasm32-unknown-unknown --lib
 
       # The colocated runtime unit tests (config-store resolver, chunk
       # remediation) need the `fastly` feature and only RUN under Viceroy — the
@@ -245,7 +312,8 @@ jobs:
         if: matrix.adapter == 'fastly'
         env:
           ${{ matrix.runner_env }}: ${{ matrix.runner_value }}
-        run: cargo test -p edgezero-adapter-fastly --features fastly --target wasm32-wasip1 --lib
+        working-directory: crates/edgezero-adapter-fastly
+        run: ../../scripts/run_test_nonzero.sh backend_creation_error_table_is_exhaustive cargo test --offline --locked --no-default-features --features fastly,test-utils --lib
 
-      - name: Check ${{ matrix.adapter }} wasm target
-        run: cargo check -p edgezero-adapter-${{ matrix.adapter }} --features ${{ matrix.adapter }} --target ${{ matrix.target }}
+      - name: Check ${{ matrix.adapter }} wasm feature matrix
+        run: bash scripts/check_adapter_feature_matrix.sh ${{ matrix.adapter }} ${{ matrix.target }}

.tool-versions

@@ -1,12 +1,6 @@
 fastly 15.1.0
 nodejs 24.12.0
 rust 1.95.0
-# spin-cli is not pinned by asdf-style version managers (no
-# asdf-spin plugin in widespread use). spin-sdk ~6.0 in the
-# workspace imports wasi:http/types@0.3.0-rc-2026-03-15, which
-# the Spin 3.6.x runtime does not provide; Spin 3.7+ is required
-# for the demo's Spin adapter to boot. Install matching CLI
-# manually (https://spinframework.dev/install) before running
-# smoke_test_config_key_override.sh; otherwise set SKIP_SPIN=1.
-viceroy 0.17.0
-wasmtime 44.0.1
+spin 4.1.0
+viceroy 0.21.0
+wasmtime 48.0.2

CLAUDE.md

@@ -12,7 +12,7 @@ CI workflows under `.github/workflows/`.
 
 ```
 crates/
-  edgezero-core/              # Core: routing, extractors, middleware, proxy, body, errors
+  edgezero-core/              # Core: routing, extractors, middleware, outbound HTTP, body, errors
   edgezero-macros/            # Proc macros: #[action], #[app]
   edgezero-adapter/           # Adapter registry and traits
   edgezero-adapter-fastly/    # Fastly Compute bridge (wasm32-wasip1)
@@ -134,11 +134,13 @@ impl Middleware for MyMiddleware {
 }
 ```
 
-### Proxy
+### Outbound HTTP
 
-Use `ProxyService` with adapter-specific clients (`FastlyProxyClient`,
-`CloudflareProxyClient`, `SpinProxyClient`). Keep proxy logic provider-agnostic
-in core.
+Handlers obtain `HttpClient` from `RequestContext::http_client()`, construct
+`OutboundRequest` values, and consume `OutboundResponse` or per-slot
+`OutboundSlotResult` outcomes. Keep provider transport logic in adapter-specific
+`*OutboundClient` implementations and use the capability matrix for behavioral
+differences.
 
 ### Logging
 
@@ -168,7 +170,7 @@ Each adapter follows the same structure:
 - `context.rs` — platform-specific request context
 - `request.rs` — platform request → core request conversion
 - `response.rs` — core response → platform response conversion
-- `proxy.rs` — platform-specific proxy client
+- `outbound.rs` — platform-specific outbound HTTP client
 - `logger.rs` — platform-specific logging init
 - `cli.rs` — adapter dispatch behind the `cli` feature: `build` / `deploy` / `serve` (legacy) plus `Adapter::execute` for `auth` (login/logout/status) and dedicated trait methods `provision` (Stage 6 — platform-resource creation) and `push_config_entries` (Stage 7 — `config push` writeback). Self-registers via `#[ctor]` into the `edgezero-adapter` registry.