ws_stream_wasm 0.2.0

A convenience library for using websockets in WASM
Documentation

ws_stream_wasm

standard-readme compliant Build Status Docs crates.io

A convenience library for using websockets in WASM

features:

  • WsStream: A wrapper around web_sys::WebSocket.
  • WsMessage: A simple rusty representation of a WebSocket message.
  • WsIo: A futures Sink/Stream of WsMessage. (can use the futures compat layer to get futures 01 versions). It also implements AsyncRead/AsyncWrite from futures 0.3. With the compat layer you can obtain futures 01 versions for use with tokio codec.
  • WsEvents: WsStream is observable with pharos for events (mainly 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.

missing features:

  • no automatic reconnect
  • not all features are thoroughly tested. Notably, I have little use for extensions and subprotocols. 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.1

With raw Cargo.toml

[dependencies]

   ws_stream_wasm = "^0.1"

Upgrade

Please check out the changelog when upgrading.

Dependencies

This crate has few dependiencies. Cargo will automatically handle it's dependencies for you.

There are no optional features.

Usage

Please have a look in the examples directory of the repository.

The integration tests are also useful.

Basic events example

#![ feature( async_await ) ]

use
{
   async_runtime  :: rt                , // from crate naja_async_runtime
   ws_stream_wasm :: *                 ,
   pharos         :: *                 ,
   wasm_bindgen   :: UnwrapThrowExt    ,
   futures        :: stream::StreamExt ,
};

let program = async
{
   let (mut ws, _wsio) = WsStream::connect( "127.0.0.1:3012", None ).await

      .expect_throw( "assume the connection succeeds" );

   let mut evts = ws.observe_unbounded();

   ws.close().await;

   // Note that since WsStream::connect resolves to an opened connection, we don't see
   // any Open events here.
   //
   assert_eq!( WsEventType::CLOSING, evts.next().await.unwrap_throw().ws_type() );
   assert_eq!( WsEventType::CLOSE  , evts.next().await.unwrap_throw().ws_type() );
};

rt::spawn_local( program ).expect_throw( "spawn program" );

API

Api documentation can be found on docs.rs.

References

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

Contributing

This repository accepts contributions. Ideas, questions, feature requests and bug reports can be filed through github issues.

Pull Requests are welcome on github. By commiting pull requests, you accept that your code might be modified and reformatted to fit the project coding style or to improve the implementation. Please discuss what you want to see modified before filing a pull request if you don't want to be doing work that might be rejected.

Please file PR's against the dev branch, don't forget to update the changelog and the documentation.

Testing

For testing we need backend servers to echo data back to the tests. These are in the ws_stream crate.

git clone https://github.com/najamelan/ws_stream
cd ws_stream
cargo run --expample echo --release

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

# the second server is pure tokio-tungstenite without ws_stream wrapping it in AsyncRead/Write. This
# is needed for testing a WsMessage::Text because ws_stream 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