Skip to content

Latest commit

 

History

History
198 lines (138 loc) · 7.73 KB

README.md

File metadata and controls

198 lines (138 loc) · 7.73 KB
Raw

ws_stream_wasm

standard-readme compliant Build Status Docs crates.io

A convenience library for using web sockets in WASM

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 ws_stream_tungstenite.

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.

Table of Contents

Install

With cargo add: cargo add ws_stream_wasm

With cargo yaml:

dependencies:

  ws_stream_wasm: ^0.7

In Cargo.toml:

[dependencies]

   ws_stream_wasm = "0.7"

Upgrade

Please check out the changelog when upgrading.

Dependencies

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.

Usage

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 + Sync 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/Sync. 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 not much multi-threading support. Thus passing it to the bindgen executor will be fine. However with webworkers you can make extra threads nevertheless. The responsibility is on you to assure you don't try to use the Web Api's on different threads.

The main entrypoint you'll want to use, eg to connect, is [WsMeta::connect].

Basic events example

use
{
   ws_stream_wasm       :: *                        ,
   pharos               :: *                        ,
   wasm_bindgen         :: UnwrapThrowExt           ,
   wasm_bindgen_futures :: futures_0_3::spawn_local ,
   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.unwrap_throw().is_closing() );
   assert!( evts.next().await.unwrap_throw().is_closed () );
};

spawn_local( program );

Filter events example

This shows how to filter events. The functionality comes from pharos which we use to make [WsMeta] observable.

use
{
   ws_stream_wasm       :: *                        ,
   pharos               :: *                        ,
   wasm_bindgen         :: UnwrapThrowExt           ,
   wasm_bindgen_futures :: futures_0_3::spawn_local ,
   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::is_closed ).into() ).expect_throw( "observe" );

   ws.close().await;

   // Note we will only get the closed event here, the WsEvent::Closing has been filtered out.
   //
   assert!( evts.next().await.unwrap_throw().is_closed () );
};

spawn_local( program );

API

Api documentation can be found on docs.rs.

References

The reference documents for understanding web sockets and how the browser handles them are:

Contributing

Please check out the contribution guidelines.

Testing

For testing we need back-end servers to echo data back to the tests. These are in the ws_stream_tungstenite crate.

git clone https://github.com/najamelan/ws_stream_tungstenite
cd ws_stream_tungstenite
cargo run --example echo --release

# in a different terminal:
cargo run --example echo_tt --release -- "127.0.0.1:3312"

# the second server is pure async-tungstenite without ws_stream_tungstenite wrapping it in AsyncRead/Write. This
# is needed for testing a WsMessage::Text because ws_stream_tungstenite only does binary.

# in a third terminal, in ws_stream_wasm you have different options:
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.

Code of conduct

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.

License

Unlicence