WebSocket Client

Golem agents use WASI HTTP for outgoing HTTP requests, but WASI HTTP does not support WebSocket upgrades. Golem 1.5 introduces a dedicated WebSocket client API (golem:websocket@1.5.0) that complements WASI HTTP and allows agents to open WebSocket connections, send and receive messages, and handle connection lifecycle events.

TypeScript

The Golem TypeScript SDK provides a WebSocket client API. connectWebsocket opens a connection and returns a WebSocketHandle with send, receive, receiveWithTimeout, and close methods. Received messages are { tag: "text", val } / { tag: "binary", val }, and a graceful close surfaces as a WebsocketError with tag === "closed" and a closeInfo.


import { z } from "zod";
import { defineAgent, method, connectWebsocket, WebsocketError } from "@golemcloud/golem-ts-sdk";
 
export const ExampleAgent = defineAgent({
  name: "ExampleAgent",
  id: { name: z.string() },
  methods: {
    run: method({ input: {}, returns: z.void() }),
  },
});
 
export const ExampleAgentImpl = ExampleAgent.implement({
  init: () => ({}),
  methods: {
    async run() {
      const ws = await connectWebsocket("wss://example.com/chat");
      console.log("Connected");
      ws.send("Hello, server!");
      try {
        for (;;) {
          const message = await ws.receive();
          if (message.tag === "text") {
            console.log("Text:", message.val);
          } else {
            console.log("Binary:", message.val);
          }
        }
      } catch (err) {
        if (err instanceof WebsocketError && err.tag === "closed") {
          const info = err.closeInfo;
          if (info) {
            console.log(`Closed [${info.code}] "${info.reason}"`);
          }
        } else {
          throw err;
        }
      }
    },
  },
});

Effect TypeScript

The Effect SDK exposes a scoped Effect Socket. The surrounding scope closes the connection when the program finishes:


import { Effect, Fiber } from "effect"
import { Websocket } from "@golemcloud/effect-golem"
 
const run = Effect.scoped(
  Effect.gen(function* () {
    const socket = yield* Websocket.connect("wss://example.com/chat", {
      closeCodeIsError: (code) => code !== 1000,
    })
    const reader = yield* Effect.forkChild(
      socket.runString((message) => {
        console.log("Received:", message)
      }),
    )
 
    const write = yield* socket.writer
    yield* write("Hello, server!")
    yield* Fiber.join(reader)
  }),
)

This Effect runs inside an Effect Golem agent, whose runtime supplies the WebSocket host service. Websocket.layer(...) provides the same socket as an Effect Layer when layer composition is more convenient.

Rust

The Golem Rust SDK provides its own WebSocket API inspired by the tungstenite library. The main types are WebsocketConnection, WebSocketMessage, and WebSocketError.


use golem_rust::{WebSocketError, WebSocketMessage, WebsocketConnection};
 
async fn run_websocket() -> Result<(), WebSocketError> {
    let ws = WebsocketConnection::connect("wss://example.com/chat", None)?;
    println!("Connected");
    ws.send(&WebSocketMessage::Text("Hello, server!".to_string()))?;
    loop {
        match ws.receive().await {
            Ok(WebSocketMessage::Text(text)) => println!("Text: {text}"),
            Ok(WebSocketMessage::Binary(data)) => println!("Binary: {data:?}"),
            Err(WebSocketError::Closed(info)) => {
                if let Some(info) = info { println!("Closed [{}] \"{}\"", info.code, info.reason); }
                break;
            }
            Err(err) => return Err(err),
        }
    }
    Ok(())
}

Scala

Golem’s JavaScript runtime provides the standard WebSocket global. Add scalajs-dom to the Scala component and use its Scala.js facade:


import org.scalajs.dom.{CloseEvent, Event, MessageEvent, WebSocket}
import scala.concurrent.{Future, Promise}
 
case class ExampleAgentImpl() extends ExampleAgent {
  def run(): Future[Unit] = {
    val done = Promise[Unit]()
    val ws = new WebSocket("wss://example.com/chat")
    ws.onopen = { (_: Event) => println("Connected"); ws.send("Hello, server!") }
    ws.onmessage = { (event: MessageEvent) =>
      event.data match {
        case text: String => println(s"Text: $text")
        case other        => println(s"Binary: $other")
      }
    }
    ws.onerror = { (_: Event) => done.tryFailure(new Exception("WebSocket error")) }
    ws.onclose = { (event: CloseEvent) => println(s"Closed [${event.code}] \"${event.reason}\""); done.trySuccess(()) }
    done.future
  }
}

MoonBit

MoonBit uses the low-level WIT interface directly through generated bindings. Assuming your generated golem:websocket bindings are imported as @websocket_client and the common agent types are imported as @common:


pub async fn ExampleAgent::run(self: Self) -> Unit raise @common.AgentError {
  let conn = match @websocket_client.WebsocketConnection::connect("wss://example.com/chat", None) {
    Ok(c) => c
    Err(e) => raise @common.AgentError::InvalidInput("Connect failed: \{Repr(e)}")
  }
  println("Connected")
  match conn.send(Text("Hello, server!")) {
    Ok(_) => ()
    Err(e) => raise @common.AgentError::InvalidInput("Send failed: \{Repr(e)}")
  }
  // receive loop...
}

WIT interface reference

The underlying package is golem:websocket@1.5.0; its golem:websocket/client@1.5.0 interface defines the websocket-connection resource type with the following methods:

connect — opens a WebSocket connection to the given URL, with optional headers
send — sends a text or binary message
receive — asynchronously waits for the next message
receive-with-timeout — waits up to the given number of milliseconds and returns none on expiry
close — initiates a graceful close handshake