created_at2022-12-06 16:25:05.70085
updated_at2024-05-24 11:42:45.832174
descriptionHigh performance, strict, tokio-util based WebSockets implementation
Tim Vilgot Mikael Fredenberg (vilgotf)



tokio-websockets 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


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};

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

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

      tokio::spawn(async move {
        // Just an echo server, really
        while let Some(Ok(msg)) = {
          if msg.is_text() || msg.is_binary() {

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

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

  let uri = Uri::from_static("ws://");
  let (mut client, _) = ClientBuilder::from_uri(uri).connect().await?;

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

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



The current MSRV for all feature combinations is Rust 1.64.

Caveats / Limitations / ToDo

WebSocket compression is currently unsupported.

Commit count: 277

cargo fmt