Struct WebSocket

pub struct WebSocket { /* private fields */ }

WebSocket stream for both clients and servers.

The WebSocket struct manages all aspects of WebSocket communication, handling mandatory frames (close, ping, and pong frames) and protocol compliance checks. It abstracts away details related to framing and compression, which are managed by the underlying ReadHalf and WriteHalf structures.

A WebSocket instance can be created via high-level functions like WebSocket::connect, or through a custom stream setup with WebSocket::handshake.

Connecting

To establish a WebSocket connection as a client:

use tokio::net::TcpStream;
use yawc::{WebSocket, frame::OpCode};
use futures::StreamExt;
use tokio_rustls::TlsConnector;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let ws = WebSocket::connect("wss://echo.websocket.org".parse()?).await?;
    // Use `ws` for WebSocket communication
    Ok(())
}

Ping and Pong Handling as a Client

When acting as a client, if a Ping frame is received from the server, WebSocket automatically replies with a Pong frame. However, the Ping frame is still made available to the user before the automatic response:

use tokio::net::TcpStream;
use yawc::{WebSocket, frame::OpCode};
use futures::StreamExt;

async fn client_loop(mut ws: WebSocket) -> anyhow::Result<()> {
    while let Some(frame) = ws.next().await {
        match frame.opcode {
            OpCode::Ping => {
                let ping_text = std::str::from_utf8(&frame.payload).unwrap();
                println!("Received ping with text: {ping_text}");
                // The WebSocket automatically sends a Pong in response
            }
            _ => {}
        }
    }

    Ok(())
}

Splitting the WebSocket

For concurrent reading and writing operations, use futures::StreamExt::split from the futures crate, which maintains all WebSocket protocol handling while enabling simultaneous reads and writes. This is the recommended approach for most concurrent WebSocket operations.

In contrast, WebSocket::split_stream is a low-level API that bypasses critical WebSocket protocol management and should rarely be used directly. It disables automatic control frame handling (like Ping/Pong), connection health monitoring, and other protocol-level features. Only use this method if you need direct access to the underlying frame processing and are prepared to handle all protocol requirements manually.

After calling WebSocket::split_stream, you get direct access to the raw ReadHalf and WriteHalf components, as well as the underlying HttpStream for direct stream access. Read more about their behavior in their respective documentation.

Implementations

impl WebSocket

pub fn connect(url: Url) -> WebSocketBuilder

Establishes a WebSocket connection to the specified url.

This asynchronous function supports both ws:// (non-secure) and wss:// (secure) schemes, allowing for secure WebSocket connections when needed. For secure connections, a default TLS configuration will be used.

Parameters

• url: The WebSocket URL to connect to. This can include both ws and wss schemes.

Returns

A Result containing either a connected WebSocket instance or an error if the connection could not be established.

Examples

use yawc::WebSocket;

#[tokio::main]
async fn main() -> yawc::Result<()> {
   let ws = WebSocket::connect("wss://echo.websocket.org".parse()?).await?;
   // Use `ws` to send and receive messages
   Ok(())
}

Errors

This function will return an error if:

• The URL provided is invalid or not a WebSocket URL.
• A network or TLS error occurs while trying to establish the connection.

Notes

• By default, no custom options are applied during the connection process. Use Options::default() for standard WebSocket behavior.
• For secure connections requiring custom TLS settings, use WebSocketBuilder::with_connector() instead.

pub async fn handshake<S: AsyncWrite + AsyncRead + Send + Unpin + 'static>( url: Url, io: S, options: Options, ) -> Result<WebSocket>

Performs a WebSocket handshake over an existing connection.

This asynchronous function establishes a WebSocket connection by performing the handshake with a pre-existing TCP stream or similar I/O type. It can be used when an active connection to a server exists, bypassing the need to initiate a new connection for the WebSocket.

Parameters

• url: The WebSocket URL to connect to, which should specify either ws or wss scheme.
• io: An I/O stream that implements AsyncWrite and AsyncRead, allowing WebSocket communication over this stream after the handshake completes. Typically, this is a TcpStream.
• options: Options to configure the WebSocket connection, such as compression and ping intervals.

Returns

A Result containing either an initialized WebSocket instance upon successful handshake or an error if the handshake fails.

Examples

use tokio::net::TcpStream;
use yawc::{WebSocket, Result, Options};

async fn handle_client(
    url: url::Url,
    socket: TcpStream,
) -> Result<()> {
    let mut ws = WebSocket::handshake(url, socket, Options::default()).await?;
    // Use `ws` to send and receive messages after a successful handshake
    Ok(())
}

Errors

This function may return an error if:

• The URL provided is invalid or does not specify a WebSocket URL.
• The handshake response does not meet WebSocket protocol requirements (e.g., missing required headers).
• A network or I/O error occurs during the handshake process.

Notes

• The function handles setting up necessary WebSocket headers, including Host, Upgrade, Connection, Sec-WebSocket-Key, and Sec-WebSocket-Version.
• If compression is enabled via Options, it will be negotiated as part of the handshake.

Usage

This function is useful when handling WebSocket connections with existing streams, such as when managing multiple connections in a server context.

pub async fn handshake_with_request<S: AsyncWrite + AsyncRead + Send + Unpin + 'static>( url: Url, io: S, options: Options, builder: HttpRequestBuilder, ) -> Result<WebSocket>

Performs a WebSocket handshake with a customizable HTTP request.

This method extends the basic handshake functionality by allowing you to provide a custom HTTP request builder, which can be used to set additional headers or customize the request before performing the WebSocket handshake.

Parameters

• url: The WebSocket URL to connect to
• io: The I/O stream to use for the WebSocket connection
• options: Configuration options for the WebSocket connection
• builder: A custom HTTP request builder for customizing the handshake request

Returns

A Result containing the established WebSocket connection if successful

Example

use yawc::{WebSocket, Options, Result};
use tokio::net::TcpStream;

async fn connect() -> Result<WebSocket> {
    let stream = TcpStream::connect("example.com:80").await.unwrap();
    let builder = yawc::HttpRequest::builder()
        .header("User-Agent", "My Custom WebSocket Client")
        .header("Authorization", "Bearer token123");

    WebSocket::handshake_with_request(
        "ws://example.com/socket".parse().unwrap(),
        stream,
        Options::default(),
        builder
    ).await
}

pub async fn reqwest( url: Url, client: Client, options: Options, ) -> Result<WebSocket>

Available on crate feature reqwest only.

Performs a WebSocket handshake when using the reqwest HTTP client.

This function is only available when the reqwest feature is enabled. It provides WebSocket handshake functionality using the reqwest::Client for HTTP request handling and connection management.

Parameters

• url: The WebSocket URL to connect to, supporting both ws and wss schemes.
• client: A configured reqwest::Client instance that will be used to initiate the connection.
• options: Options for configuring connection behavior like compression and payload limits.

Returns

A Result containing either a connected WebSocket instance or an error if the handshake fails.

Example

use reqwest::Client;
use yawc::{WebSocket, Options, Result};

async fn connect_ws(url: String) -> Result<()> {
    let client = Client::new();
    let ws = WebSocket::reqwest(
        url.parse()?,
        client,
        Options::default()
    ).await?;

    // Use WebSocket for communication
    Ok(())
}

Notes

• This function requires the reqwest feature to be enabled in your Cargo.toml
• Handles WebSocket protocol negotiation including compression if configured

pub fn upgrade<B>(request: impl BorrowMut<Request<B>>) -> UpgradeResult

Upgrades an HTTP connection to a WebSocket one.

Validates incoming HTTP request headers and handles protocol switching to establish a WebSocket connection. Returns a response to be sent back to the client and a future that will resolve into the WebSocket stream.

The response must be sent to the client before the upgrade future is awaited. Verification of headers like Origin, Sec-WebSocket-Protocol and Sec-WebSocket-Extensions is left to the caller.

Note: Connection and Upgrade headers must be validated separately. You can use header inspection to confirm this is a valid WebSocket upgrade request.

Parameters

• request: The incoming HTTP request to upgrade

Returns

Returns a tuple containing:

• Response with SWITCHING_PROTOCOLS status to send back
• UpgradeFut that resolves to the WebSocket stream

Example

use hyper::{
    body::{Bytes, Incoming},
    server::conn::http1,
    service::service_fn,
    Request, Response,
};
use yawc::{Result, WebSocket, UpgradeFut, Options};

async fn handle_client(fut: UpgradeFut) -> yawc::Result<()> {
    let ws = fut.await?;
    Ok(())
}

async fn server_upgrade(mut req: Request<Incoming>) -> anyhow::Result<yawc::HttpResponse> {
    let (response, fut) = WebSocket::upgrade_with_options(
        &mut req,
        Options::default()
    )?;

    tokio::task::spawn(async move {
        if let Err(e) = handle_client(fut).await {
            eprintln!("Error in websocket connection: {}", e);
        }
    });

    Ok(response)
}

Errors

Returns error if:

• Sec-WebSocket-Key header is missing
• Sec-WebSocket-Version is not “13”

pub fn upgrade_with_options<B>( request: impl BorrowMut<Request<B>>, options: Options, ) -> UpgradeResult

Attempts to upgrade an incoming hyper::Request to a WebSocket connection with customizable options.

Similar to WebSocket::upgrade, this function verifies the required WebSocket headers and, if successful, returns an HTTP response to switch protocols along with an upgrade future for the WebSocket stream. Additionally, it applies the specified options, which may define parameters such as compression settings, UTF-8 validation, and maximum payload size.

Parameters

• request: A mutable reference to the HTTP request to upgrade.
• options: Options that define parameters for the WebSocket connection, including compression and payload limits.

Returns

A Result containing:

• A Response with SWITCHING_PROTOCOLS status, which should be sent to the client.
• An UpgradeFut future that resolves to the WebSocket stream once the response is sent.

Notes

• options.compression: If enabled and supported by both client and server, the WebSocket connection will use compression.
• options.max_payload_read: Specifies the maximum size for received messages.
• The upgrade request must be verified for WebSocket headers before calling this function, as it does not inspect Connection or Upgrade headers.

Example

use hyper::{Request, body::Incoming};
use yawc::{Result, WebSocket, Options};

async fn handle_websocket_with_options(request: Request<Incoming>) -> Result<()> {
    let options = Options::default();
    let (response, upgrade) = WebSocket::upgrade_with_options(request, options)?;
    // Send `response` back to client, then await `upgrade` for WebSocket stream
    Ok(())
}

Errors

This function returns an error if:

• The Sec-WebSocket-Key header is missing.
• The Sec-WebSocket-Version header is not set to “13”.

pub unsafe fn split_stream( self, ) -> (Framed<HttpStream, Codec>, ReadHalf, WriteHalf)

Splits the WebSocket into its low-level components for advanced usage.

This method breaks down the WebSocket into three parts:

• Framed<HttpStream, Codec>: The raw stream with codec for handling WebSocket frames
• ReadHalf: Low-level component for receiving and processing frames
• WriteHalf: Low-level component for sending frames

Safety

This function is unsafe because:

• It splits ownership of shared state between components without synchronization
• You must ensure proper coordination between the split halves to maintain protocol correctness
• Misuse of the split components can cause protocol violations or memory corruption
• Manual management of component lifetimes is required to prevent use-after-free

Warning

This is a low-level API that should rarely be used directly. For most concurrent read/write use cases, use StreamExt::split instead, which preserves the WebSocket’s built-in protocol handling while enabling concurrent access.

Using this method bypasses critical WebSocket protocol management:

• Automatic Ping/Pong frame handling stops working
• Connection health monitoring is disabled
• Protocol compliance becomes your responsibility

Direct use of this API requires deep understanding of:

• WebSocket protocol details including control frame handling
• Proper bidirectional communication management
• Connection health monitoring implementations
• Thread safety and synchronization for concurrent access

Returns

A tuple of the raw frame-handling stream and the read/write components.

Example

use yawc::WebSocket;

async fn connect() -> yawc::Result<()> {
    let ws = WebSocket::connect("ws://example.com/ws".parse()?).await?;
    // Advanced usage - requires manual protocol handling
    let (raw_stream, read_half, write_half) = unsafe { ws.split_stream() };
    // Must implement control frame handling, connection monitoring etc.
    Ok(())
}

pub fn poll_next_frame( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<FrameView>>

Polls for the next frame in the WebSocket stream and handles protocol-level concerns.

This method manages asynchronous frame retrieval and ensures proper protocol handling, including connection cleanup, frame validation, and error responses.

Protocol Flow

1. Polls underlying stream for next frame
2. For received frames:
   • Processes and returns valid frames
   • Sends appropriate close frame for protocol violations
   • Flushes pending frames before connection closure
3. Begins cleanup when connection is closed

Frame Handling

• Valid frames are processed and returned for application use
• Protocol violations trigger graceful shutdown with appropriate status code
• Control frames (ping/pong/close) receive special handling
• Fragmented messages are reassembled before delivery

Error Responses

• Size violations receive CloseCode::Size
• Unsupported operations receive CloseCode::Unsupported
• Protocol violations receive CloseCode::Protocol
• Other errors receive CloseCode::Error

Parameters

• cx: Task context for managing asynchronous polling

Returns

• Poll::Ready(Ok(Frame)): Successfully received and processed frame
• Poll::Ready(Err(WebSocketError)): Protocol violation or other error
• Poll::Pending: More data needed for complete frame

pub async fn next_frame(&mut self) -> Result<FrameView>

Helper function to asynchronously retrieve the next frame from the WebSocket stream.

This is a convenience wrapper around WebSocket::poll_next_frame that uses poll_fn to convert the polling interface into an async/await interface. It allows users to simply await the next frame rather than manually handling polling.

Returns

• Ok(Frame) if a frame was successfully received
• Err(WebSocketError) if an error occurred while receiving the frame

pub async fn send_json<T: Serialize>(&mut self, data: &T) -> Result<()>

Available on crate feature json only.

Serializes data to JSON and sends it as a text frame over the WebSocket.

This method takes a reference to data, serializes it to JSON, and sends it as a text frame over the WebSocket connection. The method is only available when the json feature is enabled.

Type Parameters

• T: The type of data to serialize. Must implement serde::Serialize.

Parameters

• data: Reference to the data to serialize and send.

Returns

• Ok(()) if the data was successfully serialized and sent.
• Err if there was an error serializing the data or sending the frame.

Feature

This method requires the json feature to be enabled in your Cargo.toml:

[dependencies]
yawc = { version = "0.1", features = ["json"] }

Trait Implementations

impl Sink<FrameView> for WebSocket

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

Checks if the WebSocket is ready to send a frame.

This method first flushes any obligated frames, ensuring that pending data is sent before allowing new frames to be added. If the flush is successful, it polls the readiness of the write_half to send the next frame.

Parameters

• cx: The current task’s execution context, used to manage asynchronous polling.

Returns

• Poll::Ready(Ok(())) if the WebSocket is ready to send.
• Poll::Pending if the WebSocket is not yet ready.

fn start_send(self: Pin<&mut Self>, item: FrameView) -> Result<(), Self::Error>

Begins sending a frame to the WebSocket.

Adds the specified frame to the write_half for transmission. This method does not immediately send the frame; it merely prepares the frame for sending.

Parameters

• item: The Frame to be sent.

Returns

• Ok(()) if the frame was successfully prepared for sending.
• Err(WebSocketError) if an error occurs while preparing the frame.

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

Polls to flush all pending frames in the WebSocket stream.

Ensures that any frames waiting to be sent are fully flushed to the network.

Parameters

• cx: The current task’s execution context, used to manage asynchronous polling.

Returns

• Poll::Ready(Ok(())) if all pending frames have been flushed.
• Poll::Pending if there are still frames waiting to be flushed.

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

Polls the connection to close the WebSocket stream.

Initiates a graceful shutdown of the WebSocket by sending a close frame. This method will attempt to complete any pending frame transmissions before closing the connection.

Parameters

• cx: The current task’s execution context, used to manage asynchronous polling.

Returns

• Poll::Ready(Ok(())) if the WebSocket is successfully closed.
• Poll::Pending if the close process is still in progress.

type Error = WebSocketError

The type of value produced by the sink when an error occurs.

impl Stream for WebSocket

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Polls for the next frame from the WebSocket stream.

If the you want to receive the Result of reading from the WebSocket, use WebSocket::poll_next_frame instead.

This method handles asynchronous frame retrieval, managing both connection closure and frame-specific protocol compliance checks.

The method will return None when the WebSocket connection has been closed, signaling the end of the stream. In most cases, WebSocket will complete any pending obligations and flush frames before fully terminating the connection.

Parameters

• cx: The current task’s execution context, used to manage asynchronous polling.

Returns

• Poll::Ready(Some(Frame)) if a frame is successfully received.
• Poll::Ready(None) if the connection is closed, indicating no more frames will be received.

type Item = FrameView

Values yielded by the stream.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.