socket

std/socket — WebSocket, from the client side.

The browser is the target, so this is the client half and there is no other: a page connects, it does not listen. What crosses the boundary is text, so this carries text frames. A binary frame is not delivered rather than delivered as something it is not — a program that needs bytes encodes them and says how.

A message is taken off a queue, not handed to a callback. std/http opens its event streams the same way and for the same reason: a callback would be a second way for control to enter a program, and the language has one.

• Socket
• connect
• send
• receive
• pending
• open
• close

Socket

struct Socket

• id: int

connect

pub async fn connect(url: str) -> (Socket, error)

Connect, waiting until the socket is open.

The URL is ws:// or wss://. A page served over https can only reach wss://, which is the browser's rule and not this module's.

send

pub fn send(s: Socket, message: str) -> error

Send a text frame.

Sending on a socket that is not open is an error rather than a silent drop: the message did not go, and a program that is told so can decide what that means.

receive

pub async fn receive(s: Socket) -> (str, error)

The next message, waiting for one to arrive.

Answers an error once the socket closes — a closed socket will never produce another message, so waiting for one is the deadlock this reports instead of entering.

pending

pub fn pending(s: Socket) -> int

How many messages are waiting. A program with something else to do asks this rather than receive.

open

pub fn open(s: Socket) -> bool

Whether the socket is open. A socket that has closed answers false, and stays that way.

close

pub fn close(s: Socket)