Skip to content

WebSocket ​

A WebSocket is a long-lived, two-way connection. app.ws(path, options) turns a route into one, and connectWebSocket(url, protocols?) returns Promise<Result<WebSocket, HttpError>>. Both ends get the same WebSocket value, so reading and writing look the same on either side.

Route options ​

OptionTypePurpose
handler(socket: WebSocket) => Promise<void>Required. Runs once per connection; the connection closes when its Promise settles.
originsstring[]Browser origins allowed to connect. Without it only the server's own origin is accepted; a request with no Origin header, which does not come from a browser page, is always accepted.
subprotocolsstring[]Subprotocols the route speaks, in order of preference.
maxMessageBytesi64Largest message accepted, 1 MB by default. A larger message fails the receive that reads it.
preHandler((request: HttpRequest) => HttpResponse | true)[]Named functions run against the upgrade request before it is accepted, where cookies and headers decide who may connect; the first one that returns a response refuses the upgrade with it. Upgrades also count against the server's rateLimit.
config{ rateLimit?: RateLimit }A limit on upgrades for this route, written like an HTTP route's config.rateLimit; it replaces the server-wide rateLimit for this route.

Methods ​

MethodSignaturePurpose
stream() => Promise<Result<DuplexStream<u8[], u8[]>, HttpError>>Transfers binary message I/O to a bounded duplex. Each chunk is one complete binary WebSocket message.
receive() => Promise<Result<WebSocketMessage?, HttpError>>Waits for the next whole message; resolves with no message once the peer has closed the connection.
sendText(text: string) => Promise<Result<void, HttpError>>Sends one text message and resolves once it has been written.
sendBytes(data: u8[]) => Promise<Result<void, HttpError>>Sends one binary message and resolves once it has been written.
close(code?: i32, reason?: string) => Promise<Result<void, HttpError>>Sends a close with code (1000 by default, or 3000 to 4999) and an optional reason of at most 123 bytes, and ends the connection; closing twice is not an error.
protocol() => stringThe agreed subprotocol, or an empty string.
closeCode() => i32?The close code received from the peer after receive() observes its close frame, or no value before then or after an unclean transport end.

WebSocketMessage carries one whole message, never a piece of one: binary says which field holds it, text for a text message and bytes for a binary one. Pings are answered automatically and never reach the program. The runtime also sends a heartbeat ping every 30 seconds; if the peer misses the following probe, the socket ends and a pending receive() resolves with no message.

stream() hands binary message I/O to a DuplexStream<u8[], u8[]>. Its readable and writable chunks are each one complete binary WebSocket message, never a fragment. The handoff makes receive(), sendText() and sendBytes() return Err(HttpError) with ERR_HTTP_WS_STREAMED, so they cannot race the duplex. Closing its writable side starts the close handshake while the readable side can still receive the peer's final messages. A received text message cannot become bytes silently: it fails the readable side with StreamError code ERR_STREAM_WS_TEXT_MESSAGE.

A send returns Promise<Result<void, HttpError>> and waits for the connection to accept the message, so a fast sender slows down to the pace of a slow peer instead of queueing without limit. Only one receive may be pending at a time. server.close() closes every open socket with code 1001 and waits for its handler, within shutdownTimeout; a receive the handler has pending resolves with no message.

Errors ​

All fallible WebSocket methods return recoverable failures as Err(HttpError). Codes include ERR_HTTP_WS_CLOSED, ERR_HTTP_WS_STREAMED, ERR_HTTP_WS_BUSY, ERR_HTTP_WS_SEND, ERR_HTTP_WS_CLOSE_CODE and ERR_HTTP_WS_CLOSE_REASON; message receive errors include ERR_HTTP_WS_MESSAGE_TOO_LARGE and ERR_HTTP_WS_RECEIVE. Connection failures return Err(HttpError) from connectWebSocket, with codes ERR_HTTP_WS_URL, ERR_HTTP_WS_DNS, ERR_HTTP_WS_CONNECT, ERR_HTTP_WS_TLS, ERR_HTTP_WS_HANDSHAKE, or ERR_HTTP_FETCH_BLOCKED when app.fetchPolicy(...) refuses the destination, which it judges the same way it judges fetch.

Usage ​

tyrus
import { connectWebSocket, createRouter, HttpError, HttpRouter, HttpServer, WebSocket, WebSocketMessage } from "tyrus:http";

async function echoMessages(socket: WebSocket): Promise<void> throws HttpError {
    let open: boolean = true;
    while (open) {
        const message: WebSocketMessage? = await socket.receive();
        if (message) {
            if (message.binary) {
                await socket.sendBytes(message.bytes);
            } else {
                await socket.sendText(`echo ${message.text}`);
            }
        } else {
            open = false;
        }
    }
}

async function echo(socket: WebSocket): Promise<void> {
    try {
        await echoMessages(socket);
    } catch (error: HttpError) {
        console.error(error.code);
    }
}

async function main(): Promise<void> {
    const app: HttpRouter = createRouter();
    app.ws("/echo", { handler: echo, origins: ["https://app.example.com"], subprotocols: ["chat"], maxMessageBytes: 65536 });
    try {
        const server: HttpServer = app.start(3000);
        const connection = await connectWebSocket("ws://127.0.0.1:3000/echo", ["chat"]);
        const socket: WebSocket = match connection {
            Ok(value) => value,
            Err(error) => { console.error(error.code); return; }
        };
        await socket.sendText("hello");
        const reply: WebSocketMessage? = await socket.receive();
        if (reply) {
            console.log(reply.text);
        }
        await socket.close();
        await server.close();
    } catch (error: HttpError) {
        console.error(error.code);
    }
}