Server-side push
Reach connected clients from outside a handler — inject WsServer in a service, a scheduled job, or an HTTP route.
A WsClient exists only inside a #[subscribe_message] (or a
lifecycle hook). Anything that fires without a client message — a
cron job, a queue processor, an HTTP route, a service reacting to a
domain event — has nothing to call client.broadcast(...) on. The
answer is WsServer: the connection registry itself, injected as a
singleton.
The registry as a provider
Section titled “The registry as a provider”WsModule registers WsServer in the container. Import the module,
ask for the registry by injection, and call its push methods directly:
use std::sync::Arc;
use nest_rs::core::injectable;use nest_rs::ws::WsServer;
#[injectable]pub struct NotifyService { #[inject] server: Arc<WsServer>,}
impl NotifyService { pub fn announce(&self, text: &str) -> Result<usize, serde_json::Error> { self.server.broadcast("announce", &text) }}#[module( imports = [WsModule], providers = [NotifyService],)]pub struct NotifyModule;That’s the whole wiring. Any handler that calls
NotifyService::announce reaches every live WebSocket connection, even
the connections held by an entirely different gateway. The registry
does not care who recorded the message. WsModule attaches no transport, so a
binary that imports this port only to push — a worker — opens no listener; the
sockets are served by the binary importing a WebSocket adapter, whose gateway
brings HttpModule.
What the server exposes
Section titled “What the server exposes”WsServer and WsClient share the same push verbs, named slightly
differently to reflect the missing per-connection context:
WsServer method | Reaches | WsClient analog |
|---|---|---|
broadcast(event, &data) | Every live connection. | client.broadcast(...) |
emit_to(room, event, &data) | Connections joined to room. | client.to(room, ...) |
emit(conn_id, event, &data) | One specific connection by id. | client.emit(...) (this connection) |
connection_count() | Live connection total. | — |
Each method serializes data with serde, and returns the number of outboxes that
accepted the frame (usize) or whether this connection’s did (bool: false when it
is gone or its outbox refused the frame). A serializer failure surfaces as
Err(serde_json::Error); a frame an outbox refuses is shed, with one warn on
nest_rs::ws — see Backpressure.
A push carries no caller’s row
Section titled “A push carries no caller’s row”A wire row is judged for the caller whose ability builds it. A push has no
such caller: every connection WsServer reaches receives the same frame,
whoever is behind it, so a row judged for the caller pushing it refuses there
(A row answers the caller who judged it).
Push only what every recipient may read — a notice that something changed, an
id the client then fetches through a gated message or route — or a row a job
built, which holds every exposed column for no caller. The framework builds no
row per recipient.
A scheduled push
Section titled “A scheduled push”A scheduled job has no request, no client, no socket — only the registry:
use std::sync::Arc;
use nest_rs::core::injectable;use nest_rs::schedule::scheduled;use nest_rs::ws::WsServer;
#[injectable]pub struct Heartbeat { #[inject] server: Arc<WsServer>,}
#[scheduled]impl Heartbeat { #[every("5s")] async fn tick(&self) -> anyhow::Result<()> { self.server.broadcast("heartbeat", &chrono::Utc::now())?; Ok(()) }}Every five seconds, every connected client receives
{"event":"heartbeat","data":"2026-06-08T10:23:14Z"}. Same approach
works from a #[processor] consuming a queue, an HTTP route reacting
to a webhook, a domain event published on an internal bus — anywhere
DI reaches, the registry reaches.
Push vs broadcast — which one
Section titled “Push vs broadcast — which one”The question is “do I have a WsClient already?”:
- Inside a
#[subscribe_message]or lifecycle hook — use theWsClientthe handler asks for. It already holds a registry reference and addsemit(...)for “this connection only,” whichWsServercannot offer without aConnIdyou tracked yourself. - Outside any handler — inject
WsServer. There is no client to thread through, and capturing one across anawaitboundary in some external task is exactly the kind of escape hatch this avoids.
A common pattern is to do both in one feature: handlers route messages
into a service that records state, and the service holds the registry
and broadcasts the derived event. crates/features/src/chat/service.rs
shows exactly this:
#[injectable]pub struct ChatService { #[inject] server: Arc<WsServer>, history: Mutex<VecDeque<ChatMessageDto>>, // …}
impl ChatService { // … pub fn record( &self, author: Subject, message: SendMessageDto, ) -> Result<ChatMessageDto, serde_json::Error> { let stored = ChatMessageDto { author, text: message.text, }; // … let reached = self.server.broadcast("message", &stored)?; // … Ok(stored) } // …}The gateway handler is two lines — it reads the author off the caller the upgrade authenticated and hands the message over; the service owns the side effect.
Backpressure
Section titled “Backpressure”Each connection has a writer task draining a bounded outbox — 256 frames — into
the socket, so a slow client backs up its own outbox and the read loop on every
other connection stays unaffected. A push to a full outbox is shed, with a
warn on nest_rs::ws: the registry returns the count of outboxes that
accepted the frame, so a broadcast(...) to N connections may report < N
while a slow client lags or a disconnect races it. A reply to a message that
finds the outbox full closes the socket 1008, and a client that takes nothing
at all is dropped at the transport’s send deadline,
<PREFIX>_HTTP__SEND_TIMEOUT_SECS — see
When the server closes a socket.
Reference
Section titled “Reference”WsServer—broadcast,emit_to,emit,connection_count.crates/features/src/chat/service.rs— service-side broadcast pattern.
Going further
Section titled “Going further”- Namespaces — when a gateway needs its own registry separate from the global one.
- Rooms — the
WsClientside of the same surface.