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.
#[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.
Two entries, four edges
Section titled “Two entries, four edges”A guard writes check, overrides check_http where the request differs, and
the framework runs each at its own seam:
| Entry | Runs | Bound 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 |
check | per GraphQL field, and in front of the federation root fields | #[resolver] / #[operations] |
check | once per inbound envelope, after the upgrade | beside a #[subscribe_message] |
check | once 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.
A guard declares the edges it checks
Section titled “A guard declares the edges it checks”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 at | Requires | Because it runs |
|---|---|---|
#[controller] / #[routes], #[gateway] struct | GuardFor<HttpView> | check_http, check unless overridden |
#[resolver] / #[operations] | GuardFor<GraphqlView> | check |
beside a #[subscribe_message] | GuardFor<WsView> | check |
#[mcp] host / #[tools] operation | GuardFor<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:
$ cargo check -p featureserror[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.
Going further
Section titled “Going further”- 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
/graphqland/mcp.