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}