Crate ws_stream_wasm

ws_stream_wasm

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
  • Dependencies
• Usage
  • Basic Events Example
• API
• References
• Contributing
  • Code of Conduct
• License

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"

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.

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.

The integration tests are also useful.

References

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

• HTML Living Standard
• RFC 6455 - The WebSocket Protocol

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.

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

Structs

CloseEvent	An event holding information about how the connection was closed.
NextEvent	Future that resolves to the next WsEvent filtered to the type(s) you want.
WsErr	The error type for errors happening in ws_stream_wasm.
WsEventType	The different types of events a WebSocket can generate. This is used for filtering in NextEvent.
WsIo	A futures 0.3 Sink/Stream of WsMessage. It further implements AsyncRead/AsyncWrite that can be framed with codecs. You can use the compat layer from the futures library if you want to use tokio codecs. See the integration tests if you need an example.
WsStream	The meta data related to a websocket.

Enums

WsErrKind	The different kind of errors that can happen when you use the ws_stream_wasm API.
WsEvent	Events related to the WebSocket
WsMessage	Represents a WebSocket Message, after converting from JavaScript type.
WsState	Indicates the state of a Websocket connection. The only state in which it's valid to send and receive messages is WsState::Open.