Crate plaza_ws 

One client-side WebSocket interface, whatever is underneath.

plaza_session covers the server and is tokio/actix by construction, so a client cannot use it (a browser client least of all). This crate covers the client side: the socket a client holds, with the same shape on a desktop, in a browser and in-process.

Built for a frame loop

Socket::poll is non-blocking and drains into a caller-owned buffer. That choice is made for macroquad-style applications, which have a synchronous loop { ...; next_frame().await } and nowhere to put a future. An async fn recv() would be the natural Rust API and would be unusable there. Reusing the buffer also keeps a per-frame call allocation-free, matching how plaza_server_utils hands back its results.

let mut events = Vec::new();
// once per frame
socket.poll(&mut events);
for event in events.drain(..) {
  match event {
    Event::Open => println!("connected"),
    Event::Message(bytes) => println!("{} bytes", bytes.len()),
    Event::Text(text) => println!("{text}"),
    Event::Closed(reason) => println!("gone: {reason:?}"),
  }
}

Backends

Each is a feature. They can be combined: a native host that also plays enables native and loopback and talks to both over the same trait.

feature	where	underneath
loopback	anywhere	in-process channels, no dependencies
native	desktop	tungstenite on a worker thread
miniquad	browser, under macroquad	our own JS, registered as a miniquad plugin

The browser backend

The constraint comes from the host page’s loader rather than from the browser.

web-sys (and with it gloo-net and tokio-tungstenite-wasm) needs wasm-bindgen, which rewrites the module with wasm-bindgen-cli and ships its own JS to instantiate it. miniquad’s mq_js_bundle.js builds its own import object, lets plugins extend it and instantiates the raw module itself. Both want to own instantiation, so under macroquad the wasm-bindgen route does not work. It also fails silently: miniquad stubs out imports nothing provides, so such a build loads without error and then does nothing.

So the miniquad backend is a few extern "C" declarations against our own JS plugin (js/plaza_ws.js), which needs no crate at all. The two crates that do use miniquad’s plugin mechanism, sapp-jsutils and quad-net, are barely maintained and the mechanism is small enough not to need them.

An application that is not built on macroquad has the opposite problem and wants the wasm-bindgen route. It would be a fourth backend (tokio-tungstenite-wasm behind a web feature), left out until something needs it so it is not shipped untested.

Re-exports

pub use backlog::trim_backlog;

pub use backlog::DroppedBacklog;

Modules

backlog

Discarding a resume backlog before any of it is parsed.

loopback

An in-process pair, for a host that also plays.

native

Desktop, over tungstenite on a worker thread.

pump

The client side of plaza’s framed protocol, pumped once per frame.

scripted

A socket whose arrivals the test scripts.

Enums

CloseReason

Why a socket ended.

Event

Something that arrived, in order.

State

Where a socket is in its lifecycle. Monotonic: a socket never returns to an earlier state, so Closed is terminal and reconnecting means a new socket.

WsError

Traits

SendJson

Sending a value as JSON text, so call sites are not full of serde_json::to_string.

Socket

A client-side WebSocket.

Functions

connect

Connects using whichever real transport this build has for its target.

connect_boxed

connect, boxed: the form an application holds when the backend is decided by the build rather than written at the call site.