Outbound HTTP design spec

[aram356]

Summary

Adds the EdgeZero outbound HTTP design spec at docs/superpowers/specs/2026-05-21-outbound-http-design.md. Targets the PR #269 (feature/extensible-cli) baseline — the spec assumes the multi-store manifest, the edgezero_cli::adapter::execute(..) dispatcher, the expanded AdapterAction set, Adapter::provision / config-validation hooks, Spin SDK 6 / wasip2, and the demo command. Earlier appendices that quote the pre-#269 surface are explicitly flagged as historical.

Driving pattern

The spec is written against fan-out HTTP workloads — N concurrent outbound requests under a shared wall-clock deadline, results harvested in input order. The driving pattern is treated as a portable substrate; the spec deliberately does not name a single consumer.

Scope

Six driver requirements:

• Portable outbound client — OutboundHttpClient trait with single send and concurrent send_all on every adapter (Axum, Cloudflare, Fastly, Spin). One handler source compiles unchanged across all four.
• Deadline / timeout primitives — dispatch_budget(req, now) with explicit now snapshot, DEFAULT_NO_DEADLINE_BUDGET = 30s, DEADLINE_FAR_FUTURE = 7 days, BATCH_DISPATCH_SLACK_MAX = 25ms. Fastly's bounded-cooperative semantics are documented with precise overshoot bounds.
• Bounded buffering — persistent vs transient memory accounting (max + sizeof(current_chunk) worst case, in-flight chunk size source-controlled), pre-append cap checks across inbound + outbound bounded drains. Batch model is Σᵢ request_bodyᵢ.len() + Σᵢ max_response_bytesᵢ.
• Capability declaration — nine capabilities (outbound-http, outbound-deadlines, outbound-flexible-phase-budget, send-all-slot-isolation, streamed-upload-deadlines, lazy-streamed-response-passthrough, config-store, kv-store, secret-store). Enforcement runs as five pre-dispatch gates (one inside execute(..), siblings on run_provision / run_config_push / run_config_validate / run_demo).
• Adapter contract tests — three tiers: Tier 1 (core + MockOutboundClient), Tier 2 (per-adapter translation), Tier 3 (runtime against a local mock origin). Adapter-specific mechanics (Fastly host timers, harvest behaviour, dynamic backend identity) are restricted to Tier 2/3 since Tier 1's mock has no analogue.
• Canonical URI accessors — backend_target() / host_authority() / sni_hostname() / cert_host() are the single source of truth for the host/port/SNI/cert split. Adapters MUST consume these, not re-derive from req.uri(). IP-literal HTTPS (RFC 6066 §3) is handled by sni_hostname() == None && cert_host() == Some(ip).

Out of scope (explicit non-goals)

• No consumer-specific target logic in EdgeZero.
• No new direct dependency on tokio, reqwest, fastly, worker, or spin-sdk in core or app/library crates.
• No back-compat shims; renames are mechanical and downstream consumers migrate.

Process

The spec was revised through 49 review rounds. The non-normative resolution journal lives in Appendices A through AX. Appendix AR is the round-44 rebase snapshot, superseded by Appendices AS / AT / AU / AV / AW / AX (rounds 44–49).

Test plan

This is a docs-only PR.

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo test --workspace --all-targets
• Docs CI (ESLint + Prettier on docs/)
• Spec renders correctly in VitePress (no broken cross-refs to §1–§8 or Appendix anchors)

[aram356]

Round 50 — Fastly SDK correctness pass (commit 647489a)

Reviewer flagged four normative claims about Fastly that didn't match the actual SDK / public API. All fixes verified against docs.rs/fastly and Fastly's public Backend API docs before edit.

HIGH — lazy-streamed-response-passthrough on Fastly: downgraded Native → BestEffort. Response::with_streaming_body does not exist (only on Request). Response::stream_to_client() is the real API but is incompatible with #[fastly::main]. Default scaffold falls back to buffered passthrough; the non-#[fastly::main] entry-point template is tracked in new §8 risk 12.

HIGH — NameInUse semantics: rewritten. Fastly's session-uniqueness rule is unconditional — no "identical re-registration returns Ok" carve-out. Backend::from_str(name) returns a handle only, no property inspection. NameInUse on a name not in this adapter's collision map is now an explicit fail-closed EdgeError::internal.

MEDIUM — between_bytes_timeout direction: dropped the false write-side claim per Fastly's public Backend API docs (receive-side only). Streamed-upload host-write phase downgraded to BestEffort; cooperative inter-chunk check is the only adapter-side bound.

MEDIUM — Streamed-upload response overshoot: tightened from per-chunk accumulator to closed-form bound — first_byte_ms (headers wait) + one between_bytes_timeout (worst-case first-body-chunk read), one-shot. Footnote 1 single-send section and new §5.4 test row added.

LOW — App-facing consuming body accessor: added OutboundResponse::into_body(self) -> Body. send_all rustdoc now recommends single send + futures::join_all + into_body() as the canonical streamed-response orchestration path on Axum/CF/Spin.

Appendix AY records all five resolutions. Status bumped to rounds 1–50.

[aram356]

Round 51 — round-50 carry-overs + Spin WASI write mechanics (commit 8df9d80)

Five follow-up findings from the round-50 reviewer pass. All verified against the cited external docs before edit.

HIGH — Fastly dynamic-backend semantics contradictory across sections. Round 50 fixed the §4.3 step-5 algorithm but the earlier Dynamic backends introductory paragraph still preserved the false "identical name + identical properties re-registers / returns Ok" carve-out. Rewritten in place: session-uniqueness is unconditional per the SDK; EdgeZero owns the entire uniqueness story at the guest layer via the adapter-local cache; NameInUse outside that cache is fail-closed EdgeError::internal. Two historical Appendix-AK entries marked "Superseded by Appendix AY."

MEDIUM — Fastly buffered-fallback named an unavailable cap; §5.4 still bundled Fastly with CF/Spin. Added FASTLY_RESPONSE_STREAM_BUFFER_BYTES (default 16 MiB, mirrors AXUM_RESPONSE_STREAM_BUFFER_BYTES). §5.4 lazy-passthrough rows split: (a) CF/Spin yield-first-bytes row excludes Fastly; (b) CF/Spin mid-stream abort row excludes Fastly; (c) new Axum-and-Fastly buffered-fallback row with both adapter constants named.

MEDIUM — Residual between_bytes_timeout write-side claims. The "stalled streamed-upload mechanics differ per adapter" §5.4 row and §8 risk 7 both still claimed the Fastly between-bytes-timeout bounded guest-to-origin writes. Scrubbed both — Fastly's write phase is BestEffort uniformly. §8 risk 7 retitled and rewritten to track the symmetric "if Fastly adds a documented guest-write timeout in the future" follow-up.

MEDIUM — Spin host-write race mechanically wrong vs WASI. Old wording raced each OutgoingBody::write against a timer; WASI output-stream is nonblocking + readiness-polled. Rewritten as the four-step pattern: subscribe() pollable → futures::select! pollable-ready vs monotonic-clock timer → on timer-win drop the handle + return gateway_timeout → on pollable-win call nonblocking check_write() for permitted byte count + write() within that bound, looping. §5.4 row updated to match.

LOW — Typo: docsare migrated → docs are migrated in §1.3.

Appendix AZ records all five resolutions; status bumped to rounds 1–51.