Expand description
A WebSocket fan-out server: publish once, every subscriber gets it.
Clients connect, present a token, subscribe to channels by name, and receive every message published on those channels as JSON text frames. The server does not know what a channel means or what a payload contains — channels are strings and payloads are opaque JSON, embedded verbatim and serialised once per publish, so a message to a thousand subscribers costs one serialisation and a thousand queue pushes.
What it gets right that is easy to get wrong:
- Heartbeats that work with browsers. The server sends WebSocket Ping frames and counts any inbound traffic as liveness. Browsers answer Ping frames automatically and never send Pong frames unprompted; a server that pings in JSON and waits for a Pong frame drops every browser at its first timeout.
- Slow clients pay, nobody else does. Each connection has a bounded queue; a full queue drops the frame for that client and counts it. The publisher never blocks. A client that keeps dropping is closed.
- An acknowledgement to wait for.
authenticatedis sent before anything else, so a client knows when it may subscribe instead of guessing. - Nothing about your domain. Token validation and authorisation are traits; the defaults accept a fixed token and every channel. There are no tiers in here.
§Example
use ws_fanout::{Server, StaticToken};
let server = Server::builder()
.validator(StaticToken::new("demo-token", "demo"))
.bind("127.0.0.1:9001")
.await?;
// From any thread, as often as you like:
server.publish_json("ticker:BTC-USD", &serde_json::json!({ "last": 79134.01 }));A client, in JavaScript:
const ws = new WebSocket("ws://127.0.0.1:9001");
ws.onopen = () => ws.send(JSON.stringify({ type: "auth", token: "demo-token" }));
ws.onmessage = (e) => {
const m = JSON.parse(e.data);
if (m.type === "authenticated") ws.send(JSON.stringify({ type: "subscribe", channels: ["ticker:BTC-USD"] }));
if (m.type === "data") console.log(m.channel, m.payload);
};The protocol is specified in docs/protocol.md. With the outcry feature the server
can be fed from a shared-memory queue on a dedicated thread; see
Server::consume_outcry in the outcry_source module.
Re-exports§
pub use auth::HmacJwt;pub use auth::AllowAll;pub use auth::Authorizer;pub use auth::Claims;pub use auth::StaticToken;pub use auth::TokenValidator;pub use error::Error;pub use error::Result;pub use protocol::ClientMessage;pub use protocol::Frame;pub use protocol::ServerMessage;pub use registry::Metrics;pub use server::Config;pub use snapshot::LastValue;pub use snapshot::NoSnapshots;pub use snapshot::SnapshotSource;
Modules§
- auth
- Who a connection is, and what it may subscribe to.
- error
- Error type.
- outcry_
source - Feed the server from an
outcryshared-memory queue. - protocol
- The wire protocol: JSON text frames, tagged by
type. - registry
- Connections and their subscriptions.
- server
- The listener and the per-connection state machine.
- snapshot
- Initial state for a channel, sent on subscribe.