Skip to content

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

Description

@aram356

Context

The adapters currently expose different health and startup-failure behavior. Fastly handles GET /health before state construction; Axum registers it only in the healthy router and returns its startup error status through the fallback router. Spin serves GET /health from both healthy and startup-failure routers while other fallback paths return a generic 503. Cloudflare has no explicit /health route and its startup-failure router uses the error's status. The adapter guides and API reference describe these differences, but there is no single decision explaining whether health means process liveness, readiness to serve publisher traffic, or both.

The original PR #1049 finding summarized this as a cross-adapter contract gap. Current source at 666953a0d confirms differences, including a Spin health route added since that finding.

Desired outcome

Document the intended health and startup-failure contract for each adapter, with explicit supported differences where platform behavior requires them.

Scoped work

  • Decide whether GET /health is a liveness probe, readiness probe, or adapter-specific route, and define its status and body for healthy and failed startup states.
  • Define the public startup-failure status and disclosure policy for ordinary routes. Account for the current Cloudflare/Axum error response and Spin's generic 503.
  • Implement the chosen behavior or record justified adapter differences. Align route registration, tests, and the adapter status tables.

Done when

  • One documented matrix states the expected health and ordinary-route responses for healthy and failed startup on Fastly, Axum, Cloudflare, and Spin.
  • Adapter tests cover that matrix, including missing or invalid startup configuration.
  • No adapter advertises a health route or startup status that its router does not produce.
  • Error responses follow the documented disclosure policy.

Evidence

Original PR #1049 finding; current crates/trusted-server-adapter-fastly/src/main.rs, Axum, Cloudflare and Spin app.rs, plus adapter guides at 666953a0d.

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

Metadata

Metadata

Assignees

Labels

rustPull requests that update rust code

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions