wse-client
The Rust client of WSE: topics with
recovery, reconnects, msgpack, end-to-end encryption and signed messages,
on tokio and in the browser (WebAssembly).
It speaks the protocol of the TypeScript and Python clients to the same
servers: wse in Rust and
wse-server in Python.
[]
= "3"
= { = "1", = ["derive"] }
= "1"
= { = "1", = ["rt-multi-thread", "macros"] }
A stream of what the server sends
use ;
async
A handler, without copies
A Handler is called on the connection's own task with each message read
in place from its frame; its payload decodes into the application's types,
borrowing from the frame.
use ;
;
async
examples/chat_client.rs talks to the chat server of the wse crate.
What a client does
- Topics with recovery. Each topic message carries its position; the
client drops duplicates, holds what comes past a gap while it asks the
server for what is missing, and after a reconnect subscribes again from
where it left off. What cannot be recovered is reported as a
Gap. - Reconnects with backoff and jitter, a fresh token from a
TokenProvidereach time; an expired or refused token, a server that refuses the session, and the application's own close end the client. - Heartbeats both ways, and a connection silent for too long is made again.
- Wire formats. JSON in text or binary frames, compressed frames, and
msgpack (
Format::Msgpack, 24-41% fewer bytes). - End-to-end encryption with the server's identity key pinned
(
Encryption): whatever terminates TLS in between sees nothing. - Signed messages.
Client::send_signedsigns with the client's key for the server's; the server's signed messages are checked against the keys the client pins, and each carries its proof. With encryption, the client also proves its key inside the session, which binds a token that names the key to this client (Encryption::bind_session, on by default), and stops unless the server confirms the key. - Back-pressure. A handler that waits in
readyholds the server back; the stream ofconnectdoes the same while nobody reads it.
# async
In the browser
The same crate builds for wasm32-unknown-unknown, for applications in
Leptos, Yew, Dioxus and the like, with the same API. There the connection
is the browser's WebSocket, on the page's task: a handler need not be
Send, and Client::connect is awaited from the page's own futures.
- The browser sends the page's cookies with the upgrade and no header, so
the server takes the client by its cookie (
jwt_cookie_name);token,headersandtlsdo not apply, and aTokenProvideris asked before each attempt only to refresh what it must. - The browser cannot hold a WebSocket back: what comes waits in memory
until the handler or the stream takes it (
Handler::readyis not called there), and the client's own sends wait while the browser holds a megabyte unsent. - End-to-end encryption and signed messages run on RustCrypto there, checked against the same vectors as aws-lc-rs.
Features
aws-lc(default):wss://with rustls and the Mozilla root certificates, end-to-end encryption and signed messages, on aws-lc-rs (in the browser: encryption and signing on RustCrypto, TLS the browser's). Without it there is no end-to-end encryption or signing, and natively nowss://; in the browserwss://is the browser's own TLS.fips: aws-lc-rs built from its FIPS 140-3 validated module (needs CMake and Go).
The protocol is documented in the repository.
License
MIT