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

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§

source§

impl<S> WsStream<S>
where S: AsyncRead + AsyncWrite + Send + Unpin,

source

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

Create a new WsStream.

Trait Implementations§

source§

impl<S> AsyncBufRead for WsStream<S>
where S: AsyncRead + AsyncWrite + Send + Unpin,

source§

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. Read more
source§

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. Read more
source§

impl<S> AsyncRead for WsStream<S>
where S: AsyncRead + AsyncWrite + Send + Unpin,

source§

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

Attempt to read from the AsyncRead into buf. Read more
source§

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. Read more
source§

impl<S> AsyncRead for WsStream<S>
where S: AsyncRead + AsyncWrite + Send + Unpin,

Available on crate feature tokio_io only.
source§

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

Attempts to read from the AsyncRead into buf. Read more
source§

impl<S> AsyncWrite for WsStream<S>
where S: AsyncRead + AsyncWrite + Send + Unpin,

Available on crate feature tokio_io only.
source§

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.

source§

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. Read more
source§

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. Read more
source§

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. Read more
source§

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation. Read more
source§

impl<S> AsyncWrite for WsStream<S>
where S: AsyncRead + AsyncWrite + Send + Unpin,

source§

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

Attempt to write bytes from buf into the object. Read more
source§

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. Read more
source§

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. Read more
source§

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

Attempt to close the object. Read more
source§

impl<S> Debug for WsStream<S>
where S: AsyncRead + AsyncWrite + Send + Unpin,

source§

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

Formats the value using the given formatter. Read more
source§

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. Read more
source§

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.

Auto Trait Implementations§

§

impl<S> !RefUnwindSafe for WsStream<S>

§

impl<S> Send for WsStream<S>

§

impl<S> !Sync for WsStream<S>

§

impl<S> Unpin for WsStream<S>

§

impl<S> !UnwindSafe for WsStream<S>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<R> AsyncBufReadExt for R
where R: AsyncBufRead + ?Sized,

source§

fn fill_buf(&mut self) -> FillBuf<'_, Self>
where Self: Unpin,

Creates a future which will wait for a non-empty buffer to be available from this I/O object or EOF to be reached. Read more
source§

fn consume_unpin(&mut self, amt: usize)
where Self: Unpin,

A convenience for calling AsyncBufRead::consume on Unpin IO types. Read more
source§

fn read_until<'a>( &'a mut self, byte: u8, buf: &'a mut Vec<u8> ) -> ReadUntil<'a, Self>
where Self: Unpin,

Creates a future which will read all the bytes associated with this I/O object into buf until the delimiter byte or EOF is reached. This method is the async equivalent to BufRead::read_until. Read more
source§

fn read_line<'a>(&'a mut self, buf: &'a mut String) -> ReadLine<'a, Self>
where Self: Unpin,

Creates a future which will read all the bytes associated with this I/O object into buf until a newline (the 0xA byte) or EOF is reached, This method is the async equivalent to BufRead::read_line. Read more
source§

fn lines(self) -> Lines<Self>
where Self: Sized,

Returns a stream over the lines of this reader. This method is the async equivalent to BufRead::lines. Read more
source§

impl<R> AsyncReadExt for R
where R: AsyncRead + ?Sized,

source§

fn chain<R>(self, next: R) -> Chain<Self, R>
where Self: Sized, R: AsyncRead,

Creates an adaptor which will chain this stream with another. Read more
source§

fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>
where Self: Unpin,

Tries to read some bytes directly into the given buf in asynchronous manner, returning a future type. Read more
source§

fn read_vectored<'a>( &'a mut self, bufs: &'a mut [IoSliceMut<'a>] ) -> ReadVectored<'a, Self>
where Self: Unpin,

Creates a future which will read from the AsyncRead into bufs using vectored IO operations. Read more
source§

fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>
where Self: Unpin,

Creates a future which will read exactly enough bytes to fill buf, returning an error if end of file (EOF) is hit sooner. Read more
source§

fn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self>
where Self: Unpin,

Creates a future which will read all the bytes from this AsyncRead. Read more
source§

fn read_to_string<'a>( &'a mut self, buf: &'a mut String ) -> ReadToString<'a, Self>
where Self: Unpin,

Creates a future which will read all the bytes from this AsyncRead. Read more
source§

fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>)
where Self: AsyncWrite + Sized,

Helper method for splitting this read/write object into two halves. Read more
source§

fn take(self, limit: u64) -> Take<Self>
where Self: Sized,

Creates an AsyncRead adapter which will read at most limit bytes from the underlying reader. Read more
source§

impl<W> AsyncWriteExt for W
where W: AsyncWrite + ?Sized,

source§

fn flush(&mut self) -> Flush<'_, Self>
where Self: Unpin,

Creates a future which will entirely flush this AsyncWrite. Read more
source§

fn close(&mut self) -> Close<'_, Self>
where Self: Unpin,

Creates a future which will entirely close this AsyncWrite.
source§

fn write<'a>(&'a mut self, buf: &'a [u8]) -> Write<'a, Self>
where Self: Unpin,

Creates a future which will write bytes from buf into the object. Read more
source§

fn write_vectored<'a>( &'a mut self, bufs: &'a [IoSlice<'a>] ) -> WriteVectored<'a, Self>
where Self: Unpin,

Creates a future which will write bytes from bufs into the object using vectored IO operations. Read more
source§

fn write_all<'a>(&'a mut self, buf: &'a [u8]) -> WriteAll<'a, Self>
where Self: Unpin,

Write data into this object. Read more
source§

fn into_sink<Item>(self) -> IntoSink<Self, Item>
where Item: AsRef<[u8]>, Self: Sized,

Allow using an AsyncWrite as a Sink<Item: AsRef<[u8]>>. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more