stratus

Types

Builder

opaque </>

pub opaque type Builder(state, user_message)

CloseReason

</>

pub type CloseReason {
  NotProvided
  Normal(body: BitArray)
  GoingAway(body: BitArray)
  ProtocolError(body: BitArray)
  UnexpectedDataType(body: BitArray)
  InconsistentDataType(body: BitArray)
  PolicyViolation(body: BitArray)
  MessageTooBig(body: BitArray)
  MissingExtensions(body: BitArray)
  UnexpectedCondition(body: BitArray)
  Custom(CustomCloseReason)
}

Constructors

```
NotProvided
```
```
Normal(body: BitArray)
```
Status code: 1000
```
GoingAway(body: BitArray)
```
Status code: 1001
```
ProtocolError(body: BitArray)
```
Status code: 1002
```
UnexpectedDataType(body: BitArray)
```
Status code: 1003
```
InconsistentDataType(body: BitArray)
```
Status code: 1007
```
PolicyViolation(body: BitArray)
```
Status code: 1008
```
MessageTooBig(body: BitArray)
```
Status code: 1009
```
MissingExtensions(body: BitArray)
```
Status code: 1010
```
UnexpectedCondition(body: BitArray)
```
Status code: 1011
```
Custom(CustomCloseReason)
```
Use close_custom to send a custom close code.

Connection

opaque </>

This holds some information needed to communicate with the WebSocket.

pub opaque type Connection

CustomCloseError

</>

pub type CustomCloseError {
  SocketFail(SocketReason)
  InvalidCode
}

Constructors

```
SocketFail(SocketReason)
```
```
InvalidCode
```

CustomCloseReason

opaque </>

Use close_custom to send a custom close code.

pub opaque type CustomCloseReason

HandshakeError

</>

pub type HandshakeError {
  Sock(SocketReason)
  Protocol(BitArray)
  UpgradeFailed(response.Response(BitArray))
}

Constructors

```
Sock(SocketReason)
```
```
Protocol(BitArray)
```

UpgradeFailed(response.Response(BitArray))

Initialised

</>

pub type Initialised(state, user_message) {
  Initialised(
    state: state,
    selector: option.Option(process.Selector(user_message)),
  )
}

Constructors

Initialised(
  state: state,
  selector: option.Option(process.Selector(user_message)),
)

InitializationError

</>

These are the possible failures when calling stratus.initialize.

pub type InitializationError {
  HandshakeFailed(HandshakeError)
  ActorFailed(actor.StartError)
  FailedToTransferSocket(SocketReason)
}

Constructors

```
HandshakeFailed(HandshakeError)
```
```
ActorFailed(actor.StartError)
```
```
FailedToTransferSocket(SocketReason)
```

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)
```

opaque </>

pub opaque type Next(state, user_message)

SocketReason

</>

pub type SocketReason {
  SocketClosed
  Timeout
  Badarg
  Terminated
  Eaddrinuse
  Eaddrnotavail
  Eafnosupport
  Ealready
  Econnaborted
  Econnrefused
  Econnreset
  Edestaddrreq
  Ehostdown
  Ehostunreach
  Einprogress
  Eisconn
  Emsgsize
  Enetdown
  Enetunreach
  Enopkg
  Enoprotoopt
  Enotconn
  Enotty
  Enotsock
  Eproto
  Eprotonosupport
  Eprototype
  Esocktnosupport
  Etimedout
  Ewouldblock
  Exbadport
  Exbadseq
}

Constructors

```
SocketClosed
```
```
Timeout
```
```
Badarg
```
```
Terminated
```
```
Eaddrinuse
```
```
Eaddrnotavail
```
```
Eafnosupport
```
```
Ealready
```
```
Econnaborted
```
```
Econnrefused
```
```
Econnreset
```
```
Edestaddrreq
```
```
Ehostdown
```
```
Ehostunreach
```
```
Einprogress
```
```
Eisconn
```
```
Emsgsize
```
```
Enetdown
```
```
Enetunreach
```
```
Enopkg
```
```
Enoprotoopt
```
```
Enotconn
```
```
Enotty
```
```
Enotsock
```
```
Eproto
```
```
Eprotonosupport
```
```
Eprototype
```
```
Esocktnosupport
```
```
Etimedout
```
```
Ewouldblock
```
```
Exbadport
```
```
Exbadseq
```

Values

close

</>

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

close_custom

</>

pub fn close_custom(
  conn: Connection,
  code code: Int,
  body body: BitArray,
) -> Result(Nil, CustomCloseError)

Closes the connection with a custom close code between 1000 and 4999.

continue

</>

pub fn continue(state: state) -> Next(state, user_message)

get_custom_body

</>

pub fn get_custom_body(reason: CustomCloseReason) -> BitArray

get_custom_code

</>

pub fn get_custom_code(reason: CustomCloseReason) -> Int

initialised

</>

pub fn initialised(
  state: state,
) -> Initialised(state, user_message)

new

</>

pub fn new(
  request req: request.Request(String),
  state state: state,
) -> Builder(state, user_message)

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

new_with_initialiser

</>

pub fn new_with_initialiser(
  request req: request.Request(String),
  init init: fn() -> Result(
    Initialised(state, user_message),
    String,
  ),
) -> Builder(state, user_message)

on_close

</>

pub fn on_close(
  builder: Builder(state, user_message),
  on_close: fn(state, CloseReason) -> Nil,
) -> Builder(state, user_message)

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_message

</>

pub fn on_message(
  builder: Builder(state, user_message),
  on_message: fn(state, Message(user_message), Connection) -> Next(
    state,
    user_message,
  ),
) -> Builder(state, user_message)

selecting

</>

pub fn selecting(
  initialised: Initialised(state, old_message),
  selector: process.Selector(user_message),
) -> Initialised(state, user_message)

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_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.

start

</>

pub fn start(
  builder: Builder(state, user_message),
) -> Result(
  actor.Started(process.Subject(InternalMessage(user_message))),
  InitializationError,
)

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.

stop

</>

pub fn stop() -> Next(state, user_message)

stop_abnormal

</>

pub fn stop_abnormal(reason: String) -> Next(state, user_message)

to_user_message

</>

pub fn to_user_message(
  user_message: user_message,
) -> InternalMessage(user_message)

The Subject returned from initialize is an opaque type. In order to send custom messages to your process, you can do this mapping.

For example:

  // using `process.send`
  MyMessage(some_data)
  |> stratus.to_user_message
  |> process.send(stratus_subject, _)
  // using `process.call`
  process.call(stratus_subject, fn(subj) {
    stratus.to_user_message(MyMessage(some_data, subj))
  })

with_connect_timeout

</>

pub fn with_connect_timeout(
  builder: Builder(state, user_message),
  timeout: Int,
) -> Builder(state, user_message)

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.

with_selector

</>

pub fn with_selector(
  next: Next(state, user_message),
  selector: process.Selector(user_message),
) -> Next(state, user_message)