collie

Types

Builder

opaque </>

Contains all client configurations, can be adjusted by different builder functions.

pub opaque type Builder(body, state, message)

CloseReason

</>

WebSocket close codes that can be sent when closing a connection. The data parameter allows you to include payload up to 123 bytes in size.

pub type CloseReason {
  NormalClosure(data: BitArray)
  GoingAway(data: BitArray)
  ProtocolError(data: BitArray)
  UnsupportedData(data: BitArray)
  InvalidPayloadData(data: BitArray)
  PolicyViolation(data: BitArray)
  MessageTooBig(data: BitArray)
  MandatoryExtension(data: BitArray)
  InternalError(data: BitArray)
  ServiceRestart(data: BitArray)
  TryAgainLater(data: BitArray)
  BadGateway(data: BitArray)
  TLSHandshake(data: BitArray)
  CustomCloseCode(code: Int, data: BitArray)
  NoCloseReason
}

Constructors

```
NormalClosure(data: BitArray)
```
The connection successfully completed its purpose and is closing normally.
```
GoingAway(data: BitArray)
```
The endpoint is going away, either due to server shutdown or browser navigation.
```
ProtocolError(data: BitArray)
```
A WebSocket protocol violation was detected.
```
UnsupportedData(data: BitArray)
```
The endpoint received data it cannot accept.
```
InvalidPayloadData(data: BitArray)
```
The message data doesn’t match the declared type.
```
PolicyViolation(data: BitArray)
```
Generic status for policy violations when no other code applies.
```
MessageTooBig(data: BitArray)
```
Message exceeds the maximum size the endpoint can handle.
```
MandatoryExtension(data: BitArray)
```
The server encountered an unexpected condition preventing request fulfillment.
```
InternalError(data: BitArray)
```
The server encountered an unexpected error.
```
ServiceRestart(data: BitArray)
```
Server is restarting.
```
TryAgainLater(data: BitArray)
```
Temporary server overload.
```
BadGateway(data: BitArray)
```
Gateway/proxy received invalid response.
```
TLSHandshake(data: BitArray)
```
TLS/SSL handshake failure.
```
CustomCloseCode(code: Int, data: BitArray)
```
Custom close codes for application-specific use cases.
```
NoCloseReason
```
No close reason.

Connection

opaque </>

Represents a WebSocket connection between a client and a server.

pub opaque type Connection

Initialised

opaque </>

A type returned from the initialiser, containing the WebSocket state and a selector to receive messages with.

Use initialised and selecting functions to construct this type.

pub opaque type Initialised(state, message)

Message

</>

Represents a WebSocket message received from the server.

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

Constructors

```
Text(String)
```
Indicates that text frame has been received.
```
Binary(BitArray)
```
Indicates that binary frame has been received.
```
User(message)
```
Indicates that user message has been received from WebSocket selector.

opaque </>

Represents an instruction on how WebSocket connection should proceed.

continue processing the WebSocket connection.
continue processing the WebSocket connection with selector for custom messages.
stop the WebSocket connection.
stop the WebSocket connection with abnormal reason.

pub opaque type Next(state, message)

SocketReason

</>

Error codes that can occur during socket operations such as connecting, sending, or receiving data.

pub type SocketReason {
  Closed
  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

```
Closed
```
Connection was closed by the remote peer.
```
Timeout
```
Operation exceeded the specified timeout.
```
Badarg
```
Invalid argument provided to socket operation.
```
Terminated
```
Process was terminated.
```
Eaddrinuse
```
Address is already in use.
```
Eaddrnotavail
```
Requested address is not available.
```
Eafnosupport
```
Address family is not supported.
```
Ealready
```
Connection attempt is already in progress.
```
Econnaborted
```
Connection was aborted by the system.
```
Econnrefused
```
Connection was refused by the remote host.
```
Econnreset
```
Connection was reset by the remote peer.
```
Edestaddrreq
```
Destination address is required.
```
Ehostdown
```
Remote host is down.
```
Ehostunreach
```
Remote host is unreachable.
```
Einprogress
```
Operation is currently in progress.
```
Eisconn
```
Socket is already connected.
```
Emsgsize
```
Message size is too large.
```
Enetdown
```
Network is down.
```
Enetunreach
```
Network is unreachable.
```
Enopkg
```
Required package is not installed.
```
Enoprotoopt
```
Protocol option is not available.
```
Enotconn
```
Socket is not connected.
```
Enotty
```
Inappropriate I/O control operation.
```
Enotsock
```
File descriptor is not a socket.
```
Eproto
```
Protocol error occurred.
```
Eprotonosupport
```
Protocol is not supported.
```
Eprototype
```
Protocol type is incorrect for socket.
```
Esocktnosupport
```
Socket type is not supported.
```
Etimedout
```
Connection attempt timed out.
```
Ewouldblock
```
Operation would block in non-blocking mode.
```
Exbadport
```
Invalid port number.
```
Exbadseq
```
Invalid sequence number.

WebsocketMessage

opaque </>

Messages received by the underlying actor. This type is exposed so users are allowed to send custom messages. See to_user_message to construct it.

pub opaque type WebsocketMessage(message)

Values

close_reason_to_string

</>

pub fn close_reason_to_string(reason: CloseReason) -> String

Converts a close reason to a human-readable string.

continue

</>

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

Instructs WebSocket connection to continue processing.

continue_with_selector

</>

pub fn continue_with_selector(
  state: state,
  selector: process.Selector(message),
) -> Next(state, message)

Instructs WebSocket connection to continue processing, with selector for custom messages. New selector replaces any existing one that was previously given.

initialised

</>

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

Takes the post-initialisation state. This state will be passed to the on_message callback each time the message is received.

named

</>

pub fn named(
  builder: Builder(body, state, message),
  name: process.Name(WebsocketMessage(message)),
) -> Builder(body, state, message)

Provides a name for the client actor to be registered, enabling it to receive messages via a named subject.

new

</>

pub fn new(
  request: request.Request(body),
  state: state,
) -> Builder(body, state, message)

Creates a new builder to set up WebSocket client with default configuration without a custom initialiser. Use new_with_initialiser to create a builder with some initialisation logic that runs before the client starts handling messages.

new_with_initialiser

</>

pub fn new_with_initialiser(
  request: request.Request(body),
  initialise: fn(process.Subject(WebsocketMessage(message))) -> Result(
    Initialised(state, message),
    String,
  ),
) -> Builder(body, state, message)

Creates a new builder to set up WebSocket client with a custom initialiser that runs before the client starts handling messages.

The actor’s default subject is passed to the initialiser function. You can use it to send custom messages via to_user_message or ignore it completely.

If a custom selector is given using the selecting function, this expands the default selector to handle custom messages.

on_close

</>

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

Sets the handler that is called when the connection is closed. The callback accepts the last value for the state and the closing reason.

on_message

</>

pub fn on_message(
  builder: Builder(body, state, message),
  handler: fn(Connection, state, Message(message)) -> Next(
    state,
    message,
  ),
) -> Builder(body, state, message)

Sets the message handler for the client. The callback function will be called each time the client receives a message. It must return an instruction on how the WebSocket connection should proceed.

selecting

</>

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

Adds a selector to receive messages with.

send_binary_frame

</>

pub fn send_binary_frame(
  conn: Connection,
  bits: BitArray,
) -> Result(Nil, SocketReason)

Sends a binary frame to the WebSocket server.

send_close_frame

</>

pub fn send_close_frame(
  conn: Connection,
  reason: CloseReason,
) -> Next(state, message)

Sends a close frame to the websocket client. Once this function is called, no other frames can be sent on this connection. Returns how the WebSocket connection should proceed - make sure your handler returns this value.

send_ping

</>

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

Sends a ping frame to the WebSocket server.

send_text_frame

</>

pub fn send_text_frame(
  conn: Connection,
  text: String,
) -> Result(Nil, SocketReason)

Sends a text frame to the WebSocket server.

socket_reason_to_string

</>

pub fn socket_reason_to_string(reason: SocketReason) -> String

Converts a socket error to a human-readable string.

start

</>

pub fn start(
  builder: Builder(body, state, message),
) -> Result(
  actor.Started(process.Subject(WebsocketMessage(message))),
  actor.StartError,
)

Starts the WebSocket connection with the provided configurations.

stop

</>

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

Instructs WebSocket connection to stop.

stop_abnormal

</>

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

Instructs WebSocket connection to stop with abnormal reason.

supervised

</>

pub fn supervised(
  builder: Builder(body, state, message),
) -> supervision.ChildSpecification(
  process.Subject(WebsocketMessage(message)),
)

Returns a child specification for use in a supervision tree.

to_user_message

</>

pub fn to_user_message(
  message: message,
) -> WebsocketMessage(message)

Maps custom message to the WebsocketMessage opaque type, allowing to send custom messages to the client’s process.

with_connection_timeout

</>

pub fn with_connection_timeout(
  builder: Builder(body, state, message),
  connection_timeout: Int,
) -> Builder(body, state, message)

Sets the maximum amount of time for the handshake to happen in milliseconds. The initialiser function also has timeout + 1000 milliseconds to run. Default value is 5000.