tungstenite

Tungstenite distinguishes between the two sides of a WebSocket connection using the Role enum:

• Role::Client: The side that initiates the connection. Clients must mask frames sent to the server according to RFC 6455. Tungstenite handles this masking automatically.
• Role::Server: The side that accepts connections. Servers should generally not receive masked frames (unless accept_unmasked_frames is enabled in WebSocketConfig).

Connection Lifecycle

• Active: The connection is open and can both read and write.
• Closing: A close handshake has been initiated (either by us or the peer). In this state, can_read() may still be true as the peer might send final data before acknowledging the close.
• Terminated: The connection is closed and cannot be used further. Attempting to use a terminated connection will result in Error::AlreadyClosed or Error::ConnectionClosed.

You can build a synchronous WebSocket server by using tungstenite::accept to upgrade a standard TcpStream. In the example below, the server listens on 127.0.0.1:9001, accepts incoming connections, and echoes back any received binary or text messages while ignoring control frames like ping/pong.

use std::net::TcpListener;
use std::thread::spawn;
use tungstenite::accept;

/// A WebSocket echo server
fn main () {
    let server = TcpListener::bind("127.0.0.1:9001").unwrap();
    for stream in server.incoming() {
        spawn (move || {
            let mut websocket = accept(stream.unwrap()).unwrap();
            loop {
                let msg = websocket.read().unwrap();

                // We do not want to send back ping/pong messages.
                if msg.is_binary() || msg.is_text() {
                    websocket.send(msg).unwrap();
                }
            }
        });
    }
}

Use WebSocketConfig to tune the performance and security of your WebSocket connection. You can adjust buffer sizes, message limits, and protocol compliance settings using a builder-like pattern.

Key Configuration Options

• read_buffer_size: The capacity of the eagerly allocated read buffer. Use larger values (e.g., 128 KiB) for high read loads, or smaller values (e.g., 4 KiB) to save memory in high-concurrency scenarios. Default is 128 KiB.
• write_buffer_size: The target minimum size of the write buffer before data is flushed to the underlying stream. Setting this to 0 causes eager writes. Default is 128 KiB.
• max_write_buffer_size: The maximum size the write buffer can reach. This provides backpressure if writes to the underlying stream are failing. Must be greater than write_buffer_size. Default is usize::MAX.
• max_message_size: The maximum size of an incoming message. Set to None for no limit. Default is 64 MiB.
• max_frame_size: The maximum size of a single incoming frame payload. Set to None for no limit. Default is 16 MiB.
• accept_unmasked_frames: If true, the server will accept unmasked frames from clients (violating RFC 6455). Default is false.

# use tungstenite::protocol::WebSocketConfig;
let conf = WebSocketConfig::default()
    .read_buffer_size(256 * 1024)
    .write_buffer_size(256 * 1024);

The Error enum is the central error type for all Tungstenite library calls. When performing WebSocket operations, you should handle this enum to distinguish between normal connection closures, protocol violations, and IO issues.

Key variants to watch for:

• ConnectionClosed: The WebSocket connection closed normally. This is not a failure; it means the close handshake finished. It is safe to drop the underlying connection.
• AlreadyClosed: You attempted to read or write to a connection that has already received a ConnectionClosed signal. This usually indicates a logic error in your application.
• Io: Underlying input/output errors. Generally considered fatal unless they are WouldBlock errors.
• Protocol: A violation of the WebSocket protocol.
• Capacity: The message size exceeds the configured limit or buffer capacity is exhausted.
• Utf8: Errors related to UTF-8 encoding/decoding.
• Url: Errors related to the connection URL.
• Tls: Errors occurring during the TLS handshake or connection.