Struct WebSocket

pub struct WebSocket { /* private fields */ }

A request guard identifying WebSocket requests. Converts into a Channel or MessageStream.

For example usage, see the crate docs.

Details

This is the entrypoint to the library. Every WebSocket response must initiate via the WebSocket request guard. The guard identifies valid WebSocket connection requests and, if the request is valid, succeeds to be converted into a streaming WebSocket response via Stream!, WebSocket::channel(), or WebSocket::stream(). The connection can be configured via WebSocket::config(); see Config for details on configuring a connection.

Forwarding

If the incoming request is not a valid WebSocket request, the guard forwards with a status of BadRequest. The guard never fails.

Implementations

impl WebSocket

pub fn config(self, config: Config) -> Self

Change the default connection configuration to config.

Example

#[get("/echo")]
fn echo_stream(ws: ws::WebSocket) -> ws::Stream!['static] {
    let ws = ws.config(ws::Config {
        max_send_queue: Some(5),
        ..Default::default()
    });

    ws::Stream! { ws =>
        for await message in ws {
            yield message?;
        }
    }
}

pub fn channel<'r, F>(self, handler: F) -> Channel<'r>

where F: FnOnce(DuplexStream) -> BoxFuture<'r, Result<()>> + Send + 'r,

Create a read/write channel to the client and call handler with it.

This method takes a FnOnce, handler, that consumes a read/write WebSocket channel, DuplexStream to the client. See DuplexStream for details on how to make use of the channel.

The handler must return a Boxed and Pinned future: calling Box::pin() with a future does just this as is the preferred mechanism to create a Box<Pin<Future>>. The future must return a Result<()>. The WebSocket connection is closed successfully if the future returns Ok and with an error if the future returns Err.

Lifetimes

The Channel may borrow from the request. If it does, the lifetime should be specified as something other than 'static. Otherwise, the 'static lifetime should be used.

Example

use rocket::futures::{SinkExt, StreamExt};

#[get("/hello/<name>")]
fn hello(ws: ws::WebSocket, name: &str) -> ws::Channel<'_> {
    ws.channel(move |mut stream| Box::pin(async move {
        let message = format!("Hello, {}!", name);
        let _ = stream.send(message.into()).await;
        Ok(())
    }))
}

#[get("/echo")]
fn echo(ws: ws::WebSocket) -> ws::Channel<'static> {
    ws.channel(move |mut stream| Box::pin(async move {
        while let Some(message) = stream.next().await {
            let _ = stream.send(message?).await;
        }

        Ok(())
    }))
}

pub fn stream<'r, F, S>(self, stream: F) -> MessageStream<'r, S>

where F: FnOnce(SplitStream<DuplexStream>) -> S + Send + 'r, S: Stream<Item = Result<Message>> + Send + 'r,

Create a stream that consumes client Messages and emits its own.

This method takes a FnOnce stream that consumes a read-only stream and returns a stream of Messages. While the returned stream can be constructed in any manner, the Stream! macro is the preferred method. In any case, the stream must be Send.

The returned stream must emit items of type Result<Message>. Items that are Ok(Message) are sent to the client while items of type Err(Error) result in the connection being closed and the remainder of the stream discarded.

Example

// Use `Stream!`, which internally calls `WebSocket::stream()`.
#[get("/echo?stream")]
fn echo_stream(ws: ws::WebSocket) -> ws::Stream!['static] {
    ws::Stream! { ws =>
        for await message in ws {
            yield message?;
        }
    }
}

// Use a raw stream.
#[get("/echo?compose")]
fn echo_compose(ws: ws::WebSocket) -> ws::Stream!['static] {
    ws.stream(|io| io)
}

pub fn accept_key(&self) -> &str

Returns the server’s fully computed and encoded WebSocket handshake accept key.

The server takes the value of the Sec-WebSocket-Key sent in the handshake request, appends 258EAFA5-E914-47DA-95CA-C5AB0DC85B11, SHA-1 of the new value, and is then base64 encoded.

– Sec-WebSocket-Accept

This is the value returned via the Sec-WebSocket-Accept header during the acceptance response.

Example

#[get("/echo")]
fn echo_stream(ws: ws::WebSocket) -> ws::Stream!['static] {
    let accept_key = ws.accept_key();
    ws.stream(|io| io)
}

Trait Implementations

impl<'r> FromRequest<'r> for WebSocket

type Error = Infallible

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>( req: &'r Request<'life0>, ) -> Pin<Box<dyn Future<Output = Outcome<Self, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata.