Skip to content

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

Open
prk-Jr wants to merge 3 commits into
mainfrom
fix/1142-health-startup-contract
Open

prk-Jr wants to merge 3 commits into
mainfrom
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

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

1 participant