Skip to content
Velt
velt/net/websocket exports

velt/net/websocket

API reference

WebSockets (RFC 6455), written in Velt on velt/net streams: opened as a client to ws:// / wss:// URLs, or over a connection a server upgraded. The HTTP server package accepts them with upgradeWebSocket (from http-server/websocket), which is built on webSocketOver: another server can do the same. For a walkthrough, read the guide.

import { connectWebSocket, WebSocket, webSocketOver } from "velt/net/websocket";

Exports

connectWebSocketOpens a client connection to a ws:// or wss:// URL.webSocketAcceptThe Sec-WebSocket-Accept value that answers a client's Sec-WebSocket-Key (RFC 6455 §4.2.2).publishSends text to every connection subscribed to topic (ws.subscribe): the frame is encoded once and queued for each subscriber, which sends it with whatever else is queued.publishBytespublish with a binary message.webSocketOverA WebSocket over stream, a connection whose opening handshake is done: an HTTP connection a server upgraded (server true: this side reads masked frames and sends unmasked ones), or one a client opened.WsMessageOne received message: text, or binary data.WsConnectOptionsNo doc comment yetWebSocketAn open WebSocket connection.
functionasync

connectWebSocket

#std/net/websocket/connect.vlt:13

Re-exported from velt/net/websocket/connect

async function connectWebSocket(
  url: string,
  opts: WsConnectOptions = {},
): Promise<WebSocket>

Opens a client connection to a ws:// or wss:// URL.

function

webSocketAccept

#std/net/websocket/handshake.vlt:19

Re-exported from velt/net/websocket/handshake

function webSocketAccept(key: string): string

The Sec-WebSocket-Accept value that answers a client's Sec-WebSocket-Key (RFC 6455 §4.2.2).

function

publish

#std/net/websocket/publish.vlt:33

Re-exported from velt/net/websocket/publish

function publish(topic: string, text: string): i64

Sends text to every connection subscribed to topic (ws.subscribe): the frame is encoded once and queued for each subscriber, which sends it with whatever else is queued. A subscriber with more than 16 MiB already queued misses the message. Returns the number of connections it was queued for.

function

publishBytes

#std/net/websocket/publish.vlt:43

Re-exported from velt/net/websocket/publish

function publishBytes(topic: string, data: u8[]): i64

publish with a binary message.

function

webSocketOver

#std/net/websocket/socket.vlt:244

Re-exported from velt/net/websocket/socket

function webSocketOver(
  stream: TcpStream,
  server: bool,
  head: u8[] = [],
): WebSocket

A WebSocket over stream, a connection whose opening handshake is done: an HTTP connection a server upgraded (server true: this side reads masked frames and sends unmasked ones), or one a client opened. head holds what was already read from stream past the handshake (the peer's first frames, if it did not wait). The connection is the socket's from then on.

class

WsMessage

#std/net/websocket/message.vlt:4

Re-exported from velt/net/websocket/message

One received message: text, or binary data.

Returned byWebSocket.receiveUsed byWebSocket

isBinary: bool

True for a binary message (data), false for text (text).

text: stringNo doc comment yet
data: u8[]No doc comment yet
constructor(isBinary: bool, text: string, data: u8[])No doc comment yet
struct

WsConnectOptions

#std/net/websocket/connect.vlt:7

Re-exported from velt/net/websocket/connect

Parameter ofconnectWebSocketNo doc comment yet: add one

FieldTypeDescription
ca? stringExtra trusted CA certificates (PEM) for wss://, e.g. a private or test CA.
struct

WebSocket

#std/net/websocket/socket.vlt:92

Re-exported from velt/net/websocket/socket

struct WebSocket implements AsyncIterable<WsMessage, IoError>

An open WebSocket connection. A handle like std/net's TcpStream: its copies share one connection, so one task can wait in receive while another sends. Released by close().

Returned byconnectWebSocketwebSocketOver

async send(text: string): Promise<void>

Sends a text message: returns once it is queued (everything queued goes out in one write), waiting while more than 1 MiB is queued for this connection.

async sendBytes(data: u8[]): Promise<void>

Sends a binary message, queued like send.

async receive(): Promise<WsMessage | null>

The next message, or null once the peer has closed the connection.

async subscribe(topic: string): Promise<void>

Subscribes this connection to topic: messages published to it (publish) are sent here until unsubscribe(topic) or the connection closes. Subscribing twice is a no-op.

unsubscribe(topic: string)

Leaves topic (nothing happens if this connection is not subscribed to it).

publish(topic: string, text: string): i64

Sends text to every connection subscribed to topic except this one (Bun's ws.publish); the number of connections it was queued for.

publishBytes(topic: string, data: u8[]): i64

publish with a binary message.

async * [Symbol.asyncIterator](): AsyncIterator<WsMessage, IoError>

for await (const m of ws): the messages until the peer has closed the connection. Leaving the loop early leaves the connection open.

async close(code: i64 = 1000, reason: string = ""): Promise<void>

Sends a close frame (code 1000 = normal closure; 1000-1003, 1007-1014 or 3000-4999, else IoError "EINVAL", nothing is sent and the connection stays open) after everything queued, waits until it is written, and releases the handle. Closing a connection the peer already closed, or closing twice, is fine; other operations on the handle (through any copy) throw IoError EBADF afterwards.