Skip to main content

ws_fanout/
lib.rs

1//! A WebSocket fan-out server: publish once, every subscriber gets it.
2//!
3//! Clients connect, present a token, subscribe to channels by name, and receive every
4//! message published on those channels as JSON text frames. The server does not know what
5//! a channel means or what a payload contains — channels are strings and payloads are
6//! opaque JSON, embedded verbatim and serialised **once per publish**, so a message to a
7//! thousand subscribers costs one serialisation and a thousand queue pushes.
8//!
9//! What it gets right that is easy to get wrong:
10//!
11//! - **Heartbeats that work with browsers.** The server sends WebSocket Ping *frames* and
12//!   counts any inbound traffic as liveness. Browsers answer Ping frames automatically and
13//!   never send Pong frames unprompted; a server that pings in JSON and waits for a Pong
14//!   frame drops every browser at its first timeout.
15//! - **Slow clients pay, nobody else does.** Each connection has a bounded queue; a full
16//!   queue drops the frame for that client and counts it. The publisher never blocks. A
17//!   client that keeps dropping is closed.
18//! - **An acknowledgement to wait for.** `authenticated` is sent before anything else, so a
19//!   client knows when it may subscribe instead of guessing.
20//! - **Nothing about your domain.** Token validation and authorisation are traits; the
21//!   defaults accept a fixed token and every channel. There are no tiers in here.
22//!
23//! # Example
24//!
25//! ```no_run
26//! use ws_fanout::{Server, StaticToken};
27//!
28//! # async fn run() -> ws_fanout::Result<()> {
29//! let server = Server::builder()
30//!     .validator(StaticToken::new("demo-token", "demo"))
31//!     .bind("127.0.0.1:9001")
32//!     .await?;
33//!
34//! // From any thread, as often as you like:
35//! server.publish_json("ticker:BTC-USD", &serde_json::json!({ "last": 79134.01 }));
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! A client, in JavaScript:
41//!
42//! ```js
43//! const ws = new WebSocket("ws://127.0.0.1:9001");
44//! ws.onopen = () => ws.send(JSON.stringify({ type: "auth", token: "demo-token" }));
45//! ws.onmessage = (e) => {
46//!   const m = JSON.parse(e.data);
47//!   if (m.type === "authenticated") ws.send(JSON.stringify({ type: "subscribe", channels: ["ticker:BTC-USD"] }));
48//!   if (m.type === "data") console.log(m.channel, m.payload);
49//! };
50//! ```
51//!
52//! The protocol is specified in `docs/protocol.md`. With the `outcry` feature the server
53//! can be fed from a shared-memory queue on a dedicated thread; see
54//! `Server::consume_outcry` in the `outcry_source` module.
55
56#![forbid(unsafe_code)]
57#![warn(missing_docs)]
58#![deny(rustdoc::broken_intra_doc_links)]
59
60pub mod auth;
61pub mod error;
62pub mod protocol;
63pub mod registry;
64pub mod server;
65pub mod snapshot;
66
67#[cfg(feature = "outcry")]
68pub mod outcry_source;
69
70use std::net::SocketAddr;
71use std::sync::Arc;
72
73use serde_json::value::RawValue;
74use tokio::net::{TcpListener, ToSocketAddrs};
75
76#[cfg(feature = "jwt")]
77pub use auth::HmacJwt;
78pub use auth::{AllowAll, Authorizer, Claims, StaticToken, TokenValidator};
79pub use error::{Error, Result};
80pub use protocol::{ClientMessage, Frame, ServerMessage};
81pub use registry::Metrics;
82pub use server::Config;
83pub use snapshot::{LastValue, NoSnapshots, SnapshotSource};
84
85/// A running server. Clone it to publish from anywhere; drop every clone to stop.
86#[derive(Clone)]
87pub struct Server {
88    shared: Arc<server::Shared>,
89    addr: SocketAddr,
90    /// Dropped with the last `Server` clone, which stops the accept loop. Source threads
91    /// hold a `Weak` to it and stop on the same signal. Held for its `Drop`, so without
92    /// a source feature nothing reads it.
93    #[cfg_attr(not(feature = "outcry"), allow(dead_code))]
94    alive: Arc<Accepting>,
95}
96
97/// The accept loop. Aborting it on drop is what makes "drop every clone to stop" true.
98struct Accepting(tokio::task::JoinHandle<Result<()>>);
99
100impl Drop for Accepting {
101    fn drop(&mut self) {
102        self.0.abort();
103    }
104}
105
106impl Server {
107    /// Start configuring a server.
108    pub fn builder() -> Builder {
109        Builder::default()
110    }
111
112    /// The address the listener is bound to. Useful when bound to port 0.
113    pub fn local_addr(&self) -> SocketAddr {
114        self.addr
115    }
116
117    /// Counters.
118    pub fn metrics(&self) -> &Arc<Metrics> {
119        self.shared.registry.metrics()
120    }
121
122    /// Open connections.
123    pub fn connections(&self) -> usize {
124        self.shared.registry.len()
125    }
126
127    /// Subscribers to `channel`.
128    pub fn subscribers(&self, channel: &str) -> usize {
129        self.shared.registry.subscribers(channel)
130    }
131
132    /// Publish `payload` on `channel`. Serialised once; delivered to every subscriber
133    /// whose queue has room. Returns how many received it. Never blocks.
134    pub fn publish(&self, channel: &str, payload: &RawValue) -> usize {
135        let frame = ServerMessage::Data { channel, payload }.to_frame();
136        self.shared.registry.publish(channel, &frame)
137    }
138
139    /// [`publish`](Self::publish) for a value that is not yet JSON text.
140    pub fn publish_json<T: serde::Serialize>(&self, channel: &str, value: &T) -> usize {
141        match serde_json::value::to_raw_value(value) {
142            Ok(raw) => self.publish(channel, &raw),
143            Err(e) => {
144                tracing::error!(channel, error = %e, "payload did not serialise");
145                0
146            }
147        }
148    }
149
150    /// Tell every client that the upstream lost data and everything it holds may be
151    /// stale. Sent to all connections, subscribed or not.
152    pub fn resync_all(&self) -> usize {
153        let frame = ServerMessage::Resync { channels: vec![] }.to_frame();
154        self.shared.registry.broadcast(&frame)
155    }
156
157    /// Tell subscribers of `channels` that those channels lost data.
158    pub fn resync(&self, channels: &[&str]) -> usize {
159        let frame = ServerMessage::Resync {
160            channels: channels.to_vec(),
161        }
162        .to_frame();
163        let mut n = 0;
164        for ch in channels {
165            n += self.shared.registry.publish(ch, &frame);
166        }
167        n
168    }
169}
170
171/// Configures and starts a [`Server`].
172pub struct Builder {
173    config: Config,
174    validator: Box<dyn TokenValidator>,
175    authorizer: Box<dyn Authorizer>,
176    snapshots: Box<dyn SnapshotSource>,
177}
178
179impl Default for Builder {
180    fn default() -> Self {
181        Self {
182            config: Config::default(),
183            validator: Box::new(StaticToken::new("", "anonymous")),
184            authorizer: Box::new(AllowAll),
185            snapshots: Box::new(NoSnapshots),
186        }
187    }
188}
189
190impl Builder {
191    /// Replace the whole [`Config`].
192    pub fn config(mut self, config: Config) -> Self {
193        self.config = config;
194        self
195    }
196
197    /// How tokens are validated. Default: a [`StaticToken`] accepting the empty string.
198    pub fn validator(mut self, v: impl TokenValidator) -> Self {
199        self.validator = Box::new(v);
200        self
201    }
202
203    /// Which channels a connection may subscribe to. Default: all.
204    pub fn authorizer(mut self, a: impl Authorizer) -> Self {
205        self.authorizer = Box::new(a);
206        self
207    }
208
209    /// Where snapshots come from on subscribe. Default: none.
210    pub fn snapshots(mut self, s: impl SnapshotSource) -> Self {
211        self.snapshots = Box::new(s);
212        self
213    }
214
215    /// Ping interval and the silence after which a client is dropped.
216    pub fn heartbeat(
217        mut self,
218        interval: std::time::Duration,
219        timeout: std::time::Duration,
220    ) -> Self {
221        self.config.heartbeat_interval = interval;
222        self.config.heartbeat_timeout = timeout;
223        self
224    }
225
226    /// Refuse connections beyond this many.
227    pub fn max_connections(mut self, n: usize) -> Self {
228        self.config.max_connections = n;
229        self
230    }
231
232    /// Bind and start accepting. The accept loop runs on the current tokio runtime.
233    ///
234    /// # Errors
235    ///
236    /// [`Error::Config`] if a [`Config`] field holds a value the server cannot run with,
237    /// checked before the listener is bound.
238    pub async fn bind(self, addr: impl ToSocketAddrs) -> Result<Server> {
239        self.config.validate()?;
240        let slots = Arc::new(tokio::sync::Semaphore::new(self.config.max_connections));
241        let listener = TcpListener::bind(addr).await?;
242        let addr = listener.local_addr()?;
243        let shared = Arc::new(server::Shared {
244            config: self.config,
245            registry: registry::Registry::new(Arc::new(Metrics::default())),
246            validator: self.validator,
247            authorizer: self.authorizer,
248            snapshots: self.snapshots,
249            slots,
250        });
251        let accept = tokio::spawn(server::serve(listener, Arc::clone(&shared)));
252        Ok(Server {
253            shared,
254            addr,
255            alive: Arc::new(Accepting(accept)),
256        })
257    }
258}