Struct WebSocketContext

pub struct WebSocketContext {
    role: Role,
    frame: FrameCodec,
    state: WebSocketState,
    incomplete: Option<IncompleteMessage>,
    additional_send: Option<Frame>,
    unflushed_additional: bool,
    config: WebSocketConfig,
}

A context for managing WebSocket stream.

Fields

role: Role

Server or client?

frame: FrameCodec

encoder/decoder of frame.

state: WebSocketState

The state of processing, either “active” or “closing”.

incomplete: Option<IncompleteMessage>

Receive: an incomplete message being processed.

additional_send: Option<Frame>

Send in addition to regular messages E.g. “pong” or “close”.

unflushed_additional: bool

True indicates there is an additional message (like a pong) that failed to flush previously and we should try again.

config: WebSocketConfig

The configuration for the websocket session.

Implementations

impl WebSocketContext

pub fn new(role: Role, config: Option<WebSocketConfig>) -> Self

Create a WebSocket context that manages a post-handshake stream.

Panics

Panics if config is invalid e.g. max_write_buffer_size <= write_buffer_size.

pub fn from_partially_read( part: Vec<u8>, role: Role, config: Option<WebSocketConfig>, ) -> Self

Create a WebSocket context that manages an post-handshake stream.

Panics

Panics if config is invalid e.g. max_write_buffer_size <= write_buffer_size.

fn _new(role: Role, frame: FrameCodec, config: WebSocketConfig) -> Self

pub fn set_config(&mut self, set_func: impl FnOnce(&mut WebSocketConfig))

Change the configuration.

Panics

Panics if config is invalid e.g. max_write_buffer_size <= write_buffer_size.

pub fn get_config(&self) -> &WebSocketConfig

Read the configuration.

pub fn can_read(&self) -> bool

Check if it is possible to read messages.

Reading is impossible after receiving Message::Close. It is still possible after sending close frame since the peer still may send some data before confirming close.

pub fn can_write(&self) -> bool

Check if it is possible to write messages.

Writing gets impossible immediately after sending or receiving Message::Close.

pub fn read<Stream>(&mut self, stream: &mut Stream) -> Result<Message>

where Stream: Read + Write,

Read a message from the provided stream, if possible.

This function sends pong and close responses automatically. However, it never blocks on write.

pub fn write<Stream>( &mut self, stream: &mut Stream, message: Message, ) -> Result<()>

where Stream: Read + Write,

Write a message to the provided stream.

A subsequent call should be made to flush to flush writes.

In the event of stream write failure the message frame will be stored in the write buffer and will try again on the next call to write or flush.

If the write buffer would exceed the configured WebSocketConfig::max_write_buffer_size Err(WriteBufferFull(msg_frame)) is returned.

pub fn flush<Stream>(&mut self, stream: &mut Stream) -> Result<()>

where Stream: Read + Write,

Flush writes.

Ensures all messages previously passed to write and automatically queued pong responses are written & flushed into the stream.

fn _write<Stream>( &mut self, stream: &mut Stream, data: Option<Frame>, ) -> Result<bool>

where Stream: Read + Write,

Writes any data in the out_buffer, additional_send and given data.

Does not flush.

Returns true if the write contents indicate we should flush immediately.

pub fn close<Stream>( &mut self, stream: &mut Stream, code: Option<CloseFrame<'_>>, ) -> Result<()>

where Stream: Read + Write,

Close the connection.

This function guarantees that the close frame will be queued. There is no need to call it again. Calling this function is the same as calling send(Message::Close(..)).

fn read_message_frame<Stream>( &mut self, stream: &mut Stream, ) -> Result<Option<Message>>

where Stream: Read + Write,

Try to decode one message frame. May return None.

fn do_close<'t>( &mut self, close: Option<CloseFrame<'t>>, ) -> Option<Option<CloseFrame<'t>>>

Received a close frame. Tells if we need to return a close frame to the user.

fn buffer_frame<Stream>( &mut self, stream: &mut Stream, frame: Frame, ) -> Result<()>

where Stream: Read + Write,

Write a single frame into the write-buffer.

fn set_additional(&mut self, add: Frame)

Replace additional_send if it is currently a Pong message.

Trait Implementations

impl Debug for WebSocketContext

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

Formats the value using the given formatter.