Struct axum::extract::WebSocketUpgrade
source · pub struct WebSocketUpgrade<F = DefaultOnFailedUpgrade> { /* private fields */ }
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 write_buffer_size(self, size: usize) -> Self
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.
sourcepub fn max_write_buffer_size(self, max: usize) -> Self
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.
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) -> Self
pub fn protocols<I>(self, protocols: I) -> Self
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: OnFailedUpgrade,
pub fn on_failed_upgrade<C>(self, callback: C) -> WebSocketUpgrade<C>where
C: 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 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) -> Response
pub fn on_upgrade<C, Fut>(self, callback: C) -> Response
Finalize upgrading the connection and call the provided callback with the stream.