Struct ratchet_core::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.

Cancel safety

This function is not cancellation safe. If the future is dropped before it has completed then both buf and the connection state are undefined. It may not be possible to recover the connection due the read operation partially completing and the state has been lost.

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

where I: AsRef<str>,

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

Cancel safety

This function is not cancellation safe. If the future is dropped before it has completed then the connection state is undefined. It may not be possible to recover the connection due the write operation having written only part of the frame and the state of the write operation has been lost.

pub async fn write_binary<I>(&mut self, data: I) -> Result<(), Error>

where I: AsRef<[u8]>,

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

Cancel safety

This function is not cancellation safe. If the future is dropped before it has completed then the connection state is undefined. It may not be possible to recover the connection due the write operation having written only part of the frame and the state of the write operation has been lost.

pub async fn write_ping<I>(&mut self, data: I) -> Result<(), Error>

where I: AsRef<[u8]>,

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

Cancel safety

This function is not cancellation safe. If the future is dropped before it has completed then the connection state is undefined. It may not be possible to recover the connection due the write operation having written only part of the control frame and the state of the write operation has been lost.

pub async fn write_pong<I>(&mut self, data: I) -> Result<(), Error>

where I: AsRef<[u8]>,

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

Cancel safety

This function is not cancellation safe. If the future is dropped before it has completed then the connection state is undefined. It may not be possible to recover the connection due the write operation having written only part of the control frame and the state of the write operation has been lost.

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

where A: AsRef<[u8]>,

Sends a new WebSocket message of message_type and with a payload of buf.

Cancel safety

This function is not cancellation safe. If the future is dropped before it has completed then both buf and the connection state are undefined. It may not be possible to recover the connection due the read operation partially completing and the state has been lost.

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

Close this WebSocket with the reason provided.

If the WebSocket is already closed then Ok(()) is returned.

Cancel safety

This function is not cancellation safe. If the future is dropped before it has completed then the connection state is undefined. It may not be possible to recover the connection due the write operation having written only part of the close frame and the state of the write operation has been lost.

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 and chunked by fragment_size. If the length of the buffer is less than the chunk size then only a single message is sent.

Cancel safety

This function is not cancellation safe. If the future is dropped before it has completed then the connection state is undefined. It may not be possible to recover the connection due the write operation having written only part of the buffer and the state of the write operation has been lost.

pub async fn flush(&mut self) -> Result<(), Error>

Flushes the WebSocket’s output stream, ensuring that all intermediately buffered contents reach their destination.

Errors

It is considered an error if not all bytes could be written due to I/O errors or EOF being reached.

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: Debug, E: Debug> Debug for WebSocket<S, E>

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

Formats the value using the given formatter.