10 unstable releases (4 breaking)

0.5.1 Dec 29, 2023
0.4.1 Nov 23, 2023
0.3.3 Jun 16, 2023
0.2.0 Dec 6, 2022

#9 in WebSocket

Download history 488/week @ 2023-11-01 466/week @ 2023-11-08 315/week @ 2023-11-15 374/week @ 2023-11-22 456/week @ 2023-11-29 592/week @ 2023-12-06 378/week @ 2023-12-13 423/week @ 2023-12-20 667/week @ 2023-12-27 527/week @ 2024-01-03 716/week @ 2024-01-10 993/week @ 2024-01-17 581/week @ 2024-01-24 598/week @ 2024-01-31 631/week @ 2024-02-07 825/week @ 2024-02-14

2,852 downloads per month

MIT license

130KB
2K 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
  • http-integration enables a method for WebSocket upgrade http::Request generation

TLS is supported via any of the following feature flags:

The rustls-*-roots features require a crypto provider for rustls. You can either enable the ring feature to use it as the provider and 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 is recommended if the ring feature is enabled (usually 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(String::from("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.64.

Caveats / Limitations / ToDo

WebSocket compression is currently unsupported.

Dependencies

~3–17MB
~217K SLoC