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-util (which almost all tokio projects depend on)
  • 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 or SSE2 for frame (un)masking and accelerated UTF-8 validation
• Strict conformance with the websocket specification, passes the Autobahn test suite without relaxations by default (some can be enabled for performance)
• 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 and SSE2 accelerated masking and UTF-8 validation
• 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 prefered 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 is the default used and 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

For these reasons, I recommend disabling default features and using a configuration that makes sense for you, for example:

# Tiny client
tokio-websockets = { version = "*", default-features = false, features = ["client", "fastrand", "sha1_smol"] }
# Client with SIMD, cryptographically secure RNG and rustls
tokio-websockets = { version = "*", default-features = false, features = ["client", "getrandom", "simd", "rustls-webpki-roots"] }

Example

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

More examples can be found in the examples folder.

use futures_util::SinkExt;
use http::Uri;
use tokio::net::TcpListener;
use tokio_websockets::{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 ws_stream = 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::from_static("ws://127.0.0.1:3000");
  let mut client = ClientBuilder::from_uri(uri).connect().await?;

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

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

  Ok(())
}

Caveats / Limitations / ToDo

Currently, WebsocketStream does not implement Stream due to the poll_next nature of the trait, which makes implementing it with actual async code near impossible.

I am waiting for async traits and will implement it once possible. Until then, a method called next already exists and serves as a replacement for futures-util's next, which most users were probably looking for.

Further, websocket compression is currently unsupported.