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. A signed message goes out on the connection it was signed on, or not at all. - Live messages.
Client::send_liveandtry_send_livesend on the connection that is ready now, or not at all: one the connection did not write is dropped, never sent on a later connection. For commands that must not run late (a valve, a door, an order). - Another user. When the token provider's next token is another user's, what the last user queued and did not send goes nowhere, and the topics are subscribed again from the start.
- Recovery per stream. A topic published on several servers of a cluster has a stream per server; a recovery names the client's offset in each, and a stream that stayed quiet on the connection for longer than the server keeps one is no longer named. Time away keeps every position.
- Pause and close.
pause(reason)ends the connection, after what is queued went out, and nothing connects while any reason holds;resume(reason)for the last one connects at once and recovers what was missed.close_within(deadline)gives what is queued the deadline to go out and then stops. - 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).native: thenativemodule the Swift, Kotlin and Dart packages are built on: plain types, one shared runtime, cancellable calls, events read in bounded batches, andwss://checked by the system's certificate verifier. Not in the browser.
The protocol is documented in the repository.
License
MIT