tungstenite

tungstenite is a low-level RFC 6455 WebSocket implementation for Rust that works over any Read + Write stream rather than committing to a specific async runtime. It handles the handshake, framing, masking, and close-handshake logic itself and exposes a synchronous, blocking-style WebSocket<Stream> type that callers drive by reading and writing messages directly.

Because it makes no assumptions about I/O or concurrency model, tungstenite is most often consumed indirectly through async wrappers such as tokio-tungstenite (Tokio) or async-tungstenite (async-std/smol), which adapt its synchronous core to non-blocking async/await APIs. This split — protocol logic in tungstenite, runtime integration in the wrapper crates — is why it underpins a large share of the WebSocket traffic in the Rust ecosystem.

What You Get

• A complete RFC 6455 WebSocket implementation: handshake, framing, masking, fragmentation, ping/pong, close codes
• Runtime-agnostic design that works over any std::io::Read + Write stream, blocking or wrapped for async
• Optional TLS support via native-tls or rustls (with native-roots or webpki-roots variants)
• Client and server handshake helpers built on the http crate’s Request/Response types
• A message-oriented API (Message::Text/Binary/Ping/Pong/Close) instead of raw frame manipulation

Common Use Cases

• Building an async WebSocket client or server on Tokio via the tokio-tungstenite wrapper
• Building an async-std or smol WebSocket integration via async-tungstenite
• Implementing a custom transport (e.g. over a non-standard stream type) where an async-runtime-specific WebSocket crate doesn’t fit
• Writing a minimal, dependency-light WebSocket client for embedded or constrained environments using blocking I/O

Under The Hood

Architecture - The crate is organized around a protocol/ module implementing the WebSocket state machine and frame codec, a handshake/ module implementing the HTTP Upgrade handshake for both client and server roles, and a top-level WebSocket<Stream> struct in lib.rs that ties buffering (buffer.rs), the stream abstraction (stream.rs), and TLS (tls.rs) together into a single read/write-message interface.

Tech Stack - Pure Rust with a deliberately small dependency set: http/httparse for handshake parsing, sha1/data-encoding for the handshake’s Sec-WebSocket-Accept computation, and optional native-tls-crate or rustls/rustls-pki-types/webpki-roots/rustls-native-certs behind feature flags, so consumers only pull in the TLS stack they actually need.

Code Quality - The tests/ directory covers connection-reset handling, handshake edge cases, write-after-close semantics, and TLS-disabled behavior, and the repo includes an autobahn/ directory wired to the Autobahn WebSocket Testsuite (the standard protocol-conformance test suite) plus a fuzz/ target for handshake/frame fuzzing, which is a strong quality signal for a wire-protocol implementation.

API Design - The core loop is simple: construct a WebSocket from a stream via client()/accept(), then call read()/send() with a Message enum. This synchronous, blocking-shaped API is intentionally minimal at the cost of not being directly usable from async code — that gap is what the tokio-tungstenite/async-tungstenite wrapper crates exist to close, which means new users often need to learn which wrapper crate to reach for rather than using tungstenite directly.