stratus

Types

Builder

pub opaque type Builder(state, user_message)

Connection

</>

This holds some information needed to communicate with the WebSocket.

pub opaque type Connection

InternalMessage

</>

These are the messages emitted or received by the underlying process. You should only need to interact with Message below.

pub opaque type InternalMessage(user_message)

Message

</>

This is the type of message your handler might receive.

pub type Message(user_message) {
  Text(String)
  Binary(BitArray)
  User(user_message)
}

Constructors

```
Text(String)
```
```
Binary(BitArray)
```
```
User(user_message)
```

Functions

close

</>

pub fn close(conn: Connection) -> Result(Nil, SocketReason)

This will close the WebSocket connection.

initialize

</>

pub fn initialize(
  builder: Builder(a, b),
) -> Result(Subject(InternalMessage(b)), StartError)

This opens the WebSocket connection with the provided Builder. It makes some assumptions about the request if you do not provide it. It will use

It will open the connection and perform the WebSocket handshake. If this fails, the actor will fail to start with the given reason as a string value.

After that, received messages will be passed to your loop, and you can use the helper functions to send messages to the server. The close method will send a close frame and end the connection.

on_close

</>

pub fn on_close(
  builder: Builder(a, b),
  on_close: fn(a) -> Nil,
) -> Builder(a, b)

You can provide a function to be called when the connection is closed. This function receives the last value for the state of the WebSocket.

NOTE: If you manually call stratus.close, this function will not be called. I’m unsure right now if this is a bug or working as intended. But you will be in the loop with the state value handy.

send_binary_message

</>

pub fn send_binary_message(
  conn: Connection,
  msg: BitArray,
) -> Result(Nil, SocketReason)

From within the actor loop, this is how you send a WebSocket text frame.

send_message

</>

pub fn send_message(
  subject: Subject(InternalMessage(a)),
  message: a,
) -> Nil

Since the actor receives the raw data from the WebSocket, it needs a less ergonomic message type. You probably don’t want (read: shouldn’t be able to) send Data(bits) to the process, so that message type is opaque.

To get around that, this helper method lets you provide your custom message type to the actor.

This is likely what you want if you want to be able to tell the actor to send data to the server. Your message type would be – in plain language – “this thing happened”, and your loop would then send whatever relevant data corresponds to that event.

send_text_message

</>

pub fn send_text_message(
  conn: Connection,
  msg: String,
) -> Result(Nil, SocketReason)

From within the actor loop, this is how you send a WebSocket text frame. This must be valid UTF-8, so it is a String.

websocket

</>

pub fn websocket(
  request req: Request(String),
  init init: fn() -> #(a, Option(Selector(b))),
  loop loop: fn(Message(b), a, Connection) -> Next(b, a),
) -> Builder(a, b)

This creates a builder to set up a WebSocket actor. This will use default values for the connection initialization timeout, and provide an empty function to be called when the server closes the connection. If you want to customize either of those, see the helper functions with_init_timeout and on_close.

with_init_timeout

</>

pub fn with_init_timeout(
  builder: Builder(a, b),
  timeout: Int,
) -> Builder(a, b)

The WebSocket actor will attempt to connect to the server when you call initialize. It will also call your init function. This timeout serves as the upper bound for all of these actions. The default is 5 seconds.