Crate lightws

source ·
Expand description

Lightweight websocket implement for stream transmission.

Features

  • Avoid heap allocation.
  • Avoid buffering frame payload.
  • Use vectored-io if available.
  • Transparent Read/Write over the underlying IO source.

High-level API

Std:

use std::io::{Read, Write};
use std::net::TcpStream;
use lightws::role::Client;
use lightws::endpoint::Endpoint;
fn run_sync() -> std::io::Result<()> {  
    let mut buf = [0u8; 256];
    // establish tcp connection
    let mut tcp = TcpStream::connect("example.com:80")?;
    // establish ws connection
    let mut ws = Endpoint::<TcpStream, Client>::connect(tcp, &mut buf, "example.com", "/ws")?;
    // read some data
    let n = ws.read(&mut buf)?;
    // write some data
    let n = ws.write(&buf)?;
    Ok(())
}

Tokio:

use tokio::net::TcpStream;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use lightws::role::Client;
use lightws::endpoint::Endpoint;
async fn run_async() -> std::io::Result<()> {
    let mut buf = [0u8; 256];
    // establish tcp connection
    let mut tcp = TcpStream::connect("example.com:80").await?;
    // establish ws connection
    let mut ws = Endpoint::<TcpStream, Client>::connect_async(tcp, &mut buf, "example.com", "/ws").await?;
    // read some data
    let n = ws.read(&mut buf).await?;
    // write some data
    let n = ws.write(&buf).await?;
    Ok(())
}

Low-level API

Frame:

use lightws::frame::{FrameHead, Fin, OpCode, PayloadLen, Mask};
{
    let mut buf = [0u8; 14];
    // crate a frame head
    let head = FrameHead::new(
        Fin::N, OpCode::Binary,
        Mask::None, PayloadLen::from_num(256)
    );
    // encode to buffer
    let offset = unsafe {
        head.encode_unchecked(&mut buf);
    };
    // decode from buffer
    let (head, offset) = FrameHead::decode(&buf).unwrap();
}

Handshake:

use lightws::handshake::{Request, Response, HttpHeader};
{
    let mut buf = [0u8; 256];
    // make a client handshake request
    let request = Request::new(b"/ws", b"example.com", b"sec-key..");
    let offset = request.encode(&mut buf).unwrap();

    // parse a server handshake response
    let mut custom_headers = HttpHeader::new_storage();
    let mut response = Response::new_storage(&mut custom_headers);
    let offset = response.decode(&buf).unwrap();
}

Modules