Struct ws_stream_tungstenite::WsStream

pub struct WsStream<S>
where
    S: AsyncRead + AsyncWrite + Send + Unpin,
{ /* private fields */ }

Takes a WebSocketStream and implements futures 0.3 AsyncRead/AsyncWrite/AsyncBufRead.

Will always create an entire Websocket message from every write. Tungstenite buffers messages up to write_buffer_size in their tungstenite::protocol::WebSocketConfig. If you want small messages to be sent out, either make sure this buffer is small enough or flush the writer.

On the other hand the max_write_buffer_size from tokio is the maximum size we can send in one go, otherwise tungstenite returns an error. Our AsyncWrite implementation never sends data that exceeds this buffer or max_message_size.

However you still must respect the max_message_size of the receiving end.

Errors

Errors returned directly are generally io errors from the underlying stream. Only fatal errors are returned in band, so consider them fatal and drop the WsStream object.

Other errors are returned out of band through pharos:

On reading, eg. AsyncRead::poll_read:

• WsErr::Protocol: The remote made a websocket protocol violation. The connection will be closed gracefully indicating to the remote what went wrong. You can just keep calling poll_read until None is returned.
• tungstenite returned a utf8 error. Pharos will return it as a Tungstenite error. This means the remote send a text message, which is not supported, so the connection will be gracefully closed. You can just keep calling poll_read until None is returned.
• WsErr::ReceivedText: This means the remote send a text message, which is not supported, so the connection will be gracefully closed. You can just keep calling poll_read until None is returned.

On writing, eg. AsyncWrite::* all errors are fatal.

When a Protocol error is encountered during writing, it indicates that either ws_stream_tungstenite or tungstenite have a bug so it will panic.

Implementations

impl<S> WsStream<S>

where S: AsyncRead + AsyncWrite + Send + Unpin,

pub fn new(inner: ATungSocket<S>) -> Self

Create a new WsStream.

Trait Implementations

impl<S> AsyncBufRead for WsStream<S>

where S: AsyncRead + AsyncWrite + Send + Unpin,

fn poll_fill_buf( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Result<&[u8]>>

Attempt to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amount: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl<S> AsyncRead for WsStream<S>

where S: AsyncRead + AsyncWrite + Send + Unpin,

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8] ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>] ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<S> AsyncRead for WsStream<S>

where S: AsyncRead + AsyncWrite + Send + Unpin,

Available on crate feature tokio_io only.

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_> ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl<S> AsyncWrite for WsStream<S>

where S: AsyncRead + AsyncWrite + Send + Unpin,

Available on crate feature tokio_io only.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<Result<usize>>

Will always flush the underlying socket. Will always create an entire Websocket message from every write, so call with a sufficiently large buffer if you have performance problems. Don’t call with a buffer larger than the max message size accepted by the remote endpoint.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>] ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl<S> AsyncWrite for WsStream<S>

where S: AsyncRead + AsyncWrite + Send + Unpin,

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>] ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl<S> Debug for WsStream<S>

where S: AsyncRead + AsyncWrite + Send + Unpin,

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

Formats the value using the given formatter.

impl<S> Observable<WsEvent> for WsStream<S>

where S: AsyncRead + AsyncWrite + Send + Unpin,

type Error = WsErr

The error type that is returned if observing is not possible.

fn observe( &mut self, options: ObserveConfig<WsEvent> ) -> Observe<'_, WsEvent, Self::Error>

Add an observer to the observable. Options allow chosing the channel type and to filter events with a predicate.