Question: Can Websocket Handlers Receive Ping/Pong/Close Messages?

[ssanderson]

👋 Hi! Thanks for your work on Axum. I have a question about a documentation ambiguity.

I'm testing out using Axum for an application that primarily communicates with clients via Websockets. So far things are working well, but one thing I'm a bit confused about is which of the Message enum variants are possible to be received in a handler that obtains a websocket via WebSocketUpgrade.on_upgrade.

In particular, I currently have a function that tries to read the next message of a websocket and parse it into an app-specific structure. That function looks like:

    async fn read_from_websocket<'a, T: serde::de::DeserializeOwned>(
        ws: &mut SplitStream<WebSocket>,
    ) -> Result<T, WebsocketReadError> {
        loop {
            match ws.next().await {
                Some(Ok(Message::Text(s))) => {
                    return serde_json::from_str(&s).map_err(Into::into);
                }
                Some(Ok(Message::Binary(_))) => {
                    return Err(WebsocketReadError::UnexpectedBinaryMessage);
                }
                Some(Ok(msg)) => {
                    // XXX: Do we need to handle non-Text/Binary messages?[
                    continue;
                }
                Some(Err(e)) => {
                    return Err(WebsocketReadError::from(e));
                }
                None => {
                    return Err(WebsocketReadError::Closed);
                }
            }
        }
    }

At the points in my protocol where I'm calling this, I expect the next received message to be a regular text message containing some json that I can parse into my type. If I get an unexpected message type I want to return an error indicating what went wrong. One issue I'm having it is that it's unclear to me whether I should expect to receive Ping / Pong / Close messages in my handler. The documentation on Message::Ping says:

    /// Ping messages will be automatically responded to by the server, so you do not have to worry
    /// about dealing with them yourself.

but it wasn't clear to me if this means that Axum will filter out Ping messages and handle them before they even get to me, or if it just means that Axum will queue Pongs before forwarding to me, but I'm still responsible for ignoring Pong messages in my application. I have similar questions for whether my application needs to explicitly ignore Pong/Close messages.

Thanks in advance for your time!

[davidpdrsn]

axum uses tungstenite internally to do all the websocket stuff and tungstenite will automatically respond to pings. See snapview/tokio-tungstenite#88. So you just ignore them.

[ssanderson]

Gotcha. Just to make sure I understand, it sounds like this means my application should expect to see messages when I pull from the websocket stream, but the expected behavior is that my application should ignore them and keep pulling until I get a Text or Binary message?

[davidpdrsn]

Yep!

[ssanderson]

@davidpdrsn would you be interested in a small PR to clarify this in the documentation for Message? On my initial reading of the current docs, it wasn't totally to me whether "you do not have to worry about dealing with them" meant "your application will not receive this message type" or "your application will receive this message type, but you should ignore them unless you're doing something fancy".

[davidpdrsn]

Sure!

I think we should document it along the lines of "your application will receive this message type, but you should ignore them unless you're doing something fancy". I suppose there are still ways to receive them if users try hard enough 😅