tokio-websockets

High performance, strict, tokio-util based websockets implementation.

Why use tokio-websockets?

• Built with tokio-util, intended to be used with tokio from the ground up
• Minimal dependencies: The base only requires:
  • tokio, tokio-util, bytes, futures-core, futures-sink
  • SHA1 backend, e.g. sha1_smol (see Feature flags)
• Big selection of features to tailor dependencies to any project (see Feature flags)
• SIMD support: AVX2, SSE2 or NEON for frame (un)masking and accelerated UTF-8 validation
• Strict conformance with the websocket specification, passes the Autobahn test suite without relaxations by default
• TLS support
• Reusable TLS connectors
• Uses widely known crates from the ecosystem for types, for example Uri from http in the client
• Cheaply clonable messages due to Bytes as payload storage
• Tuned for performance: no unnecessary duplicate UTF-8 validation, no duplicate bounds checking (this however heavily uses unsafe code, which is sound to my knowledge, if not, open an issue!)

Feature flags

Feature flags in tokio-websockets are added to allow tailoring it to your needs.

• simd will enable AVX2, SSE2 or NEON accelerated masking and UTF-8 validation. Additionally enabling the nightly feature when using a nightly compiler will also enable AVX512 accelerated masking
• client enables a tiny client implementation
• server enables a tiny server implementation
• http-integration enables a method for websocket upgrade http::Request generation

TLS support is supported via any of the following feature flags:

• native-tls for a tokio-native-tls backed implementation
• rustls-webpki-roots for a tokio-rustls backed implementation with webpki-roots
• rustls-native-roots for a tokio-rustls backed implementation with rustls-native-certs

One SHA1 implementation is required, usually provided by the TLS implementation:

• ring is used if rustls is the TLS library
• The openssl feature will use openssl, usually preferred on most Linux/BSD systems with native-tls
• The sha1_smol feature can be used as a fallback if no TLS is needed

The client feature requires enabling one random number generator:

• fastrand can be used as a PRNG
• getrandom can be used as a cryptographically secure RNG
• rand can be used as an alternative to fastrand and should be preferred if it is already in the dependency tree

Example

This is a simple websocket echo server without any proper error handling.

More examples can be found in the examples folder.

```rust use futuresutil::{SinkExt, StreamExt}; use http::Uri; use tokio::net::TcpListener; use tokiowebsockets::{ClientBuilder, Error, Message, ServerBuilder};

[tokio::main]

async fn main() -> Result<(), Error> { let listener = TcpListener::bind("127.0.0.1:3000").await?;

tokio::spawn(async move { while let Ok((stream, )) = listener.accept().await { let mut wsstream = ServerBuilder::new() .accept(stream) .await?;

  tokio::spawn(async move {
    // Just an echo server, really
    while let Some(Ok(msg)) = ws_stream.next().await {
      if msg.is_text() || msg.is_binary() {
        ws_stream.send(msg).await?;
      }
    }

    Ok::<_, Error>(())
  });
}

Ok::<_, Error>(())

});

let uri = Uri::fromstatic("ws://127.0.0.1:3000"); let (mut client, _) = ClientBuilder::fromuri(uri).connect().await?;

client.send(Message::text(String::from("Hello world!"))).await?;

while let Some(Ok(msg)) = client.next().await { if let Some(text) = msg.astext() { asserteq!(text, "Hello world!"); // We got one message, just stop now client.close().await?; } }

Ok(()) } ```

MSRV

The current MSRV for all feature combinations is Rust 1.64.

Caveats / Limitations / ToDo

Websocket compression is currently unsupported.