async-tungstenite 0.35.0

Async binding for Tungstenite, the Lightweight stream-based WebSocket implementation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# async-tungstenite

Asynchronous WebSockets for [async-std](https://async.rs),
[tokio](https://tokio.rs), [gio](https://gtk-rs.org) and any `std`
`Future`s runtime.

[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Crates.io](https://img.shields.io/crates/v/async-tungstenite.svg?maxAge=2592000)](https://crates.io/crates/async-tungstenite)
[![Build Status](https://github.com/sdroege/async-tungstenite/workflows/CI/badge.svg)](https://github.com/sdroege/async-tungstenite/actions?query=workflow%3ACI)

[Documentation](https://docs.rs/async-tungstenite)

## Usage

Add this in your `Cargo.toml`:

```toml
[dependencies]
async-tungstenite = "*"
```

Take a look at the `examples/` directory for client and server examples. You
may also want to get familiar with [async-std](https://async.rs/) or
[tokio](https://tokio.rs) if you don't have any experience with it.

## What is async-tungstenite?

This crate is based on [tungstenite](https://crates.io/crates/tungstenite)
Rust WebSocket library and provides async bindings and wrappers for it, so you
can use it with non-blocking/asynchronous `TcpStream`s from and couple it
together with other crates from the async stack. In addition, optional
integration with various other crates can be enabled via feature flags

 * `smol-runtime`: Enables the `smol` module, which provides integration with
   the [async-io](https://crates.io/crates/async-io) crate and the
   [smol](https://crates.io/crates/smol) runtime.
 * `smol-native-tls`: Enables the additional functions in the `smol`
   module to implement TLS via
   [async-native-tls](https://crates.io/crates/async-native-tls).
 * `futures-rustls-manual-roots`: Enables the additional functions in the `smol` 
   module to implement TLS via [futures-rustls](https://crates.io/crates/futures-rustls)
   and uses native system certificates found with
   [rustls-manual-roots](https://github.com/rustls/rustls-manual-roots).
 * `futures-rustls-native-certs`: Enables the additional functions in the `smol` 
   module to implement TLS via [futures-rustls](https://crates.io/crates/futures-rustls)
   and uses native system certificates found with
   [rustls-native-certs](https://github.com/rustls/rustls-native-certs).
 * `futures-rustls-platform-verifier`: Enables the additional functions in the `smol` 
   module to implement TLS via [futures-rustls](https://crates.io/crates/futures-rustls)
   and uses native system certificates via the platform verifier found with
   [rustls-platform-verifier](https://github.com/rustls/rustls-platform-verifier).
 * `futures-rustls-webpki-roots`: Enables the additional functions in the `smol` 
   module to implement TLS via [futures-rustls](https://crates.io/crates/futures-rustls)
   and uses the certificates [webpki-roots](https://github.com/rustls/webpki-roots)
   provides.
 * `tokio-runtime`: Enables the `tokio` module, which provides integration
   with the [tokio](https://tokio.rs) runtime.
 * `tokio-native-tls`: Enables the additional functions in the `tokio` module to
   implement TLS via [tokio-native-tls](https://crates.io/crates/tokio-native-tls).
 * `tokio-rustls-manual-roots`: Enables the additional functions in the `tokio` 
   module to implement TLS via [tokio-rustls](https://crates.io/crates/tokio-rustls)
   and uses native system certificates found with
   [rustls-manual-roots](https://github.com/rustls/rustls-manual-roots).
 * `tokio-rustls-native-certs`: Enables the additional functions in the `tokio` 
   module to implement TLS via [tokio-rustls](https://crates.io/crates/tokio-rustls)
   and uses native system certificates found with
   [rustls-native-certs](https://github.com/rustls/rustls-native-certs).
 * `tokio-rustls-platform-verifier`: Enables the additional functions in the `tokio` 
   module to implement TLS via [tokio-rustls](https://crates.io/crates/tokio-rustls)
   and uses native system certificates via the platform verifier found with
   [rustls-platform-verifier](https://github.com/rustls/rustls-platform-verifier).
 * `tokio-rustls-webpki-roots`: Enables the additional functions in the `tokio` 
   module to implement TLS via [tokio-rustls](https://crates.io/crates/tokio-rustls)
   and uses the certificates [webpki-roots](https://github.com/rustls/webpki-roots)
   provides.
 * `gio-runtime`: Enables the `gio` module, which provides integration with
   the [gio](https://gtk-rs.org) runtime.

### Deprecated features

These features depend on unmaintained crates / crates with security issues and are
**deprecated**.

 * `async-tls`: Use futures-rustls instead. Enables the `async_tls` module,
   which provides integration with the
   [async-tls](https://crates.io/crates/async-tls) TLS stack and can be used
   independently of any async runtime.
 * `async-std-runtime`: Use the smol runtime instead for a similar experience.
   Enables the `async_std` module, which provides integration with the
   [async-std](https://async.rs) runtime.
 * `async-native-tls`: Use the smol runtime with the `smol-native-tls` feature
   instead for a similar experience. Enables the additional functions in the
   `async_std` module to implement TLS via
   [async-native-tls](https://crates.io/crates/async-native-tls).

## Messages vs Streaming

WebSocket provides a message-oriented protocol, and this crate primarily
supports sending and receiving data in messages; protocols built on WebSocket
are allowed to make message boundaries semantically significant. However, some
users of WebSocket may want to treat the socket as a continuous stream of
bytes. If you know the other end does not place significance on message
boundaries, and you want to process a stream of bytes without regard to those
boundaries, you can use the `ByteReader` and `ByteWriter` types provided by
this crate.

## Is it performant?

In essence, `async-tungstenite` is a wrapper for `tungstenite`, so the performance is capped by the performance of `tungstenite`. `tungstenite`
has a decent performance (it has been used in production for real-time communication software, video conferencing, etc), but it's definitely
not the fastest WebSocket library in the world at the moment of writing this note.

We are aware of changes that both `tungstenite` and `tokio-tungstenite` require in order to make it on-par with slightly more performant libraries like `fastwebsockets`. In the course of past years we have merged several performance improvements submitted by the awesome community of Rust users who helped to improve the library! The more recent versions of `tokio-tungstenite` (`> 0.26.2`) are more performant and should be more on-par with `fastwebsockets`.

For a quick summary of the pending performance problems/improvements, see [the comment](https://github.com/snapview/tungstenite-rs/issues/352#issuecomment-1537488614).

## tokio-tungstenite

Originally this crate was created as a fork of
[tokio-tungstenite](https://github.com/snapview/tokio-tungstenite) and ported
to the traits of the [`futures`](https://crates.io/crates/futures) crate.
Integration into async-std, tokio and gio was added on top of that.