wse
A WebSocket engine for reactive user interfaces, run inside your Rust
application: topics with recovery for clients that come back, presence,
servers that form a cluster without a broker, JWT validation, end-to-end
encryption and signed messages, delivered on every CPU core. The same
engine runs the Python package
wse-server; the clients are
wse-client for Rust (with Swift,
Kotlin, Java and Dart packages on it),
wse-client for TypeScript
(React, Vue, Svelte, Angular, Solid, React Native, Electron and Tauri), and
wse-client for Python.
[]
= "3.2"
= "1"
= { = "1", = ["rt-multi-thread", "macros", "net", "signal"] }
A server
A server is a Config, a Handler (what the application hears of its
clients) and a Publisher (what it sends them). It runs on the
application's own tokio runtime.
use ;
/// Every connection joins its user's topic.
;
async
examples/chat.rs is a complete chat room; it prints a token to try it
with, and the wse-client crate's chat_client example talks to it.
What a server does
- Fan-out on every core. Each connection belongs to a delivery lane, one
per core; a broadcast to 10,000 connections is delivered by every core at
once. A publisher faster than its clients waits for room
(
Publisher::ready) instead of filling memory: past 65,536 queued sends, a send fails withError::Full. - Topics. Exact names and glob patterns, queue groups (one member of a
group gets each message), per-connection ACLs, from the JWT
wse_topicsclaim or set by the application. - Recovery. Topics keep their last messages; a client that comes back with its position gets what it missed, or learns that it must reload.
- The outbox. A 3.2 client numbers what it sends, and the server
takes each message once and confirms it: a repeat is confirmed and
dropped, a refusal said (
busywhenHandler::messagereturns false;not_ready,rate_limited,missing). One it cannot tell it took already is handed on with"possible_repeat": true, and the application checks itsid. Each node keeps decisions for at most 262,144 idle outboxes (or twicemax_connections, if more) for up to a day after disconnect, forgetting the longest-disconnected first. Another node can ask the last one for its decisions. A newer connection of the producer closes the older one (4409). - Presence. Who is on a topic, with their data, across the cluster.
- Users.
send_to_userreaches every tab and device of a user,disconnect_usercloses them all. - Cluster.
Server::connect_clusterlinks nodes over a binary protocol in TLS, from the cluster's secret (ClusterSettings::secret) or from certificates, and forwards each topic only where it has subscribers. With recovery on, a link that drops and comes back loses nothing that either node still holds: each gets what it missed from the other, in order, before anything new, and a client whose recovery reaches past what is gone is told so. Addresses arehost:port, an IPv6 address with its zone by number. - Security. JWT validation in the handshake (HS*, RS*, PS*, ES*, EdDSA,
key rotation), origin checks, rate limits, end-to-end encryption with the
server's identity key, signed messages both ways. A token that names the
client's key (
cnf) opens a session only for the client that proves the key (Config::bind_sessions;Publisher::accept_boundwhen the application authenticates connections itself). - Operations. Graceful drain, health snapshots and Prometheus metrics.
Features
server(default): the server. Without it the crate is itsprotocolmodule alone: the crypto, end-to-end sessions and signed messages that the server andwse-clientshare, which is how the client depends on it, in the browser too.fips: aws-lc-rs built from its FIPS 140-3 validated module (needs CMake and Go). The crypto is aws-lc-rs otherwise, for TLS, JWT, end-to-end encryption and signing.
The protocol, the close codes and the cluster wire format are documented in the repository.
License
MIT