Struct WebSocket 

pub struct WebSocket<S> { /* private fields */ }

WebSocket protocol implementation over an async stream.

Implementations

impl<'f, S> WebSocket<S>

pub fn after_handshake(stream: S, role: Role) -> Self

where S: AsyncRead + AsyncWrite + Unpin,

Creates a new WebSocket from a stream that has already completed the WebSocket handshake.

Use the upgrade feature to handle server upgrades and client handshakes.

Example

use tokio::net::TcpStream;
use fastwebsockets::{WebSocket, OpCode, Role};
use eyre::Result;

async fn handle_client(
  socket: TcpStream,
) -> Result<()> {
  let mut ws = WebSocket::after_handshake(socket, Role::Server);
  // ...
  Ok(())
}

pub fn into_inner(self) -> S

Consumes the WebSocket and returns the underlying stream.

pub fn set_writev(&mut self, vectored: bool)

Sets whether to use vectored writes. This option does not guarantee that vectored writes will be always used.

Default: true

pub fn set_writev_threshold(&mut self, threshold: usize)

pub fn set_auto_close(&mut self, auto_close: bool)

Sets whether to automatically close the connection when a close frame is received. When set to false, the application will have to manually send close frames.

Default: true

pub fn set_auto_pong(&mut self, auto_pong: bool)

Sets whether to automatically send a pong frame when a ping frame is received.

Default: true

pub fn set_max_message_size(&mut self, max_message_size: usize)

Sets the maximum message size in bytes. If a message is received that is larger than this, the connection will be closed.

Default: 64 MiB

pub fn set_auto_apply_mask(&mut self, auto_apply_mask: bool)

Sets whether to automatically apply the mask to the frame payload.

Default: true

pub fn is_closed(&self) -> bool

pub async fn write_frame( &mut self, frame: Frame<'f>, ) -> Result<(), WebSocketError>

where S: AsyncRead + AsyncWrite + Unpin,

Writes a frame to the stream.

Example

use fastwebsockets::{WebSocket, Frame, OpCode};
use tokio::net::TcpStream;
use eyre::Result;

async fn send(
  ws: &mut WebSocket<TcpStream>
) -> Result<()> {
  let mut frame = Frame::binary(vec![0x01, 0x02, 0x03].into());
  ws.write_frame(frame).await?;
  Ok(())
}

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

where S: AsyncWrite + Unpin,

Flushes the data from the underlying stream.

if the underlying stream is buffered (i.e: TlsStream<TcpStream>), it is needed to call flush to be sure that the written frame are correctly pushed down to the bottom stream/channel.

pub async fn read_frame(&mut self) -> Result<Frame<'f>, WebSocketError>

where S: AsyncRead + AsyncWrite + Unpin,

Reads a frame from the stream.

This method will unmask the frame payload. For fragmented frames, use FragmentCollector::read_frame.

Text frames payload is guaranteed to be valid UTF-8.

Example

use fastwebsockets::{OpCode, WebSocket, Frame};
use tokio::net::TcpStream;
use eyre::Result;

async fn echo(
  ws: &mut WebSocket<TcpStream>
) -> Result<()> {
  let frame = ws.read_frame().await?;
  match frame.opcode {
    OpCode::Text | OpCode::Binary => {
      ws.write_frame(frame).await?;
    }
    _ => {}
  }
  Ok(())
}