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>

source

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.

source

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.

source

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

Set the maximum message size (defaults to 64 megabytes)

source

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

Set the maximum frame size (defaults to 16 megabytes)

source

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

Allow server to accept unmasked frames (defaults to false)

source

pub fn protocols<I>(self, protocols: I) -> Self
where 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 {
            // ...
        })
}
source

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 { /* ... */ })
}
source

pub fn on_upgrade<C, Fut>(self, callback: C) -> Response
where C: FnOnce(WebSocket) -> Fut + Send + 'static, Fut: Future<Output = ()> + Send + 'static, F: OnFailedUpgrade,

Finalize upgrading the connection and call the provided callback with the stream.

Trait Implementations§

source§

impl<F> Debug for WebSocketUpgrade<F>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<S> FromRequestParts<S> for WebSocketUpgrade<DefaultOnFailedUpgrade>
where S: Send + Sync,

§

type Rejection = WebSocketUpgradeRejection

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.
source§

fn from_request_parts<'life0, 'life1, 'async_trait>( parts: &'life0 mut Parts, _state: &'life1 S, ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Rejection>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Perform the extraction.

Auto Trait Implementations§

§

impl<F = DefaultOnFailedUpgrade> !Freeze for WebSocketUpgrade<F>

§

impl<F> RefUnwindSafe for WebSocketUpgrade<F>
where F: RefUnwindSafe,

§

impl<F> Send for WebSocketUpgrade<F>
where F: Send,

§

impl<F> Sync for WebSocketUpgrade<F>
where F: Sync,

§

impl<F> Unpin for WebSocketUpgrade<F>
where F: Unpin,

§

impl<F> UnwindSafe for WebSocketUpgrade<F>
where F: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<S, T> FromRequest<S, ViaParts> for T
where S: Send + Sync, T: FromRequestParts<S>,

§

type Rejection = <T as FromRequestParts<S>>::Rejection

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.
source§

fn from_request<'life0, 'async_trait>( req: Request<Body>, state: &'life0 S, ) -> Pin<Box<dyn Future<Output = Result<T, <T as FromRequest<S, ViaParts>>::Rejection>> + Send + 'async_trait>>
where 'life0: 'async_trait, T: 'async_trait,

Perform the extraction.
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more