HewStandard Library

Module std::net::websocket

WebSocket client and server for bidirectional communication.

Provides blocking WebSocket connections that can send and receive text messages. Both client and server connections use the same Conn type, so the send/receive API is identical in both directions.

Client example

import std::net::websocket;

fn main() {
    let ws = websocket.connect("ws://localhost:8080/ws");
    ws.send_text("hello");
    let msg = ws.recv();
    msg.free();
    ws.close();
}

Server example

import std::net::websocket;

fn main() {
    let server = websocket.listen("0.0.0.0:8080");
    let conn = server.accept();
    let msg = conn.recv();
    conn.send_text("got it");
    conn.close();
    server.close();
}

Contents

Functions

Function connect

pub fn connect(url: string) -> Conn

Open a WebSocket connection to the given URL (client).

Function listen

pub fn listen(addr: string) -> Server

Start a WebSocket server listening on the given address.

Examples

let server = websocket.listen("0.0.0.0:8080");
let conn = server.accept();

Types

Struct Conn

An open WebSocket connection handle.

Created by calling websocket.connect(url). Use send_text() to send messages and recv() to receive them.

Struct Message

An incoming WebSocket message handle.

Obtained from conn.recv(). Must be freed with free() when no longer needed.

Struct Server

A WebSocket server listening for incoming connections.

Created by calling websocket.listen(addr). Use accept() to wait for the next client connection.

Traits

Trait ConnMethods

Methods available on a WebSocket Conn.

Methods

fn send_text(self: Self, msg: string) -> i64

Send a text message over the connection. Return 0 on success.

fn try_send_text(self: Self, msg: string) -> Result<(), fs.IoError>

Send a text message over the connection.

fn recv(self: Self) -> Message

Block until a message is received and return it.

fn recv_timeout(self: Self, deadline_ms: i64) -> Result<Message, fs.IoError>

Receive a message with a per-call deadline.

deadline_ms <= 0 disables the deadline and behaves like recv. Returns Err(IoError::TimedOut(0)) on deadline expiry. On other failures returns Err(IoError::Other(0)) (WebSocket errors carry no OS errno channel).

fn close(self: Self)

Close the WebSocket connection.

fn attach(self: Self, handler: LocalPid<WebSocketHandler>, on_message_type: i64, on_close_type: i64)

Attach this connection to an actor (Erlang-style active mode). The runtime reads frames in a background thread and delivers them as actor messages. Transfers ownership — the Conn handle is consumed and must not be used for recv() after this call. The actor can still call conn.send_text() for outbound messages.

handler is the actor that will receive on_message and on_close. on_message_type is the msg_type index for the on_message receive fn. on_close_type is the msg_type index for the on_close receive fn.

Trait MessageMethods

Methods available on a WebSocket Message.

Methods

fn msg_type(self: Self) -> i32

Get the message type (0=text, 1=binary, 2=ping, 3=pong, 4=close, -1=error).

fn text(self: Self) -> string

Extract the text content of a text message.

fn free(self: Self)

Release the message resources.

Trait ServerMethods

Methods available on a WebSocket Server.

Methods

fn accept(self: Self) -> Conn

Accept the next WebSocket connection. Blocks until a client connects and completes the handshake.

fn port(self: Self) -> i64

Get the port the server is listening on.

fn close(self: Self)

Close the server and stop listening.

Trait WebSocketHandler

Trait for actors that handle WebSocket connections.

Implement this on an actor and call conn.attach(actor) to have the runtime deliver frames as actor messages. The actor never calls recv() — the runtime reads in a background thread.

Example

actor Echo {
    let conn: Conn;
    receive fn on_message(text: string) {
        conn.send_text("echo: " + text);
    }
    receive fn on_close() {
        println("disconnected");
    }
}

Methods

fn on_message(text: string)

Called when a text frame arrives from the client.

fn on_close()

Called when the connection closes or errors.