Как реализовать WebSocket-соединения в Actix-web?

WebSocket-соединения в Actix-web

Actix-web предоставляет встроенную поддержку WebSocket через модуль actix_web_actors::ws (если используется actix-акторная модель) либо через низкоуровневый actix_web::web::Payload с ручным апгрейдом. Рассмотрим оба подхода.

Подход 1: через actix-акторы

Добавьте зависимости в Cargo.toml:

[dependencies]
actix-web = "4"
actix-web-actors = "4"
actix = "0.13"

Определите актор, реализующий трейт Actor и обработчик StreamHandler<Result<ws::Message, ws::ProtocolError>>:

use actix::{Actor, StreamHandler};
use actix_web::{web, App, HttpRequest, HttpResponse, HttpServer, Error};
use actix_web_actors::ws;

struct MyWs;

impl Actor for MyWs {
    type Context = ws::WebsocketContext<Self>;
}

impl StreamHandler<Result<ws::Message, ws::ProtocolError>> for MyWs {
    fn handle(&mut self, msg: Result<ws::Message, ws::ProtocolError>, ctx: &mut Self::Context) {
        match msg {
            Ok(ws::Message::Text(text)) => {
                // эхо обратно клиенту
                ctx.text(format!("echo: {}", text));
            }
            Ok(ws::Message::Binary(bin)) => ctx.binary(bin),
            Ok(ws::Message::Ping(msg)) => ctx.pong(&msg),
            Ok(ws::Message::Close(reason)) => {
                ctx.close(reason);
                ctx.stop();
            }
            _ => {}
        }
    }
}

async fn ws_index(
    req: HttpRequest,
    stream: web::Payload,
) -> Result<HttpResponse, Error> {
    ws::start(MyWs {}, &req, stream)
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .route("/ws", web::get().to(ws_index))
    })
    .bind(("127.0.0.1", 8080))?
    .run()
    .await
}

Подход 2: через tokio-tungstenite без акторов

Если вы не хотите использовать actix-акторную модель, можно применить крейт actix-ws (без акторов), который предоставляет более простой API поверх Payload:

[dependencies]
actix-web = "4"
actix-ws = "0.3"
tokio = { version = "1", features = ["rt-multi-thread"] }

use actix_web::{web, App, HttpRequest, HttpResponse, HttpServer, Error};
use actix_ws::Message;

async fn ws_handler(
    req: HttpRequest,
    body: web::Payload,
) -> Result<HttpResponse, Error> {
    let (response, mut session, mut stream) = actix_ws::handle(&req, body)?;

    actix_web::rt::spawn(async move {
        while let Some(Ok(msg)) = stream.recv().await {
            match msg {
                Message::Text(text) => {
                    let _ = session.text(format!("got: {}", text)).await;
                }
                Message::Close(reason) => {
                    let _ = session.close(reason).await;
                    break;
                }
                _ => {}
            }
        }
    });

    Ok(response)
}

Отправка сообщений из других задач

При использовании акторной модели можно сохранять Addr<MyWs> и посылать акторам произвольные сообщения через addr.do_send(MyMessage { ... }). При использовании actix-ws клонируйте session (он реализует Clone) и передавайте в канал.

Подводные камни

• Забыть обработать ws::Message::Ping — браузеры отключаются при отсутствии Pong в течение таймаута (по умолчанию 10 с).
• Не вызывать ctx.stop() при получении Close — актор остаётся «живым» и утечка памяти накапливается.
• Использовать блокирующие операции внутри актора — всё, что блокирует поток актора, замораживает обработку сообщений; используйте ctx.spawn(async { ... }.into_actor(self)).
• Не устанавливать heartbeat: без периодического Ping сервер не обнаруживает разорванные соединения (zombie connections).
• Создавать по одному актору на запрос без ограничения числа соединений — приводит к исчерпанию ресурсов при высокой нагрузке.
• При использовании actix-ws забыть вызвать stream.recv().await в цикле — иначе данные не читаются и буфер забивается.
• Ошибочно предполагать, что WebSocket работает через HTTP/2 — Actix-web поддерживает WS только поверх HTTP/1.1.
• Не задавать максимальный размер кадра: по умолчанию ws::start принимает очень большие фреймы, что открывает вектор DoS-атаки.

• Отвечать определением без production-сценария.
• Не называть runtime boundary, security boundary или failure mode.
• Игнорировать версию API, observability и тестовую проверку.

• Объясняет механизм своими словами и без выдуманных API.
• Называет реальные риски, диагностику и критерий корректности.
• Связывает ответ с текущей документацией и миграционными ограничениями.