Build-time state validation

How host.build() checks state provisioning, detects cycles and dead middleware, and fails on missing providers.

AI generated, pending review Updated 10 days ago · Flare 0.3

After validators pass, HTTP compile walks each route’s middleware chain and checks state provisioning. These failures throw at host.build() time, not on the first request.

Route and controller consumers

For each route, compile verifies that every token in the route’s effective state list is provided by a middleware before() hook in that route’s chain. On Cloudflare, a Durable Object’s static state tokens also count as provided at arc entry (see state crossing).

Example failure when middleware is missing:

Error: … requires state token AuthUser that is not provided by any preceding middleware.

Tokens listed in provides on after- or finally-only middleware do not satisfy route state declarations.

Duplicate providers

Two middleware in the same chain that both list the same token in provides fail the build as a duplicate provider.

Dead middleware

Global middleware that every controller excludes is reported as a DEAD_MIDDLEWARE warning at build. Warnings are logged and do not fail the build. See Failure modes for DEAD_MIDDLEWARE.

State derivation cycles

Build detects cycles in the middleware provides/state graph and fails with MIDDLEWARE_STATE_CYCLE (severity error, Circular state dependency in middleware chain: ...). It does not detect cycles in .from() derivation graphs: when .from() handlers mutually require each other, the read that closes the cycle throws at runtime. See Reading state.

Middleware consumers vs route consumers

A middleware’s state list is checked against the provides of every middleware registered earlier in the chain, regardless of hook kind. A middleware that implements before() is additionally checked against the provides of earlier before() hooks only. Route handlers always need before() providers.

What compile does not check

Tokens you read with get but never declare in state (no provider check for undeclared reads).
Error handlers (no state option on error handler registration).
Runtime-only set without provides (compile fails when a route declares the token).