Skip to main content

Crate ws_fanout

Crate ws_fanout 

Source
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. authenticated is 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 outcry shared-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.

Structs§

Builder
Configures and starts a Server.
Server
A running server. Clone it to publish from anywhere; drop every clone to stop.