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]:
#[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()) }}What the boot refuses
Section titled “What the boot refuses”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]
Section titled “#[public]”#[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:
#[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:
#[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]
Section titled “#[authorize]”#[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.
What a refused row answers
Section titled “What a refused row answers”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.
Going further
Section titled “Going further”- WebSocket guards — the upgrade gate and the envelope gate a posture stands behind.
- Public reads — the rules a visitor reads under.
- Replies and error frames — what a refusal answers.