Struct WebSocketUpgrade 

pub struct WebSocketUpgrade<F = DefaultOnFailedUpgrade> { /* private fields */ }

Available on crate features server and ws only.

Handle request for establishing WebSocket connection.

WebSocketUpgrade can be passed as an argument to a handler, which will be called if the http connection making the request can be upgraded to a websocket connection.

WebSocketUpgrade must be used with WebSocketUpgrade::on_upgrade and a websocket handler, WebSocketUpgrade::on_upgrade will return a Response for the client and the connection will then be upgraded later.

Example

use volo_http::{response::Response, server::utils::ws::WebSocketUpgrade};

fn ws_handler(ws: WebSocketUpgrade) -> Response {
    ws.on_upgrade(|socket| async { todo!() })
}

Implementations

impl<F> WebSocketUpgrade<F>

pub fn write_buffer_size(self, size: usize) -> Self

The target minimum size of the write buffer to reach before writing the data to the underlying stream.

The default value is 128 KiB.

If set to 0 each message will be eagerly written to the underlying stream. It is often more optimal to allow them to buffer a little, hence the default value.

Note: flush will always fully write the buffer regardless.

pub fn max_write_buffer_size(self, max: usize) -> Self

The max size of the write buffer in bytes. Setting this can provide backpressure in the case the write buffer is filling up due to write errors.

The default value is unlimited.

Note: The write buffer only builds up past write_buffer_size when writes to the underlying stream are failing. So the write buffer can not fill up if you are not observing write errors even if not flushing.

Note: Should always be at least write_buffer_size + 1 message and probably a little more depending on error handling strategy.

pub fn max_message_size(self, max: Option<usize>) -> Self

The maximum size of an incoming message.

None means no size limit.

The default value is 64 MiB, which should be reasonably big for all normal use-cases but small enough to prevent memory eating by a malicious user.

pub fn max_frame_size(self, max: Option<usize>) -> Self

The maximum size of a single incoming message frame.

None means no size limit.

The limit is for frame payload NOT including the frame header.

The default value is 16 MiB, which should be reasonably big for all normal use-cases but small enough to prevent memory eating by a malicious user.

pub fn accept_unmasked_frames(self, accept: bool) -> Self

If server to accept unmasked frames.

When set to true, the server will accept and handle unmasked frames from the client.

According to the RFC 6455, the server must close the connection to the client in such cases, however it seems like there are some popular libraries that are sending unmasked frames, ignoring the RFC.

By default this option is set to false, i.e. according to RFC 6455.

pub fn protocols<I>(self, protocols: I) -> Self

where I: IntoIterator, I::Item: Into<Cow<'static, str>>,

Set available protocols for Sec-WebSocket-Protocol.

If the protocol in Sec-WebSocket-Protocol matches any protocol, the upgrade response will insert Sec-WebSocket-Protocol and WebSocket will contain the protocol name.

Note that if the client offers multiple protocols that the server supports, the server will pick the first one in the list.

pub fn on_failed_upgrade<F2>(self, callback: F2) -> WebSocketUpgrade<F2>

where F2: OnFailedUpgrade,

Provide a callback to call if upgrading the connection fails.

The connection upgrade is performed in a background task. If that fails this callback will be called.

By default, any errors will be silently ignored.

Example

use volo_http::{
    response::Response,
    server::{
        route::{Router, get},
        utils::ws::{WebSocket, WebSocketUpgrade},
    },
};

async fn ws_handler(ws: WebSocketUpgrade) -> Response {
    ws.on_failed_upgrade(|err| eprintln!("Failed to upgrade connection, err: {err}"))
        .on_upgrade(|socket| async { todo!() })
}

let router: Router = Router::new().route("/ws", get(ws_handler));

pub fn on_upgrade<C, Fut>(self, callback: C) -> Response

where C: FnOnce(WebSocket) -> Fut + Send + 'static, Fut: Future<Output = ()> + Send, F: OnFailedUpgrade + Send + 'static,

Finalize upgrading the connection and call the provided callback

If request protocol is matched, it will use callback to handle the connection stream data.

The callback function should be an async function with WebSocket as parameter.

Example

use futures_util::{sink::SinkExt, stream::StreamExt};
use volo_http::{
    response::Response,
    server::{
        route::{Router, get},
        utils::ws::{WebSocket, WebSocketUpgrade},
    },
};

async fn ws_handler(ws: WebSocketUpgrade) -> Response {
    ws.on_upgrade(|mut socket| async move {
        while let Some(Ok(msg)) = socket.next().await {
            if msg.is_ping() || msg.is_pong() {
                continue;
            }
            if socket.send(msg).await.is_err() {
                break;
            }
        }
    })
}

let router: Router = Router::new().route("/ws", get(ws_handler));

Trait Implementations

impl FromContext for WebSocketUpgrade<DefaultOnFailedUpgrade>

type Rejection = WebSocketUpgradeRejectionError

If the extractor fails, it will return this Rejection type.

async fn from_context( _: &mut ServerContext, parts: &mut Parts, ) -> Result<Self, Self::Rejection>

Extract the type from context.