A convenience library for using web sockets in WASM
This is a fork of wsstreamwasm
that adds support for Clone to WsStream which may or may not create a memory leak.
The web-sys bindings for websockets aren't very convenient to use directly. This crates hopes to alleviate that. Browsers can't create direct TCP connections, and by putting AsyncRead/AsyncWrite on top of websockets, we can use interfaces that work over any async byte streams from within the browser. The crate has 2 main types. The WsMeta type exists to allow access to the web API while you pass WsStream to combinators that take ownership of the stream.
features:
- [WsMeta]: A wrapper around [web_sys::WebSocket].
- [WsMessage]: A simple rusty representation of a WebSocket message.
- [WsStream]: A futures Sink/Stream of WsMessage.
It also has a method into_io() which let's you get a wrapper that implements AsyncRead/AsyncWrite/AsyncBufRead (tokio version behind the feature tokio_io).
- [WsEvent]: [WsMeta] is observable with pharos for events (mainly useful for connection close).
NOTE: this crate only works on WASM. If you want a server side equivalent that implements AsyncRead/AsyncWrite over
WebSockets, check out wsstreamtungstenite.
missing features: - no automatic reconnect - not all features are thoroughly tested. Notably, I have little use for extensions and sub-protocols. Tungstenite, which I use for the server end (and for automated testing) doesn't support these, making it hard to write unit tests.
With cargo add:
cargo add ws_stream_wasm
With cargo yaml: ```yaml dependencies:
wsstreamwasm: ^0.7 ```
In Cargo.toml: ```toml [dependencies]
wsstreamwasm = "0.7" ```
Please check out the changelog when upgrading.
This crate has few dependencies. Cargo will automatically handle it's dependencies for you.
There is one optional features. The tokio_io features causes the WsIo returned from [WsStream::into_io] to implement the
tokio version of AsyncRead/AsyncWrite.
The integration tests show most features in action. The example directory doesn't currently hold any interesting examples.
The types in this library are Send as far as the compiler is concerned. This is so that you can use them with general purpose
libraries that also work on WASM but that require a connection to be Send. Currently WASM has no threads though and most
underlying types we use aren't Send. The solution for the moment is to use [send_wrapper::SendWrapper]. This will panic
if it's ever dereferenced on a different thread than where it's created. You have to consider that the types aren't Send, but
on WASM it's safe to pass them to an API that requires Send, because there is no multi-threading.
The main entrypoint you'll want to use, eg to connect, is [WsMeta::connect].
```rust use { wsstreamwasm :: * , pharos :: * , wasmbindgen :: UnwrapThrowExt , wasmbindgenfutures :: futures03::spawnlocal , futures :: stream::StreamExt , };
let program = async { let (mut ws, _wsio) = WsMeta::connect( "ws://127.0.0.1:3012", None ).await
.expect_throw( "assume the connection succeeds" );
let mut evts = ws.observe( ObserveConfig::default() ).expect_throw( "observe" );
ws.close().await;
// Note that since WsMeta::connect resolves to an opened connection, we don't see // any Open events here. // assert!( evts.next().await.unwrapthrow().isclosing() ); assert!( evts.next().await.unwrapthrow().isclosed () ); };
spawn_local( program ); ```
This shows how to filter events. The functionality comes from pharos which we use to make
[WsMeta] observable.
```rust use { wsstreamwasm :: * , pharos :: * , wasmbindgen :: UnwrapThrowExt , wasmbindgenfutures :: futures03::spawnlocal , futures :: stream::StreamExt , };
let program = async { let (mut ws, _wsio) = WsMeta::connect( "ws://127.0.0.1:3012", None ).await
.expect_throw( "assume the connection succeeds" );
// The Filter type comes from the pharos crate. // let mut evts = ws.observe( Filter::Pointer( WsEvent::isclosed ).into() ).expectthrow( "observe" );
ws.close().await;
// Note we will only get the closed event here, the WsEvent::Closing has been filtered out. // assert!( evts.next().await.unwrapthrow().isclosed () ); };
spawn_local( program ); ```
Api documentation can be found on docs.rs.
The reference documents for understanding web sockets and how the browser handles them are: - HTML Living Standard - RFC 6455 - The WebSocket Protocol
Please check out the contribution guidelines.
For testing we need back-end servers to echo data back to the tests. These are in the ws_stream_tungstenite crate.
```bash
git clone https://github.com/najamelan/wsstreamtungstenite
cd wsstreamtungstenite
cargo run --example echo --release
cargo run --example echo_tt --release -- "127.0.0.1:3312"
wasm-pack test --firefox [--headless] [--release] wasm-pack test --chrome [--headless] [--release] ```
In general chrome is well faster. When running it in the browser (without --headless) you get trace logging
in the console, which helps debugging. In chrome you need to enable verbose output in the console,
otherwise only info and up level are reported.
Any of the behaviors described in point 4 "Unacceptable Behavior" of the Citizens Code of Conduct are not welcome here and might get you banned. If anyone, including maintainers and moderators of the project, fail to respect these/your limits, you are entitled to call them out.