Skip to content

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.

WsModule registers WsServer in the container. Import the module, ask for the registry by injection, and call its push methods directly:

crates/features/src/notify/service.rs
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)
}
}
crates/features/src/notify/module.rs
#[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.

WsServer and WsClient share the same push verbs, named slightly differently to reflect the missing per-connection context:

WsServer methodReachesWsClient 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 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 job has no request, no client, no socket — only the registry:

crates/features/src/notify/schedule/tasks.rs
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.

The question is “do I have a WsClient already?”:

  • Inside a #[subscribe_message] or lifecycle hook — use the WsClient the handler asks for. It already holds a registry reference and adds emit(...) for “this connection only,” which WsServer cannot offer without a ConnId you tracked yourself.
  • Outside any handler — inject WsServer. There is no client to thread through, and capturing one across an await boundary 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:

crates/features/src/chat/service.rs (from the demo, abridged)
#[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.

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.

  • Namespaces — when a gateway needs its own registry separate from the global one.
  • Rooms — the WsClient side of the same surface.