WebSockets

Build WebSocket clients and standalone servers with tokio-tungstenite when you are not using Axum's built-in WebSocket support.

Recipe

Quick-reference recipe card - copy-paste ready.

use tokio_tungstenite::connect_async;
use futures_util::{SinkExt, StreamExt};
use tungstenite::Message;
 
let (ws, _) = connect_async("wss://echo.websocket.events").await?;
let (mut write, mut read) = ws.split();
write.send(Message::Text("hello".into())).await?;
if let Some(Ok(Message::Text(reply))) = read.next().await {
    println!("{reply}");
}

When to reach for this: Standalone WebSocket clients, custom servers, or protocols outside Axum.

Working Example

use futures_util::{SinkExt, StreamExt};
use tokio::net::{TcpListener, TcpStream};
use tokio_tungstenite::accept_async;
use tungstenite::Message;
 
async fn handle_connection(stream: TcpStream) -> Result<(), Box<dyn std::error::Error>> {
    let ws = accept_async(stream).await?;
    let (mut write, mut read) = ws.split();
    while let Some(msg) = read.next().await {
        match msg? {
            Message::Text(t) => write.send(Message::Text(format!("echo: {t}").into())).await?,
            Message::Close(_) => break,
            _ => {}
        }
    }
    Ok(())
}
 
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener = TcpListener::bind("127.0.0.1:9002").await?;
    while let Ok((stream, _)) = listener.accept().await {
        tokio::spawn(handle_connection(stream));
    }
    Ok(())
}

What this demonstrates:

• accept_async completes server-side handshake on TCP stream.
• Split sink/stream for concurrent read/write tasks if needed.
• Handle Text and Close messages explicitly.
• Client uses connect_async symmetrically.

Deep Dive

How It Works

• WebSocket starts as HTTP Upgrade request.
• Frames carry Text, Binary, Ping, Pong, Close opcodes.
• tokio-tungstenite integrates with Tokio async IO.

Axum vs tungstenite

Rust Notes

// Ping keepalive
write.send(Message::Ping(vec![].into())).await?;

Gotchas

• No TLS in accept_async - Plain TCP only; wrap with tokio-rustls for WSS. Fix: TLS terminator or rustls handshake before accept.
• Message size bombs - Default max message size can be exceeded maliciously. Fix: Configure max_message_size / max_frame_size.
• Half-open connections - Peer gone without Close frame. Fix: Periodic Ping and read timeout.
• Blocking on slow consumer - Unbounded channel to write loop. Fix: Bounded channel with drop policy.
• Origin not checked - CSWSH vulnerability on servers. Fix: Validate Origin header during handshake.

Alternatives

FAQs

Related

• WebSockets & SSE - Axum integration
• TLS with rustls - WSS encryption
• Low-Level Sockets - TCP beneath WS
• Authentication & Sessions - Securing upgrades
• Networking Best Practices - Real-time ops

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

NzA2MjAyfDg0Mm9pZ2N8b2kuc2VkaXVnZWRvYw==