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
5,662 downloads per month
Used in 8 crates
(6 directly)
155KB
2.5K
SLoC
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-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
fromhttp
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 thenightly
feature when using a nightly compiler will also enable AVX512 accelerated maskingclient
enables a tiny client implementationserver
enables a tiny server implementation
TLS is supported via any of the following feature flags:
native-tls
for atokio-native-tls
backed implementationrustls-webpki-roots
for atokio-rustls
backed implementation withwebpki-roots
rustls-native-roots
for atokio-rustls
backed implementation withrustls-native-certs
rustls-platform-verifier
for atokio-rustls
backed implementation withrustls-platform-verifier
rustls-bring-your-own-connector
for atokio-rustls
backed implementation that requires you to create your ownConnector::Rustls
- theConnector::new
method will return a plain connector
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
oraws_lc_rs
are used if thering
oraws_lc_rs
features are enabled (recommended whenrustls
is used)- The
openssl
feature will useopenssl
, usually preferred on most Linux/BSD systems withnative-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 aPRNG
getrandom
can be used as a cryptographically secure RNGrand
can be used as an alternative tofastrand
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