Struct ratchet_rs::WebSocket

pub struct WebSocket<S, E> { /* private fields */ }

An upgraded WebSocket stream.

This is created after a connection has been upgraded to speak the WebSocket protocol by using the accept, accept_with, subscribe and subscribe_with functions or by using WebSocket::from_upgraded with an already upgraded stream.

Example

let stream = TcpStream::connect("127.0.0.1:9001").await?;
let upgraded = subscribe(WebSocketConfig::default(), stream, "ws://127.0.0.1/hello").await?;
let UpgradedClient { mut  websocket, .. } = upgraded;

let mut buf = BytesMut::new();

loop {
    match websocket.read(&mut buf).await? {
        Message::Text => {
            websocket.write(&mut buf, PayloadType::Text).await?;
            buf.clear();
        }
        Message::Binary => {
            websocket.write(&mut buf, PayloadType::Binary).await?;
            buf.clear();
        }
        Message::Ping(_) | Message::Pong(_) => {}
        Message::Close(_) => break Ok(()),
    }
}

Implementations

impl<S, E> WebSocket<S, E> where
    S: WebSocketStream,
    E: Extension, 

pub fn from_upgraded(
    config: WebSocketConfig,
    stream: S,
    extension: NegotiatedExtension<E>,
    read_buffer: BytesMut,
    role: Role
) -> WebSocket<S, E>

Initialise a new WebSocket from a stream that has already executed a handshake.

Arguments

config - The configuration to initialise the WebSocket with. stream - The stream that the handshake was executed on. extension - A negotiated extension that will be used for the session. read_buffer - The read buffer which will be used for the session. This may contain any unread data received after performing the handshake that was not required. role - The role that this WebSocket will take.

pub fn role(&self) -> Role

Returns the role of this WebSocket.

pub async fn read(
    &mut self,
    read_buffer: &mut BytesMut
) -> Result<Message, Error>

Attempt to read some data from the WebSocket. Returning either the type of the message received or the error that was produced.

Errors

In the event that an error is produced, an attempt is made to cleanly close the connection by sending a close frame to the peer. If this attempt fails, then the connection is abruptly closed and the cause of the error is returned.

In the event that an error is produced the contents of read_buffer must be considered to be dirty; unless the error indicates a clean closure.

Control frames

Ratchet transparently handles ping messages received from the peer in read operations by returning a pong frame and this function will return Message::Pong if one has been received. As per RFC6455 these may be interleaved between data frames. In the event of one being received while reading a continuation, this function will then yield Message::Ping and the read_buffer will contain the data received up to that point. The callee must ensure that the contents of read_buffer are not then modified before calling read again.

pub async fn write_text<I>(&mut self, data: I) -> Result<(), Error> where
    I: AsRef<str>, 

Constructs a new text WebSocket message with a payload of data.

pub async fn write_binary<I>(&mut self, data: I) -> Result<(), Error> where
    I: AsRef<[u8]>, 

Constructs a new binary WebSocket message with a payload of data.

pub async fn write_ping<I>(&mut self, data: I) -> Result<(), Error> where
    I: AsRef<[u8]>, 

Constructs a new ping WebSocket message with a payload of data.

pub async fn write_pong<I>(&mut self, data: I) -> Result<(), Error> where
    I: AsRef<[u8]>, 

Constructs a new pong WebSocket message with a payload of data.

pub async fn write<A>(
    &mut self,
    buf: A,
    message_type: PayloadType
) -> Result<(), Error> where
    A: AsRef<[u8]>, 

Constructs a new WebSocket message of message_type and with a payload of `buf.

pub async fn close(&mut self, reason: CloseReason) -> Result<(), Error>

Close this WebSocket with the reason provided.

pub async fn write_fragmented<A>(
    &mut self,
    buf: A,
    message_type: MessageType,
    fragment_size: usize
) -> Result<(), Error> where
    A: AsRef<[u8]>, 

Constructs a new WebSocket message of message_type and with a payload of buf_ref and chunked by fragment_size. If the length of the buffer is less than the chunk size then only a single message is sent.

pub fn is_closed(&self) -> bool

Returns whether this WebSocket is closed.

pub fn is_active(&self) -> bool

Returns whether this WebSocket is closing or closed.

Trait Implementations

impl<S, E> Debug for WebSocket<S, E> where
    S: Debug,
    E: Debug, 

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

Formats the value using the given formatter.