gossamer/web_socket

Bidirectional, message-oriented WebSocket connections (ws: and wss:). Construct via new; lifecycle events arrive as WebSocketEvent variants, dispatched by the handler registered via with_on_event.

Types

Builder

opaque </>

The configuration for a WebSocket.

pub opaque type Builder

CloseEvent

</>

The data carried by a WebSocket close event.

pub type CloseEvent {
  CloseEvent(code: Int, reason: String, clean: Bool)
}

Constructors

CloseEvent(code: Int, reason: String, clean: Bool)

Info

</>

A snapshot of the handshake-time fields of a WebSocket, returned by info. For the dynamic fields that change over the connection’s lifecycle, use ready_state and buffered_amount directly.

pub type Info {
  Info(url: String, protocol: String, extensions: String)
}

Constructors

```
Info(url: String, protocol: String, extensions: String)
```
Arguments

url

The URL the socket is connected to.

protocol

The sub-protocol selected by the server during the handshake, or "" if none was negotiated.

extensions

The extensions selected by the server, or "" if none.

ReadyState

</>

The state of a WebSocket connection.

pub type ReadyState {
  Connecting
  Open
  Closing
  Closed
}

Constructors

```
Connecting
```
The handshake is in progress.
```
Open
```
The connection is open and messages can flow.
```
Closing
```
close has been called; the closing handshake is in progress.
```
Closed
```
The connection has closed.

WebSocket

</>

A bidirectional, message-oriented network connection to a server.

See WebSocket on MDN.

pub type WebSocket

WebSocketError

</>

Errors raised by WebSocket operations.

pub type WebSocketError {
  InvalidUrl
  InvalidProtocols
  InvalidCloseCode(code: Int)
  CloseReasonTooLong
  NotOpen
}

Constructors

```
InvalidUrl
```
The URL is not an absolute ws:, wss:, http:, or https: URL, or includes a fragment.
```
InvalidProtocols
```
The protocols list contains duplicates or values that aren’t valid HTTP header field tokens (per RFC 7230).
```
InvalidCloseCode(code: Int)
```
The close code is not 1000 and not in the range 3000–4999.
```
CloseReasonTooLong
```
The close reason exceeds 123 bytes when encoded as UTF-8.
```
NotOpen
```
A send_* call was made while the socket is in the Connecting state. Data sent on Closing or Closed sockets is silently discarded per spec and does not produce this error.

WebSocketEvent

</>

An event delivered to the handler registered via with_on_event.

pub type WebSocketEvent {
  Opened
  Text(String)
  Binary(BitArray)
  Errored
  Disconnected(event: CloseEvent)
}

Constructors

```
Opened
```
The connection was established and is ready to send and receive.
```
Text(String)
```
A text message arrived from the server.
```
Binary(BitArray)
```
A binary message arrived from the server.
```
Errored
```
A transport-level failure occurred. The WebSocket error event carries no usable payload per spec.
```
Disconnected(event: CloseEvent)
```
The connection closed. The event carries the close code, the reason string, and whether the close was clean.

Values

buffered_amount

</>

pub fn buffered_amount(socket: WebSocket) -> Int

The number of bytes of application data (UTF-8 text and binary data) that have been queued using send_* but not yet been transmitted to the network. Changes as messages queue and flush, so re-read this value rather than caching it.

If the WebSocket connection is closed, this attribute’s value will only increase with each call to a send_* method. (The number does not reset to zero once the connection closes.)

build

</>

pub fn build(
  builder: Builder,
) -> Result(WebSocket, WebSocketError)

Opens the WebSocket connection from the configured Builder. An http: or https: URL connects over ws: or wss: respectively. Returns Error(InvalidUrl) when the URL isn’t an absolute ws:, wss:, http:, or https: URL or contains a fragment, and Error(InvalidProtocols) when the protocols list has duplicates or non-token entries.

close

</>

pub fn close(socket: WebSocket) -> Nil

Closes the WebSocket connection with the default code 1000 and no reason. Does nothing if the connection is already closing or closed. For custom code or reason, use close_with.

close_with

</>

pub fn close_with(
  socket: WebSocket,
  code code: Int,
  reason reason: String,
) -> Result(Nil, WebSocketError)

Closes the WebSocket connection with the given code and reason. Returns Error(InvalidCloseCode(code)) if code is outside 1000 or the range 3000–4999, or Error(CloseReasonTooLong) if reason exceeds 123 bytes when encoded as UTF-8.

info

</>

pub fn info(socket: WebSocket) -> Info

A snapshot of the socket’s URL, negotiated sub-protocol, and server extensions. These fields are fixed once the handshake completes. For sockets built from http:/https: URLs, Bun keeps the original scheme in url where Node.js and Deno report the normalized ws:/wss: URL.

new

</>

pub fn new(uri: uri.Uri) -> Builder

Creates a Builder for a WebSocket connection to uri. Protocols default to [] (no negotiation), and the event handler is unset.

ready_state

</>

pub fn ready_state(socket: WebSocket) -> ReadyState

The current state of the connection. Changes through Connecting → Open → Closing → Closed over the connection’s lifecycle, so re-read this value rather than caching it.

send_binary

</>

pub fn send_binary(
  socket: WebSocket,
  data: BitArray,
) -> Result(Nil, WebSocketError)

Sends a binary frame through the WebSocket. Returns Error(NotOpen) if the connection is still Connecting. Data sent after the connection is Closing or Closed is silently discarded per spec. Equivalent to JavaScript’s WebSocket.send with an ArrayBuffer argument.

send_blob

</>

pub fn send_blob(
  socket: WebSocket,
  data: blob.Blob,
) -> Result(Nil, WebSocketError)

Sends a Blob through the WebSocket. Returns Error(NotOpen) if the connection is still Connecting. Data sent after the connection is Closing or Closed is silently discarded per spec. Equivalent to JavaScript’s WebSocket.send with a Blob argument.

send_text

</>

pub fn send_text(
  socket: WebSocket,
  data: String,
) -> Result(Nil, WebSocketError)

Sends a text frame through the WebSocket. Returns Error(NotOpen) if the connection is still Connecting. Data sent after the connection is Closing or Closed is silently discarded per spec. Equivalent to JavaScript’s WebSocket.send with a String argument.

with_on_event

</>

pub fn with_on_event(
  builder: Builder,
  handler: fn(WebSocketEvent, WebSocket) -> a,
) -> Builder

Registers a handler invoked for every connection event: Opened, Text, Binary, Errored, Disconnected. The handler also receives the WebSocket so it can reply via send_* while dispatching on the WebSocketEvent.

with_protocols

</>

pub fn with_protocols(
  builder: Builder,
  protocols: List(String),
) -> Builder

Sets the sub-protocols offered during the WebSocket handshake. Pass [] to skip protocol negotiation.

Constructors

Constructors

Arguments

Constructors

Constructors

Constructors