Struct ws_stream_tungstenite::WsStream

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

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

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. Note that if you get io::ErrorKind::InvalidData, it means you send data that exceeds the tungstenite Capacity. Eg. it leads to a message that exceeds the max message size in tungstenite. It's intended that ws_stream_tungstenite protects from this by splitting the data in several messages, but for now there is no way to find out what the max message size is from the underlying WebSocketStream, so that will require changes in the API of tungstenite and async-tungstenite, so that will be for a future release.

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 + Unpin, 

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

Create a new WsStream.

Trait Implementations

impl<S> AsyncBufRead for WsStream<S> where
    S: AsyncRead + AsyncWrite + 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 + 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 + Unpin, 

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 + Unpin, 

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_write_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context<'_>,
    bufs: &[IoSlice<'_>]
) -> 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 buffers 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<()>>

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> AsyncWrite for WsStream<S> where
    S: AsyncRead + AsyncWrite + Unpin, 

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.

impl<S> Debug for WsStream<S> where
    S: AsyncRead + AsyncWrite + 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 + Unpin, 

type Error = WsErr

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

fn observe(
    &mut self,
    options: ObserveConfig<WsEvent>
) -> Result<Events<WsEvent>, Self::Error>

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