Skip to content

Guards beyond HTTP

One guard on GraphQL fields, WebSocket messages and MCP operations — its two entries, where each runs, and the GuardFor line that binds it.

A guard is written once and bound wherever a caller reaches a unit: an HTTP route, a GraphQL field, a WebSocket message, an MCP tool call or prompt fetch. It writes its decision once, in check, which runs on every unit and, through check_http, on an HTTP request too; it overrides check_http only where the request differs from the unit. check has no default: a guard admitting a unit says so. It declares, with a GuardFor line, that it checks those units: one per edge, or once for all of them when its decision reads no view. A job, a tick and a listener call have no caller, so no guard runs there: guard where the work is produced.

crates/features/src/posts/guard.rs (from the demo, abridged)
#[async_trait]
impl Guard for PostAuthorGuard {
async fn check(&self, cx: &mut UnitContext<'_>) -> Result<(), Denial> {
let claims = cx.require::<Claims>()?;
match claims.sub.user_id() {
Some(_) => Ok(()),
None => Err(
Denial::forbidden("writing a post takes a token naming a user")
.with_reason("not_a_user"),
),
}
}
fn phase(&self) -> GuardPhase {
GuardPhase::Authorization
}
fn expected_principal(&self) -> Option<PrincipalClaim> {
Some(PrincipalClaim::of::<Claims>())
}
// …
}
impl<V: UnitView> GuardFor<V> for PostAuthorGuard {}

The one body serves the route and the GraphQL field alike, though only /graphql lets a visitor through: the principal it declares is one require answers by cause, a 401 for a caller admitted without one, and a boot refusal where nothing attaches it.

A guard writes check, overrides check_http where the request differs, and the framework runs each at its own seam:

EntryRunsBound by
check_http (check unless overridden)post-routing on the request, before the handler; on a WS upgrade; on the /graphql and /mcp requests#[controller] / #[routes], and the #[gateway] struct
checkper GraphQL field, and in front of the federation root fields#[resolver] / #[operations]
checkonce per inbound envelope, after the upgradebeside a #[subscribe_message]
checkonce per #[tool], #[prompt], #[resource] or #[resources] operation, inside rmcp’s dispatch#[mcp] host / #[tools] operation

The app’s GlobalGuards<(...)> reaches every edge at every entry it implements. /graphql and /mcp run the pool at their request and in each operation: check_http once on the request, check once per operation it carries — so a global ThrottlerGuard rate-limits the /mcp request and each tool call. A global guard writing only check runs it on every request too, the route, the WS upgrade and the /graphql and /mcp requests included; one whose decision is the unit’s alone admits the request in check_http, and one whose decision is the request’s alone admits the units that request carries in check. AuthnGuard reads there what the request found: a gated unit no principal reached is refused 401, since /graphql admits an anonymous request.

The three multiplexed edges need one thing on top: the guards that build the caller’s Ability at the request, because a unit below the request does not see the request. A gateway binds them on its struct, for its upgrade; on /graphql and /mcp, which no controller owns, a module declares them — EndpointGuards<GraphqlView, (AuthnGuard, AuthzGuard)> — and the transport runs them beside the global pool, each guard once. What they attach is ambient for every operation the request carries; below it you bind ordinary guards as usual, and a handler reads what they attached as an Ambient<T> parameter on every edge. That wiring — AuthzGraphqlModule, AuthzMcpModule, AuthzModule on a gateway’s upgrade, and what each one gates — lives on Endpoint guards, with the connection-vs-message split on WebSocket guards.

check has no default, so every guard writes its decision — an empty impl Guard for X {} does not compile, and neither does a guard writing only check_http — and none admits a unit it never decided. GuardFor<V>, V the view of the units a site dispatches, says which units that decision was written for:

Bound atRequiresBecause it runs
#[controller] / #[routes], #[gateway] structGuardFor<HttpView>check_http, check unless overridden
#[resolver] / #[operations]GuardFor<GraphqlView>check
beside a #[subscribe_message]GuardFor<WsView>check
#[mcp] host / #[tools] operationGuardFor<McpView>check

Declare it next to the entry it covers — impl GuardFor<GraphqlView> for RequireAdmin {} — and the binding compiles. Bind a guard that lacks it and it does not, with a diagnostic naming the view and the way out. AuthnGuard is the guard it catches most often: its decision is the HTTP request’s, which is why a resolver binds AuthzGuard alone and leaves authentication to the guards at the /graphql request. Bound on one anyway:

Terminal window
$ cargo check -p features
error[E0277]: `nest_rs::authn::AuthnGuard<JwtStrategy<Claims>>` does not declare that it checks `GraphqlView` units
--> crates/features/src/users/graphql/resolver.rs:14:14
|
14 | #[use_guards(AuthnGuard, AuthzGuard)]
| ^^^^^^^^^^ bound at a site whose units are `GraphqlView`
|
= note: a guard's `check` decides the units it declares; bound where its units are another edge's, it would run a decision written for a view they do not have
= note: write the guard's decision for `GraphqlView` units in `Guard::check` (overriding `Guard::check_http` only where the HTTP request differs from the unit), then declare `impl GuardFor<GraphqlView> for nest_rs::authn::AuthnGuard<JwtStrategy<Claims>> {}`

A guard whose one check is the same on every edge declares it once for all of them, impl<V: UnitView> GuardFor<V> for X {} — ThrottlerGuard does.

A guard bound globally takes no GuardFor. A global guard serves whichever edges it implements — its check_http on the request, its check on every unit — and requiring GuardFor<HttpView> there would refuse a GraphQL-only one, where the alternative is four global lists where the developer wrote one. Since every guard writes check, a pooled guard admits no unit it did not decide: one whose decision is the request’s says Ok(()) there, in one visible line.

A guard on the #[gateway] struct declares GuardFor<HttpView>, not GuardFor<WsView> — the upgrade is an HTTP GET, and WsView belongs to the per-message scope.

  • Guards — writing a guard, its scopes, and what it attaches.
  • Execution context — the context both entries read, and each edge’s view.
  • Endpoint guards — the guards a module adds to /graphql and /mcp.