Milo

Appearance

std/ws ​

WebSocket connections (RFC 6455), both sides: wsAccept upgrades a TCP connection a server has already accepted, and wsConnect / wsConnectTls dial one. WsConn.recv reassembles fragmented messages and answers pings itself.

milo
from "std/ws" import { WsConn, WsMessage, wsAccept, wsConnect, wsConnectTls }

API reference ​

WsConn ​

milo
pub struct WsConn

WsConn.close ​

milo
fn WsConn.close(self: &mut WsConn): void

Send a close frame and release the socket and TLS state now rather than at drop. Afterwards every send and recv fails. The handles are reset, not just flagged: this used to close the fd and keep the number, so a later send wrote to whatever the kernel reused it for, and the TLS state leaked because drop skips a closed conn.

WsConn.ping ​

milo
fn WsConn.ping(self: &WsConn): Result<i32, string>

Send a ping.

WsConn.readMessage ​

milo
fn WsConn.readMessage(self: &WsConn, maxBytes: i64, returnPongs: bool): Result<WsMessage, string>

WsConn.recv ​

milo
fn WsConn.recv(self: &WsConn): Result<WsMessage, string>

Read next WebSocket message. Handles fragmentation, responds to ping automatically. &Self, like the sends: a read changes nothing in the handle, so one task can read while scoped tasks borrowing the same connection write (Task.scope).

WsConn.recvWithin ​

milo
fn WsConn.recvWithin(self: &WsConn, maxBytes: i64): Result<WsMessage, string>

recv for a server facing untrusted peers. A message longer than maxBytes is refused before its payload is allocated (close 1009, Err "message too big"): the length is the peer's to claim. Pongs come back as messages, so a heartbeat can tell a live peer from a half-open socket; one arriving mid-fragment is dropped.

WsConn.sendBinary ​

milo
fn WsConn.sendBinary(self: &WsConn, data: &string): Result<i32, string>

Send a binary message.

WsConn.sendSealed ​

milo
fn WsConn.sendSealed(self: &WsConn, msg: &Sealed): Result<i32, string>

Send a sealed buffer as one text message, framed straight from its bytes.

WsConn.sendShared ​

milo
fn WsConn.sendShared(self: &WsConn, msg: &Shared): Result<i32, string>

Send a shared sealed buffer as one text message. The fan-out shape: seal and share a message once, hand each connection's writer a refcount clone, and every socket is written from the one buffer.

WsConn.sendText ​

milo
fn WsConn.sendText(self: &WsConn, msg: &string): Result<i32, string>

Send a text message.

WsConn.tlsHandle ​

milo
fn WsConn.tlsHandle(self: &WsConn): i64

The TLS handle, 0 for plain TCP. Opaque to callers: pass it back to std, never construct one.

WsConn.view ​

milo
fn WsConn.view(fd: i32, ssl: i64, isClient: bool): WsConn

A second handle over a socket some other WsConn owns: same fd and TLS handle, but this one never closes them (ws.rawFd() / ws.tlsHandle() are the values to pass). The owner must outlive it, and nothing checks that, hence @unsafe. For a reader and a writer on one connection use Task.scope, whose tasks borrow the owner.

WsMessage ​

milo
pub struct WsMessage

Fields: opcode: WsOpcode, payload: string.

WsOpcode ​

milo
pub enum WsOpcode: i32

RFC 6455 §5.2 opcode nibble. The discriminant IS the wire value, so op as i32 is what goes in the frame header and WsOpcode.tryFrom(nibble) rejects the reserved codes (3–7, 11–15) that the spec says must fail the connection.

Variants:

  • Continuation = 0
  • Text = 1
  • Binary = 2
  • Close = 8
  • Ping = 9
  • Pong = 10

Functions ​

extractWsKey ​

milo
pub fn extractWsKey(raw: &string): string

Extract Sec-WebSocket-Key from raw HTTP request.

isWsUpgrade ​

milo
pub fn isWsUpgrade(raw: &string): bool

Check if raw HTTP request bytes contain a WebSocket upgrade request.

wsAccept ​

milo
pub fn wsAccept(conn: TcpStream, rawRequest: &string): Result<WsConn, string>

Accept a WebSocket upgrade on an already-accepted TCP connection, which the WsConn takes over (on error it is dropped, closing the socket). Pass the raw HTTP request bytes so the handshake can be completed.

wsConnect ​

milo
pub fn wsConnect(ip: u32, port: u16, path: &string): Result<WsConn, string>

Connect to a WebSocket server. Performs TCP connect + HTTP upgrade handshake. Returns a WsConn on successful 101 response.

wsConnectTls ​

milo
pub fn wsConnectTls(ip: u32, port: u16, hostname: &string, path: &string): Result<WsConn, string>

Connect to a WebSocket server over TLS (wss://). Performs TCP connect, TLS handshake (blocking — call before setting fds nonblocking), then the HTTP upgrade handshake over the encrypted channel. hostname is used for SNI, certificate validation, and the Host header.