Rustango docs
← Guides

WebSockets & SSE

Most requests are one-shot: ask, answer, done. Real-time features are the exception — a live notification, a progress bar, a dashboard that updates itself, a chat. The server needs to push to the browser without being asked. Rustango gives you both push transports on one foundation:

  • SSE (Server-Sent Events) — a one-way stream, server → browser, over plain HTTP. The browser's built-in EventSource auto-reconnects. Simplest thing that works; use it for notifications, progress, live counters, feeds.
  • WebSockets — a full-duplex channel, both directions. Use it when the client also sends (chat, collaborative editing, presence).

Both fan out through the same in-process broadcast bus ([EventBus]), so "send this to every connected client" is one call regardless of transport.

Source: rustango::sse (EventBus) — behind the sse feature; and rustango::ws (WsHub, WsConfig, ws_handler) — behind the websocket feature (implies admin + sse + axum/ws). Both are in the default feature set. The MCP server's server→client channel (rustango::mcp::transport) is a production consumer of the SSE side.

Runnable reference: the authoritative, up-to-date snippets are the module quick-starts in src/sse.rs and src/ws.rs; EventBus's fan-out is covered by the unit tests in src/sse.rs.

New to a term here? SSE, WebSocket, broadcast, keep-alive/ping, back-pressure — see the glossary.

Table of contents


SSE or WebSocket — which?

SSEWebSocket
Directionserver → client onlybidirectional
Transportplain HTTP (text/event-stream)ws:// / wss:// upgrade
Reconnectautomatic (built into EventSource)you handle it (or a client lib does)
Proxies / infrajust HTTP — trivially proxiedneeds upgrade-aware proxies
Client APInew EventSource(url)new WebSocket(url)
Use it fornotifications, progress, live counters, feedschat, presence, collaborative editing, anything the client also sends

Rule of thumb: if the client only receives, use SSE — it's less code, auto-reconnects, and rides ordinary HTTP. Reach for a WebSocket only when the client also sends.

The broadcast bus

Both transports sit on [EventBus<T>] — a cheap-to-clone fan-out channel. One send reaches every subscriber; slow subscribers lag rather than blocking the others. T is your own Clone message type.

use rustango::sse::EventBus;
use serde::{Serialize, Deserialize};

#[derive(Clone, Serialize, Deserialize)]
struct Notification { kind: String, message: String }

// capacity = per-subscriber buffer; older messages drop for a lagging client.
let bus: EventBus<Notification> = EventBus::new(100);

// share `bus` via router state (it's Clone). Then from anywhere:
let delivered = bus.send(Notification { kind: "info".into(), message: "Saved".into() });
//  `delivered` = how many connected clients received it (0 = no-op).

EventBus API: new(capacity), send(event) -> usize, subscribe() -> broadcast::Receiver<T>, receiver_count() -> usize.

Server-Sent Events

Wire the bus to an SSE endpoint with axum's Sse response + an async_stream::stream! that forwards each broadcast message as an event. Add async-stream and futures to your Cargo.toml.

use std::convert::Infallible;
use axum::{extract::State, response::sse::{Event, KeepAlive, Sse}, routing::get, Router};
use futures::Stream;
use rustango::{shutdown::Shutdown, sse::EventBus};

async fn events(
    shutdown: Shutdown,
    State(bus): State<EventBus<Notification>>,
) -> Sse<impl Stream<Item = Result<Event, Infallible>>> {
    let mut rx = bus.subscribe();
    let stream = async_stream::stream! {
        loop {
            let msg = match rx.recv().await {
                Ok(msg) => msg,
                // A slow client skipped messages; keep it connected.
                Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => continue,
                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
            };
            let json = serde_json::to_string(&msg).unwrap_or_default();
            yield Ok(Event::default().event("notification").data(json));
        }
    };
    // keep-alive comments stop idle connections being reaped by proxies.
    // Ends the stream when the server stops.
    Sse::new(shutdown.cut(stream)).keep_alive(KeepAlive::default())
}

let app = Router::new()
    .route("/events", get(events))
    .with_state(bus.clone());

Browser — the built-in EventSource connects and auto-reconnects:

const es = new EventSource('/events');
es.addEventListener('notification', (e) => {
  const n = JSON.parse(e.data);
  console.log(n.kind, n.message);
});
es.onerror = () => {/* EventSource retries automatically */};

WebSockets

For bidirectional traffic, use [WsHub] + [ws_handler]. The hub wraps an EventBus and adds keep-alive pings, JSON (de)serialization, and slow-consumer handling; ws_handler runs one connection until the client disconnects.

use std::time::Duration;
use axum::{extract::{State, WebSocketUpgrade}, response::Response, routing::get, Router};
use rustango::{shutdown::Shutdown, sse::EventBus, ws::WsHub};
use serde::{Serialize, Deserialize};

#[derive(Clone, Serialize, Deserialize)]
struct Tick { value: i64 }

let bus: EventBus<Tick> = EventBus::new(100);
let hub = WsHub::new(bus).keepalive(Duration::from_secs(20));

async fn ws_route(
    ws: WebSocketUpgrade,
    shutdown: Shutdown,
    State(hub): State<WsHub<Tick>>,
) -> Response {
    // Caps the frame reader at `max_message_bytes` before buffering.
    hub.upgrade(ws, shutdown)
}

let app = Router::new()
    .route("/ws", get(ws_route))
    .with_state(hub.clone());

// From anywhere — one call fans out to every connected socket:
hub.broadcast(Tick { value: 42 });
const ws = new WebSocket(`${location.origin.replace('http', 'ws')}/ws`);
ws.onmessage = (e) => { const t = JSON.parse(e.data); console.log('tick', t.value); };

Tuning via [WsConfig] (builder methods on WsHub):

KnobDefaultEffect
.keepalive(Duration)30 sPing interval, busy or idle; a peer silent for a whole interval after a ping is closed
.on_message(fn(&str) -> Option<String>)nonehandle client→server text; return Some(reply) to echo to that client only (call hub.broadcast(..) for fan-out)
.max_message_bytes(n)1 MiBclose the connection if a client message exceeds this
.max_connections(n)noneopen sockets at most; past it upgrade answers 503

Slow consumers don't get silently dropped: a lagging client is told it missed n messages so it can resync or carry on: it gets the text frame {"_lagged": n}. Binary frames from the client are dropped. To pass a full WsConfig at once, use WsHub::with_config(bus, config); hub.receiver_count() counts open sockets.

Both take [Shutdown] as an extractor. When the server stops, an SSE stream wrapped in shutdown.cut(..) ends and a socket gets Close 1001 (going away), so a deploy does not wait out the drain deadline.

Sending from elsewhere

The bus/hub is Clone and lives in router state, so any part of your app — a request handler, a background job, a signal receiver — can push to every connected client by holding a clone and calling bus.send(..) / hub.broadcast(..). A common pattern: a job finishes → it broadcasts a "done" notification → the browser's open SSE stream updates the UI.

One EventBus can back both an SSE route and a WebSocket route at once — WsHub::bus() hands you the underlying bus to share with an SSE handler, so clients on either transport see the same stream.

Per-user events

KeyedEventBus<K, T> gives each key, such as a user or account id, its own topic: send(&key, event) reaches only that key's subscribers, and a topic lives only while someone subscribes. A Subscription reads with recv():

use rustango::sse::{KeyedEventBus, Recv};

let bus: KeyedEventBus<i64, Notification> = KeyedEventBus::new(100);

// In the SSE handler, after auth:
let mut sub = bus.subscribe(user.id);
let stream = async_stream::stream! {
    while let Some(got) = sub.recv().await {
        let event = match got {
            Recv::Event(n) => Event::default().event("notification")
                .data(serde_json::to_string(&n).unwrap_or_default()),
            // Events were missed: tell the client to reload its state.
            Recv::Resync => Event::default().event("resync").data(""),
            _ => continue,
        };
        yield Ok::<_, Infallible>(event);
    }
};

// Anywhere else:
bus.send(&user.id, Notification { kind: "info".into(), message: "Saved".into() });

Lag contract. Recv::Resync means events were missed: the subscriber fell more than capacity behind, or (on PgEventBus) the database connection dropped. Nothing is replayed, so the client reloads what it shows and keeps listening. recv() gives None once the bus is gone.

Across processes

PgEventBus<K, T> (features sse + postgres) is the keyed bus over PostgreSQL LISTEN/NOTIFY, so a worker in another process can publish:

use rustango::session::SessionSecret;
use rustango::sse::PgEventBus;

// In every process, on the same channel name and secret:
let secret = SessionSecret::require_from_env()?;
let bus: PgEventBus<i64, Notification> =
    PgEventBus::connect(&pool, "notifications", 100, &secret).await?;

let mut sub = bus.subscribe(user.id);            // web process
bus.publish(&user.id, &notification).await?;      // any process
  • K and T travel as JSON; an event over PostgreSQL's 8000-byte limit is refused (BusError::TooLarge). Send an id and let the client fetch the rest.
  • Inside an atomic block on the same pool, publish goes out at the commit and not at all on a rollback.
  • A lost connection is re-opened, and every subscriber gets Recv::Resync.
  • LISTEN and NOTIFY need no privilege and are database-wide, so the channel on the wire is an HMAC of the name and the pool's schema under secret. SQL without the secret, such as a schema tenant's role, can neither listen in nor inject, and a bus on a schema-scoped pool only hears its own schema. Tenants with their own database are apart anyway.
  • Each bus keeps one connection of its pool for LISTEN: build one per process (it is Clone), not one per request.

Auth & tenancy

The SSE/WS routes are ordinary axum routes — layer your usual auth on them (session, JWT, API key) exactly as you would any handler; add the extractor to the route and reject before subscribing. In a multi-tenant app, resolve the tenant on the connection and use a per-tenant bus (or filter messages by tenant) so one tenant's events never reach another's clients. The MCP server does exactly this — its authenticated, per-agent SSE channel is built on this same sse foundation.

Scaling notes

EventBus is an in-process tokio::sync::broadcast — fan-out is instant and lock-light, but it only reaches clients connected to this process. Running multiple app instances behind a load balancer? A client connected to node A won't see an event sent on node B. On PostgreSQL, use PgEventBus; otherwise bridge the bus to an external pub/sub (e.g. Redis). Single-node (the common case) needs none of this.

Also size EventBus::new(capacity) for your burst rate: it's the per-subscriber buffer, and a client that falls further behind than capacity gets a Lagged signal rather than unbounded memory growth.

Feature flags

# Cargo.toml — both are in Rustango's default set; list them if you slim features.
rustango = { version = "0.67", features = ["sse", "websocket"] }
  • sse — the EventBus broadcast bus (no extra dependencies). Enough for SSE, since the SSE wire format comes from axum's own response::sse. Not to be confused with rustango::events::EventBus, an always-on typed bus of domain events with async handlers.
  • websocket — the WsHub / ws_handler scaffold; implies admin (axum)
    • sse + axum/ws.