Axum WebSockets

Overview

A WebSocket endpoint in Axum is an ordinary handler that takes the WebSocketUpgrade extractor, returns ws.on_upgrade(callback), and runs the live connection inside the callback. The HTTP 101 Switching Protocols response is returned immediately; the callback owns the connection for its entire lifetime.

Two facts dominate correct WebSocket code:

1. A single WebSocket cannot be borrowed mutably by two tasks at once, so it cannot recv and send concurrently as-is. Any server that pushes messages on its own schedule MUST split the socket.
2. Axum 0.8 changed the Message payload types from owned String / Vec<u8> to the reference-counted Utf8Bytes / Bytes. Code carried over from 0.7 without change fails to compile.

The entire axum::extract::ws module is gated behind the ws cargo feature.