Skip to content

Standardize health and startup-failure responses across adapters - #1617

Open
prk-Jr wants to merge 5 commits into
feat/s2s-eid-collection-providersfrom
fix/1142-health-startup-contract
Open

prk-Jr wants to merge 5 commits into
feat/s2s-eid-collection-providersfrom
fix/1142-health-startup-contract

Conversation

@prk-Jr

@prk-Jr prk-Jr commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Give every adapter separate GET/HEAD liveness (/health) and application-initialization readiness (/ready) probes, so monitoring can distinguish a running handler from a usable application.
  • Return fixed, uncacheable startup 503 responses while enabling application-wide warn/error logging to the Worker console and Spin stderr, including startup diagnostics; keep probes independent of application authentication, cookies, and configured response headers.
  • Migrate readiness consumers and document the contract, with production startup smokes for Fastly, Axum, Cloudflare, and Spin.

Compatibility: GET/HEAD /ready becomes reserved everywhere, and Cloudflare gains local GET/HEAD /health. Move traffic-admission checks to /ready; Axum /health now remains live after caught startup failures. Fastly/Axum/Cloudflare startup statuses become 503. Readiness does not poll runtime dependencies; ordinary errors after successful startup retain their existing mapping.

Changes

File Change
.github/workflows/health-startup-contract.yml Run production startup smokes for every adapter in CI.
AGENTS.md List the Wrangler pin and production health/startup CI gate.
.tool-versions Pin Wrangler used by the Worker smoke.
CHANGELOG.md Document probes and startup-response migration.
crates/trusted-server-adapter-axum/README.md Point health, readiness, and startup responses to the canonical contract.
crates/trusted-server-adapter-axum/src/app.rs Compose probes with trace; standardize startup failures and test the matrix.
crates/trusted-server-adapter-cloudflare/README.md Point health, readiness, and startup responses to the canonical contract.
crates/trusted-server-adapter-cloudflare/src/app.rs Add shared probes and generic startup fallback with regressions.
crates/trusted-server-adapter-cloudflare/src/lib.rs Enable application-wide warning/error logging in production, including startup diagnostics.
crates/trusted-server-adapter-fastly/src/app.rs Compose shared probe policy and generic startup fallback.
crates/trusted-server-adapter-fastly/src/main.rs Keep early liveness; gate readiness on initialization; protect terminal responses and reuse the publisher method table.
crates/trusted-server-adapter-fastly/src/sandbox.rs Verify probe initialization, retry, and retained success.
crates/trusted-server-adapter-spin/README.md Point health, readiness, and startup responses to the canonical contract.
crates/trusted-server-adapter-spin/src/app.rs Use shared probes and startup fallback with matrix coverage.
crates/trusted-server-adapter-spin/src/lib.rs Enable application-wide warning/error logging in production, including startup diagnostics.
crates/trusted-server-cli/src/commands/dev/sandbox_probe.rs Reject readiness as a workload without counters.
crates/trusted-server-core/src/health.rs Own exact probe matching, fixed responses, and composed hook.
crates/trusted-server-core/src/lib.rs Export the shared health module.
crates/trusted-server-integration-tests/browser/helpers/infra.ts Wait for application readiness.
crates/trusted-server-integration-tests/tests/common/trace_boundary.rs Preserve trace controls with the reserved health path.
crates/trusted-server-integration-tests/tests/environments/axum.rs Require readiness instead of any root response.
crates/trusted-server-integration-tests/tests/environments/cloudflare.rs Require readiness instead of discovery/root fallbacks.
crates/trusted-server-integration-tests/tests/environments/fastly.rs Use application readiness for successful startup.
crates/trusted-server-integration-tests/tests/environments/mod.rs Require exactly 200 for readiness.
crates/trusted-server-integration-tests/tests/html_eof_runtime.rs Use HEAD readiness in the application-usability wait.
crates/trusted-server-integration-tests/tests/parity.rs Test protected probes, exact responses, and no dependency polling.
docs/guide/api-reference.md Define the normative health/startup response matrix.
docs/guide/axum-dev.md Explain readiness, startup errors, and migration.
docs/guide/cloudflare.md Document local probes and the startup boundary.
docs/guide/fastly.md Document early liveness, readiness, and startup 503s.
docs/guide/integrations-overview.md Align the startup and adapter support summary.
docs/guide/spin.md Align probes, production diagnostics, and startup support.
docs/superpowers/plans/2026-11-16-1142-health-startup-contract.md Record implementation tasks and completed local verification.
docs/superpowers/specs/2026-11-16-1142-health-startup-contract-design.md Record the approved contract and two-round review log.
scripts/README.md Document probe checks, Python prerequisite, and artifact retention.
scripts/smoke-axum.sh Exercise genuine startup inputs and publisher controls.
scripts/smoke-cloudflare.sh Exercise Worker bindings, startup inputs, and publisher controls.
scripts/smoke-common.sh Assert wire responses, mutate envelopes, and preserve synthetic evidence.
scripts/smoke-fastly.sh Exercise config-store startup inputs with pinned Viceroy.
scripts/smoke-spin.sh Exercise component config/secrets and publisher controls.

Closes

Closes #1142

Spec

Spec: Health and startup-failure contract, including two review rounds.

Implementation and verification: Plan.

Test plan

  • cargo test-fastly && cargo test-axum
  • cargo test-fastly-reuse && cargo test-cloudflare && cargo test-spin
  • All eight target-matched Clippy aliases from AGENTS.md
  • cargo fmt --all -- --check
  • JS tests, build, and format
  • Docs and repository Markdown format; staged added-line domain lint
  • Production Fastly WASM build and manual fastly compute serve smoke with Fastly 16.0.0 / Viceroy 0.21.0
  • All four production startup smokes: eight cases each, using current artifacts without test-utils; exact GET and raw-wire HEAD, auth/header controls, diagnostic assertions, and publisher sentinel/rewrite controls
  • Native parity: 31 tests, including injected services and a positive wiring control
  • CLI tests (including the helper's browser-audit fixtures), native digest tests/lint, HTML EOF harness tests/lint, clock lint, Node pin guards, release checks, and documentation-proposal checks
  • Fastly deadline fixtures and Cloudflare/Spin deadline example build, Clippy, and runtime controls
  • Core documentation generation; existing warnings remain in unchanged modules

Local baseline checks passed with Rust 1.98.1 and Node 24.20.0. The review correction in 1a801939e additionally passed fresh Fastly tests in both modes, target-matched Clippy, real deadline fixtures, Rust/Markdown/docs formatting, README contract-link checks, and added-line domain lint. All 35 hosted checks passed on the prior head dba90aa; hosted results for the updated head are separate. Existing ignored tests are not counted as passing runtime smokes.

Checklist

  • Spec linked above, ending in two agent review rounds
  • Changes follow AGENTS.md conventions
  • No unwrap() in production code
  • Uses log macros for production diagnostics
  • New behavior has tests
  • No real secrets or credentials committed

@prk-Jr prk-Jr self-assigned this Nov 16, 2026
@prk-Jr
prk-Jr marked this pull request as ready for review November 17, 2026 05:23
Brings the provider stack, including the EdgeZero cutover (#1506), into the
cross-adapter health and startup-failure contract, and keeps the contract on
every adapter.

Core: the probe pre-dispatch hook takes EdgeZero's PreDispatchRequest, and its
tests drive the hook through a router with run_pre_dispatch_hook, because
PreDispatchRequest cannot be built outside EdgeZero.

Fastly: the cutover's handle_request, assemble_app and finalize_response stay.
Liveness is built from the shared probe response and sent natively. A new
initialize_dispatch runs the sandbox initialization, answers GET and HEAD
/ready from its result, and answers a failed assembly on the seven publisher
fallback methods with the fixed 503, logging the assembly error that
EdgeZero's assembly-error response would have logged. Other methods keep
EdgeZero's assembly-error response. finalize_response skips operational
responses as it skips trace responses. The retained router wraps the trace
hook in the probe hook. Fastly needs no failure router, so the PR's Fastly
startup_error_router and its matrix test go; the matrix moves to main.rs and
runs through initialize_dispatch and the native conversion.

Axum, Cloudflare and Spin: Hooks::routes logs the report and returns the PR's
failure router instead of failing assembly, so liveness stays 200 and /ready
and every supported route answer the fixed 503. The routers keep the cutover's
middleware and Axum's received-head preparer, with the probe hook around the
trace hook. The cutover's EdgeZero managed logger already gives Cloudflare and
Spin a production log sink, so the PR's adapter loggers are dropped.

Tests: the cutover's startup tests are moved to the contract. Fastly's
missing-blob test checks the fixed 503 for GET, the assembly error for TRACE,
then recovery. The Cloudflare and Spin routes() tests serve the failure router.
The Axum binary test now requires the binary to keep listening with live
health and a 503 /ready and page, in place of a non-zero exit. The two Axum
connection-entry tests move from /health, which now bypasses configured
response headers, to the identify preflight. The probe parity test takes the
cutover's forbidden-router tuple and also asserts that probes send no outbound
request.

Docs: the API reference, adapter guides, READMEs, AGENTS.md and CHANGELOG keep
both sides. Startup statements now describe the contract: no Axum exit, no
Spin /health 503, no Cloudflare JSON 500, with the Fastly logger-failure case
and the Fastly assembly error for unsupported methods kept. The smoke-axum.sh
negative cases stay on the PR's 503 contract with EdgeZero's port variable.
Takes #1489's new head e4ae9ca, which brings #1506's repin of EdgeZero to
rc/identity at 9d02d7b3. The one conflict is CHANGELOG.md, where this PR's
health and readiness bullet sits next to the cutover's pin bullet; both are
kept, with the pin bullet naming the new commit.
aram356 added a commit that referenced this pull request Nov 19, 2026
Brings the identity integration chain, now including the health and startup
contract (#1617) on the EdgeZero cutover (#1506), into the creative proxy
disclosure policy, and keeps the policy on every adapter's proxy path.

Core proxy: proxy_request keeps the cutover's EdgeZero outbound client and
redirect follower. The creative identity policy now runs at the cutover's two
check points. The first target passes check_proxy_target, then CreativeHops
rejects userinfo, rewrites the reserved ts-ec query to the authorized identity
or to none, and picks the hop's cache policy. Each followed redirect goes
through redirect_policy, which, on the creative route, takes EdgeZero's
prepared request, applies the same per-hop decision with the raw Location path
check, and follows the rewritten request. Identity endpoints bypass upstream
caches. The chain state is shared with the policy, because EdgeZero keeps the
policy for the whole chain, and the final response becomes private once an
identity endpoint was visited. A final 3xx with a Location on the creative
route is an error, and creative responses strip the first-party passthrough
headers. The creative route sends the fixed creative header profile through a
header-profile choice in proxy_outbound_request. append_ec_id is gone, and
ProxyRequestConfig carries query_identity and disclosure in place of
forward_ec_id. Target logging drops the query, as the PR does.

Adapters: every adapter prepares the proxy policy when it builds state,
alongside the cutover's identity-provider rejection, and passes the request's
EcContext into handle_first_party_proxy. The finalize middleware keeps the
cutover's handler-error rendering and Fastly's RequestGeo, and marks 4xx and
5xx creative proxy responses terminal-private. Fastly's test-only service
injection in build_per_request_services is not needed on the cutover, so it is
not carried.

Core settings, config and consent: both sides' fields, checks, warnings and
test imports are kept. Testlight keeps the base's response cap and uses
without_ec_id.

Tests: the PR's core proxy policy tests, its parity module and its Fastly
named-route test run on ScriptedHttpClient in place of the removed platform
HTTP stubs, and read each hop's URI and cache policy from the recorded
requests. The parity origin answers by path through a request observer. The
Fastly named-route test routes with the cutover's outbound client and a held
US geo and runs the real entry-point finalize_response. The Fastly network
fixture uses EdgeZero's Fastly client. The cutover's first-party proxy readback
test now expects the creative header profile. The CLI proxy test keeps the
cutover's in-process Axum fixture. The CLI proxy explain tests create the
`[proxy]` table, which the cutover dropped from the integration fixture, so the
appended endpoint tables still parse.

Docs: the first-party proxy redirect list combines EdgeZero's redirect rules
with the per-hop identity policy and the creative terminal-redirect rejection,
and the proxy settings table keeps both sides' rows.
aram356 added a commit that referenced this pull request Nov 19, 2026
Takes #1617's new head 50bb96a, which brings #1506's repin of EdgeZero to
rc/identity at 9d02d7b3. The merge is clean, and this PR's tree changes only
by that repin.
@aram356
aram356 changed the base branch from main to feat/s2s-eid-collection-providers November 19, 2026 05:59
@aram356

aram356 commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

For the identity integration chain (#1608), this PR now stacks on #1489, and its base is feat/s2s-eid-collection-providers. Two merges bring the chain in. 5c6fb5df9 merges #1489's earlier head a7262c7db, which carries the EdgeZero cutover (#1506). 50bb96ad9 then merges #1489's new head e4ae9ca5a, which adds #1506's repin of EdgeZero to rc/identity at 9d02d7b3. Its one conflict was the pair of CHANGELOG.md bullets, both kept, and it changes this PR's tree by exactly that repin.

This PR's health and startup contract wins over the cutover's startup behavior on every adapter, so once both land these cutover statements no longer hold:

  • Axum no longer exits non-zero when settings fail. It serves this PR's failure router, so /health stays 200 and /ready and every supported route answer the fixed 503.
  • Cloudflare and Spin serve the same failure router. Spin's /health no longer answers 503 during a startup failure, and Cloudflare no longer answers a JSON 500.
  • Fastly answers a failed assembly with the fixed 503 on the seven publisher fallback methods and keeps EdgeZero's assembly-error response for other methods. A new initialize_dispatch runs the sandbox initialization and answers GET and HEAD /ready from its result.

How the port fits the cutover:

  • Core. The probe pre-dispatch hook takes EdgeZero's PreDispatchRequest. Its tests drive the hook through a router with run_pre_dispatch_hook, because PreDispatchRequest cannot be built outside EdgeZero.
  • Fastly. The cutover's handle_request, assemble_app and finalize_response stay. Liveness is built from the shared probe response and sent natively, and finalize_response skips operational responses as it skips trace responses. Fastly needs no failure router, so this PR's Fastly startup_error_router and its matrix test go. The matrix moves to main.rs and runs through initialize_dispatch and the native conversion.
  • Axum, Cloudflare and Spin. Hooks::routes logs the report and returns this PR's failure router instead of failing assembly. The routers keep the cutover's middleware and Axum's received-head preparer, with the probe hook around the trace hook. The cutover's EdgeZero managed logger already gives Cloudflare and Spin a production log sink, so this PR's adapter loggers are dropped.
  • Tests. The cutover's startup tests now assert the contract. Fastly's missing-blob test checks the fixed 503 for GET, the assembly error for TRACE, then recovery. The Cloudflare and Spin routes() tests serve the failure router. axum_main_exits_non_zero_when_settings_fail became axum_main_serves_the_failure_router_when_settings_fail, which runs the real binary and requires a live /health, a 503 /ready and a 503 page. The two Axum connection-entry tests move from /health, which now bypasses configured response headers, to the identify preflight. The probe parity test takes the cutover's router tuple and asserts that probes send no outbound request. No test is dropped. The cutover had already deleted Spin's two old startup-router tests, and this PR's matrix covers them apart from their x-ts-version assertion on startup /health.
  • Docs. The API reference, adapter guides, READMEs, AGENTS.md and CHANGELOG.md keep both sides, with startup statements describing the contract. The Fastly logger-failure case and the Fastly assembly error for unsupported methods are kept. The negative cases in smoke-axum.sh stay on this PR's 503 contract and use EdgeZero's port variable.

Checked locally at 5c6fb5df9: cargo fmt, all eight clippy aliases and the core build-digest clippy, scripts/lint-wasm-clock.sh, test-fastly (4,074), test-fastly-reuse (248), test-axum (65), test-cloudflare (67), test-spin (90), parity (35), build-digest (10), host CLI tests (972), docs and Markdown format, and the URL-host lint against #1489, all passing.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Define a uniform cross-adapter health and startup-failure contract

2 participants