Struct axum::extract::WebSocketUpgrade
source · pub struct WebSocketUpgrade<F = DefaultOnFailedUpdgrade> { /* private fields */ }
ws
only.Expand description
Extractor for establishing WebSocket connections.
Note: This extractor requires the request method to be GET
so it should
always be used with get
. Requests with other methods will be
rejected.
See the module docs for an example.
Implementations§
source§impl<F> WebSocketUpgrade<F>
impl<F> WebSocketUpgrade<F>
sourcepub fn max_send_queue(self, max: usize) -> Self
pub fn max_send_queue(self, max: usize) -> Self
Set the size of the internal message send queue.
sourcepub fn max_message_size(self, max: usize) -> Self
pub fn max_message_size(self, max: usize) -> Self
Set the maximum message size (defaults to 64 megabytes)
sourcepub fn max_frame_size(self, max: usize) -> Self
pub fn max_frame_size(self, max: usize) -> Self
Set the maximum frame size (defaults to 16 megabytes)
sourcepub fn accept_unmasked_frames(self, accept: bool) -> Self
pub fn accept_unmasked_frames(self, accept: bool) -> Self
Allow server to accept unmasked frames (defaults to false)
sourcepub fn protocols<I>(self, protocols: I) -> Selfwhere
I: IntoIterator,
I::Item: Into<Cow<'static, str>>,
pub fn protocols<I>(self, protocols: I) -> Selfwhere
I: IntoIterator,
I::Item: Into<Cow<'static, str>>,
Set the known protocols.
If the protocol name specified by Sec-WebSocket-Protocol
header
to match any of them, the upgrade response will include Sec-WebSocket-Protocol
header and
return the protocol name.
The protocols should be listed in decreasing order of preference: if the client offers multiple protocols that the server could support, the server will pick the first one in this list.
Examples
use axum::{
extract::ws::{WebSocketUpgrade, WebSocket},
routing::get,
response::{IntoResponse, Response},
Router,
};
let app = Router::new().route("/ws", get(handler));
async fn handler(ws: WebSocketUpgrade) -> Response {
ws.protocols(["graphql-ws", "graphql-transport-ws"])
.on_upgrade(|socket| async {
// ...
})
}
sourcepub fn on_failed_upgrade<C>(self, callback: C) -> WebSocketUpgrade<C>where
C: OnFailedUpdgrade,
pub fn on_failed_upgrade<C>(self, callback: C) -> WebSocketUpgrade<C>where
C: OnFailedUpdgrade,
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 axum::{
extract::{WebSocketUpgrade},
response::Response,
};
async fn handler(ws: WebSocketUpgrade) -> Response {
ws.on_failed_upgrade(|error| {
report_error(error);
})
.on_upgrade(|socket| async { /* ... */ })
}
sourcepub fn on_upgrade<C, Fut>(self, callback: C) -> Responsewhere
C: FnOnce(WebSocket) -> Fut + Send + 'static,
Fut: Future<Output = ()> + Send + 'static,
F: OnFailedUpdgrade,
pub fn on_upgrade<C, Fut>(self, callback: C) -> Responsewhere
C: FnOnce(WebSocket) -> Fut + Send + 'static,
Fut: Future<Output = ()> + Send + 'static,
F: OnFailedUpdgrade,
Finalize upgrading the connection and call the provided callback with the stream.
When using WebSocketUpgrade
, the response produced by this method
should be returned from the handler. See the module docs for an
example.