stratus

Types

Builder

opaque </>

pub opaque type Builder(state, user_message)

Connection

opaque </>

This holds some information needed to communicate with the WebSocket.

pub opaque type Connection

InternalMessage

opaque </>

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 ports 80 or 443 for ws or wss respectively.

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.

on_handshake_error

</>

pub fn on_handshake_error(
  builder: Builder(a, b),
  on_handshake_error: fn(Response(BitArray)) -> Nil,
) -> Builder(a, b)

If the WebSocket handshake fails, this method will be called with the response received from the server. The process will stop after this.

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_ping

</>

pub fn send_ping(
  conn: Connection,
  data: BitArray,
) -> Result(Nil, SocketReason)

Send a ping frame with some data.

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_connect_timeout

with_connect_timeout

</>

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

This sets the maximum amount of time you are willing to wait for both connecting to the server and receiving the upgrade response. This means that it may take up to timeout * 2 to begin sending or receiving messages. This value defaults to 5 seconds.