collie

Types

Builder

opaque </>

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

pub opaque type Builder(body, state, message, return)

CloseCode

</>

WebSocket status codes that may appear in a close frame.

The codes reserved for local use only, such as 1005, 1006 and 1015, are absent. They must never be sent, and receiving one is a protocol violation.

pub type CloseCode {
  NormalClosure
  GoingAway
  ProtocolError
  UnsupportedData
  InvalidPayloadData
  PolicyViolation
  MessageTooBig
  MandatoryExtension
  InternalError
  ServiceRestart
  TryAgainLater
  BadGateway
  ApplicationCode(code: Int)
}

Constructors

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

CloseReason

</>

Why the connection is closing. A close frame is allowed to carry neither code nor reason.

pub type CloseReason {
  NoCloseReason
  CloseReason(code: CloseCode, reason: String)
}

Constructors

```
NoCloseReason
```
A close frame with an empty payload.
```
CloseReason(code: CloseCode, reason: String)
```
A close frame carrying a status code and a description. The description must not exceed 123 bytes.

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, selecting and returning functions to construct this type.

pub opaque type Initialised(state, message, return)

Limits

</>

Caps on how much data the server can make this client hold at once. Without them a server can declare an arbitrarily large frame, or fragment a single message indefinitely, and exhaust memory.

pub type Limits {
  Limits(max_frame_size: Int, max_message_size: Int)
}

Constructors

```
Limits(max_frame_size: Int, max_message_size: Int)
```
Arguments

max_frame_size

Largest payload a single frame may declare.

max_message_size

Largest payload a fragmented message may accumulate to.

Message

</>

Represents a message the websocket actor can receive.

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_code_to_string

</>

pub fn close_code_to_string(code: CloseCode) -> String

Converts a close code to a human-readable string.

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.

default_limits

</>

pub const default_limits: Limits

16 MiB per frame, 64 MiB per reassembled message. Use the with_limits function to override them.

factory

</>

pub fn factory(
  build: fn(start_args) -> Builder(body, state, message, return),
) -> factory_supervisor.Builder(start_args, return)

Returns a factory supervisor builder for dynamically starting WebSocket connections.

initialised

</>

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

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, return),
  name: process.Name(WebsocketMessage(message)),
) -> Builder(body, state, message, return)

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,
  process.Subject(WebsocketMessage(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, return),
    String,
  ),
) -> Builder(body, state, message, return)

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, return),
  on_close: fn(state, CloseReason) -> Nil,
) -> Builder(body, state, message, return)

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, return),
  handler: fn(Connection, state, Message(message)) -> Next(
    state,
    message,
  ),
) -> Builder(body, state, message, return)

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.

returning

</>

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

Adds the data to return to the parent process.

selecting

</>

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

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,
) -> Result(Nil, SocketReason)

Sends a close frame to the WebSocket server. Once called, no other frames can be sent on this connection. Stop the actor after calling this.

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, return),
) -> Result(actor.Started(return), 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, return),
) -> supervision.ChildSpecification(return)

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, return),
  connection_timeout: Int,
) -> Builder(body, state, message, return)

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.

with_limits

</>

pub fn with_limits(
  builder: Builder(body, state, message, return),
  limits: Limits,
) -> Builder(body, state, message, return)

Sets the caps on how much data a single frame and a single reassembled message may hold. A server that exceeds them closes the connection with MessageTooBig. Defaults to default_limits.

Constructors

Constructors

Constructors

Arguments

Constructors

Constructors