stratocumulus

Types

Builder

opaque </>

Builders are used to construct the desired WebSocket. Use new, protocols and open to create your Builder and opening your WebSocket.

pub opaque type Builder

CloseError

</>

Possible errors that can be received after calling close.

pub type CloseError {
  InvalidAccessError
  ReasonSyntaxError
}

Constructors

```
InvalidAccessError
```
code is neither an integer equal to 1000 nor an integer in the range 3000 – 4999.
```
ReasonSyntaxError
```
The UTF-8-encoded reason value is longer than 123 bytes.

OpenError

</>

pub type OpenError {
  OpenSyntaxError
}

Constructors

```
OpenSyntaxError
```
Happens when
- uri has a scheme other than ws, wss, http, or https
- uri has a fragment
- any of the values in protocols occur more than once, or otherwise fail to match the requirements for elements that comprise the value of Sec-WebSocket-Protocol fields as defined by the WebSocket Protocol specification

ReadyState

</>

State of the WebSocket. A WebSocket is always in one of those four states.

pub type ReadyState {
  Connecting
  Open
  Closing
  Closed
}

Constructors

```
Connecting
```
Socket has been created. The connection is not yet open.
```
Open
```
The connection is open and ready to communicate.
```
Closing
```
The connection is in the process of closing.
```
Closed
```
The connection is closed or couldn’t be opened.

SendError

</>

Possible errors that can be received after calling send or send_bytes.

pub type SendError {
  InvalidStateError
}

Constructors

```
InvalidStateError
```
Thrown if ready_state is Connecting.

WebSocket

</>

pub type WebSocket

Values

buffered_amount

</>

pub fn buffered_amount(websocket: WebSocket) -> Int

Return the number of bytes of data that have been queued using calls to send but not yet transmitted to the network. This value resets to zero once all queued data has been sent. This value does not reset to zero when the connection is closed; if you keep calling send, this will continue to climb.

close

</>

pub fn close(
  websocket: WebSocket,
  code code: Int,
  reason reason: String,
) -> Result(Nil, CloseError)

Close an opened WebSocket.

let assert Ok(endpoint) = uri.parse("...")
let assert Ok(ws) = stratocumulus.new(endpoint) |> stratocumulus.open
let assert Ok(_) = stratocumulus.close(ws, code: 1000, reason: "normal")

extensions

</>

pub fn extensions(websocket: WebSocket) -> String

Return the extensions selected by the server. This is currently only the empty string or a list of extensions as negotiated by the connection.

new

</>

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

Init a new WebSocket Builder. A Builder is the equivalent of a blueprint, on which we can spawn an infinite amount of WebSockets.

let assert Ok(endpoint) = uri.parse("...")
let assert Ok(ws) = stratocumulus.new(endpoint) |> stratocumulus.open
let assert Ok(_) = stratocumulus.send(ws, "Hello world!")

on_bytes

</>

pub fn on_bytes(
  builder: Builder,
  on_bytes: fn(BitArray, dynamic.Dynamic) -> Nil,
) -> Builder

Subscribe to bytes messages received. Everytime the WebSocket receives a binary message, an event is received with the bytes as content. The second argument is the event itself, in case it is needed for other usages.

let assert Ok(endpoint) = uri.parse("...")
stratocumulus.new(endpoint)
|> stratocumulus.on_open(fn (data) { Nil })
|> stratocumulus.on_close(fn (data) { Nil })
|> stratocumulus.on_error(fn (data) { Nil })
|> stratocumulus.on_bytes(fn (content: BitArray, event) { Nil })

on_close

</>

pub fn on_close(
  builder: Builder,
  on_close: fn(dynamic.Dynamic) -> Nil,
) -> Builder

Subscribe to the "close" event. "close" will be emitted after the Socket has been closed with the remote server. The argument received is a CloseEvent. on_close returns the original WebSocket to continue chaining commands on the WebSocket.

let assert Ok(endpoint) = uri.parse("...")
stratocumulus.new(endpoint)
|> stratocumulus.on_open(fn (data) { Nil })
|> stratocumulus.on_close(fn (data) { Nil })
|> stratocumulus.on_error(fn (data) { Nil })

on_error

</>

pub fn on_error(
  builder: Builder,
  on_error: fn(dynamic.Dynamic) -> Nil,
) -> Builder

Subscribe to the "error" event. "error" will be emitted when an error has occur, like some data that could not be sent. The argument received is a generic Event. on_error returns the original WebSocket to continue chaining commands on the WebSocket.

let assert Ok(endpoint) = uri.parse("...")
stratocumulus.new(endpoint)
|> stratocumulus.on_open(fn (data) { Nil })
|> stratocumulus.on_close(fn (data) { Nil })
|> stratocumulus.on_error(fn (data) { Nil })

on_open

</>

pub fn on_open(
  builder: Builder,
  on_open: fn(dynamic.Dynamic) -> Nil,
) -> Builder

Subscribe to the "open" event. "open" will be emitted after the Socket has been opened with the remote server. The argument received is a generic Event. on_open returns the original WebSocket to continue chaining commands on the WebSocket.

let assert Ok(endpoint) = uri.parse("...")
stratocumulus.new(endpoint)
|> stratocumulus.on_open(fn (data) { Nil })
|> stratocumulus.on_close(fn (data) { Nil })
|> stratocumulus.on_error(fn (data) { Nil })

on_text

</>

pub fn on_text(
  builder: Builder,
  on_text: fn(String, dynamic.Dynamic) -> Nil,
) -> Builder

Subscribe to text messages received. Everytime the WebSocket receives a textual message, an event is received with the text as content. The second argument is the event itself, in case it is needed for other usages.

let assert Ok(endpoint) = uri.parse("...")
stratocumulus.new(endpoint)
|> stratocumulus.on_open(fn (data) { Nil })
|> stratocumulus.on_close(fn (data) { Nil })
|> stratocumulus.on_error(fn (data) { Nil })
|> stratocumulus.on_text(fn (content: String, event) { Nil })

open

</>

pub fn open(builder: Builder) -> Result(WebSocket, OpenError)

Create & open the WebSocket from its Builder. This is the equivalent to creating the WebSocket with new WebSocket in JavaScript.

let assert Ok(endpoint) = uri.parse("...")
stratocumulus.new(endpoint)
|> stratocumulus.protocols(["soap"])
|> stratocumulus.open

protocol

</>

pub fn protocol(websocket: WebSocket) -> String

Return the name of the sub-protocol the server selected; this will be one of the strings specified in the protocols parameter when creating the WebSocket, or the empty string if no connection is established.

protocols

</>

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

A single string or an array of strings representing the sub-protocol(s) that the client would like to use, in order of preference. If it is omitted, an empty list is used by default, i.e., [].

A single server can implement multiple WebSocket sub-protocols, and handle different types of interactions depending on the specified value. Note however that only one sub-protocol can be selected per connection.

The allowed values are those that can be specified in the Sec-WebSocket-Protocol HTTP header. These are values selected from the IANA WebSocket Subprotocol Name Registry, such as soap, wamp, ship and so on, or may be a custom name jointly understood by the client and the server.

MDN Reference

let assert Ok(endpoint) = uri.parse("...")
stratocumulus.new(endpoint)
|> stratocumulus.protocols(["soap"])
|> stratocumulus.open

ready_state

</>

pub fn ready_state(websocket: WebSocket) -> ReadyState

Return the current state of the WebSocket connection.

send

</>

pub fn send(
  ws: WebSocket,
  content: String,
) -> Result(WebSocket, SendError)

Send a text frame on the WebSocket. The WebSocket will be returned on success. An error will be returned in case the WebSocket state is Connecting.

let assert Ok(endpoint) = uri.parse("...")
let assert Ok(ws) = stratocumulus.new(endpoint) |> stratocumulus.open
let assert Ok(_) = stratocumulus.send(ws, "Hello world!")

send_bytes

</>

pub fn send_bytes(
  websocket: WebSocket,
  content: BitArray,
) -> Result(WebSocket, SendError)

Send a binary frame on the WebSocket. The WebSocket will be returned on success. An error will be returned in case the WebSocket state is Connecting.

let assert Ok(endpoint) = uri.parse("...")
let assert Ok(ws) = stratocumulus.new(endpoint) |> stratocumulus.open
let assert Ok(_) = stratocumulus.send(ws, <<"Hello world!">>)

uri

</>

pub fn uri(websocket: WebSocket) -> uri.Uri

Return the absolute URI of the WebSocket as resolved by the WebSocket itself.