Skip to content

Message posture

Who may send a message: the upgrade's guards, a #[public] the boot holds to its word, and #[authorize] gating a message and judging the rows it answers.

A message runs on a socket its upgrade already admitted. Its posture says who may send it beyond that: nothing more, under a guard that identified the caller; #[public], for a gateway open on purpose; or #[authorize], which gates the message and judges every row it answers.

A message takes HTTP’s grammar, because a socket authenticates where a route does, before any message runs. A message under its gateway’s #[use_guards], the app’s pool or a guard of its own needs no posture: the guards decide, as they do on a route. Where it declares who may call it beyond them, it does so with #[authorize]:

crates/features/src/chat/ws/gateway.rs
#[gateway(path = "/ws")]
#[use_guards(AuthnGuard, AuthzGuard)]
pub struct ChatGateway { /* ... */ }
#[messages]
impl ChatGateway {
#[subscribe_message("history")] // covered by the upgrade's guards
async fn history(&self) -> Vec<ChatMessageDto> { /* ... */ }
#[subscribe_message("message")]
#[authorize(Create, Posting)] // a gate, on a capability no table holds
async fn on_message(&self, msg: SendMessageDto) -> Result<(), WsError> { /* ... */ }
#[subscribe_message("users.list")]
#[authorize(Read, users::Entity)] // class gate, and reads under the caller's ability
async fn list(&self) -> Result<Vec<User>, ServiceError> {
Ok(self.svc.list().await?.iter().map(User::from).collect())
}
}

The boot reads the rest. A message no guard identifying a caller covers says #[public] or fails the boot, which names every such message on the gateway and each remedy; a macro reading an impl cannot see the app’s pool, so this is where it can be said. A rate limit identifies no one, so it covers nothing, and a guard of your own declaring no phase() is read the same way. A gateway running no such guard at its upgrade and with no #[public] message fails the same way, whatever guards its messages bind: a message’s guard runs on that message, while any caller connects, its hooks run and what the server emits reaches the socket.

#[public] means a caller with no credential is admitted, the word’s one meaning on every edge. It is the line a gateway open on purpose writes, and a reviewer greps for:

crates/features/src/ticker/ws/gateway.rs
#[gateway(path = "/ticker")]
pub struct TickerGateway;
#[messages]
impl TickerGateway {
#[subscribe_message("latest")]
#[public]
async fn latest(&self) -> Price { /* ... */ }
}

Behind an upgrade whose guards establish or read who the caller is, one declaring GuardPhase::Authentication or Authorization, no visitor ever reaches the message, so #[public] could open nothing, and the boot refuses it, naming the guard. A guard of the app’s pool runs at every upgrade, so a gateway opens beneath it only by moving that guard onto the hosts it should cover. A guard that identifies no one — a rate limit — leaves it standing: a visitor does reach the message, and the word is true.

A bare #[public] reads nothing a grant guards. A ticker keeps the bare word and pays nothing for it. A message serving rows to a visitor names them, with #[authorize]’s arguments, its gate and its reads:

crates/features/src/posts/ws/gateway.rs
#[gateway(path = "/feed")]
pub struct FeedGateway;
#[messages]
impl FeedGateway {
#[subscribe_message("latest")]
#[public(Read, post::Entity)]
#[use_guards(AuthzGuard)]
async fn latest(&self) -> Result<Vec<Post>, WsError> { /* ... */ }
}

The guard beside it builds the rules define_visitor writes, since no ability reached a message under an upgrade no guard ran at: those rules answer every caller of such a socket.

#[authorize(Action, Entity)] emits what you would otherwise write by hand. Right after the message’s guards, before any interceptor, exception filter or pipe, a class-level gate asks the caller’s ambient Ability whether it may perform Action on Entity; a refusal is an error frame and nothing else runs. The handler then reads through Repo under that ability, so its rows are the ones the caller may read, and each wire row it answers was judged for the caller where User::from(&row) built it: a column a field grant withholds reads null in the frame. You write no masking call, and nothing reads the reply back.

A wire row the caller may not read at all — a write’s reply to a caller whose Read grants refuse that row — answers a FORBIDDEN frame, and one judged for someone else (a row kept from another socket’s message) the opaque INTERNAL frame; each files one line on nest_rs::authz naming the message as its mounted line does, path and event. A gated message no ability guard reaches refuses the boot, so a message never runs with no ability to judge its rows. A frame pushed to other connections is not a reply and carries no caller’s row; see Server-side push.