18 releases (9 breaking)

0.10.1 Sep 13, 2024
0.9.0 Aug 4, 2024
0.8.3 May 24, 2024
0.7.0 Feb 27, 2024
0.2.0 Dec 6, 2022

#7 in WebSocket

Download history 928/week @ 2024-07-18 1372/week @ 2024-07-25 1714/week @ 2024-08-01 1548/week @ 2024-08-08 1558/week @ 2024-08-15 1544/week @ 2024-08-22 1840/week @ 2024-08-29 1365/week @ 2024-09-05 1170/week @ 2024-09-12 1398/week @ 2024-09-19 1682/week @ 2024-09-26 1508/week @ 2024-10-03 1058/week @ 2024-10-10 1633/week @ 2024-10-17 1357/week @ 2024-10-24 1281/week @ 2024-10-31

5,662 downloads per month
Used in 8 crates (6 directly)

MIT license

155KB
2.5K SLoC

tokio-websockets

Crates.io GitHub Workflow Status (with event) Documentation

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 (see the benchmarks)

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

TLS is supported via any of the following feature flags:

The rustls-*-roots and rustls-platform-verifier features require a crypto provider for rustls. You can either enable the aws_lc_rs (optionally also FIPS-compliant via the fips feature) or ring features to use these crates as the providers and then use TlsConnector::new(), or bring your own with TlsConnector::new_rustls_with_crypto_provider().

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

  • ring or aws_lc_rs are used if the ring or aws_lc_rs features are enabled (recommended when rustls is used)
  • 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.

use futures_util::{SinkExt, StreamExt};
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("Hello world!")).await?;

  while let Some(Ok(msg)) = client.next().await {
    if let Some(text) = msg.as_text() {
      assert_eq!(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.79.

Caveats / Limitations / ToDo

WebSocket compression is currently unsupported.

Dependencies

~2–28MB
~583K SLoC