rust 48 lines · 8 steps

How an Axum WebSocket echo server works

An Axum handler upgrades an HTTP request to a WebSocket, then loops over incoming frames and echoes them back to the client.

Explained by highlit
Axum Intermediate websockets async streams protocol handling connection lifecycle
1use axum::{
2 extract::ws::{Message, WebSocket, WebSocketUpgrade},
3 response::IntoResponse,
4};
5use futures::{sink::SinkExt, stream::StreamExt};
6use std::net::SocketAddr;
7use tracing::{info, warn};
8 
9pub async fn echo_handler(
10 ws: WebSocketUpgrade,
11 axum::extract::ConnectInfo(addr): axum::extract::ConnectInfo<SocketAddr>,
12) -> impl IntoResponse {
13 ws.on_upgrade(move |socket| handle_socket(socket, addr))
14}
15 
16async fn handle_socket(socket: WebSocket, addr: SocketAddr) {
17 let (mut sender, mut receiver) = socket.split();
18 
19 while let Some(msg) = receiver.next().await {
20 let msg = match msg {
21 Ok(msg) => msg,
22 Err(err) => {
23 warn!(%addr, %err, "websocket receive error");
24 break;
25 }
26 };
27 
28 match msg {
29 Message::Text(text) => {
30 if sender.send(Message::Text(text)).await.is_err() {
31 break;
32 }
33 }
34 Message::Binary(bytes) => {
35 if sender.send(Message::Binary(bytes)).await.is_err() {
36 break;
37 }
38 }
39 Message::Ping(payload) => {
40 let _ = sender.send(Message::Pong(payload)).await;
41 }
42 Message::Close(_) => break,
43 _ => {}
44 }
45 }
46 
47 info!(%addr, "websocket connection closed");
48}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Axum's WebSocketUpgrade defers the protocol switch until you hand it an async task via on_upgrade.
  2. 2Splitting a socket into a sender and receiver lets you read and write the same connection independently.
  3. 3Explicitly matching each WebSocket frame type keeps control frames like Ping and Close handled correctly, not just data.

Related explainers

rust 
#[derive(Debug, Clone, PartialEq)]
pub enum Token {
    Number(f64),
    Plus,

How a tokenizer turns text into tokens

lexing enums iterators
Intermediate 8 steps
rust 
use axum::{
    extract::{FromRequestParts, Host},
    http::{request::Parts, StatusCode},
};

Multi-tenant DB routing in Axum extractors

multi-tenancy extractors connection-pooling
Advanced 8 steps
rust 
use std::{collections::HashSet, sync::Arc};
 
use axum::{
    body::Body,

Feature-flag middleware in Axum

middleware async shared-state
Advanced 7 steps
rust 
pub fn format_size(bytes: u64) -> String {
    const UNITS: [&str; 7] = ["B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB"];
 
    if bytes < 1024 {

Formatting byte counts as human-readable sizes

bit-manipulation formatting unit-conversion
Intermediate 5 steps
rust 
use base64::engine::general_purpose::{STANDARD, URL_SAFE_NO_PAD};
use base64::{DecodeError, Engine};
 
pub fn encode_standard(data: &[u8]) -> String {

Base64 encode and decode in Rust

base64 encoding error-handling
Beginner 7 steps
rust 
use std::collections::HashMap;
 
#[derive(Debug)]
pub struct RequestHead {

Parsing an HTTP request head in Rust

parsing error-handling iterators
Intermediate 9 steps

Share this explainer

Here's the card — post it anywhere.

How an Axum WebSocket echo server works — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code