socket

Types

ConnectError

Why opening a socket didn’t work.

pub type ConnectError {
  HttpError(status: Int)
  Timeout
  Network(reason: String)
}

Constructors

```
HttpError(status: Int)
```
The gateway refused the upgrade with this HTTP status: 401 for a token it doesn’t know, 503 while it can’t check tokens yet.
```
Timeout
```
Opening took longer than the connect timeout.
```
Network(reason: String)
```
No network, a dropped connection, or another failure below HTTP.

Event

</>

What the socket tells its owner.

pub type Event {
  Opened
  OpenFailed(error: ConnectError)
  Frames(frames: List(Frame))
  SocketError(reason: String)
}

Constructors

```
Opened
```
The upgrade is done: the socket can send.
```
OpenFailed(error: ConnectError)
```
It didn’t open.
```
Frames(frames: List(Frame))
```
The frames of one read, in the order the gateway wrote them. Frames written in one burst come in one of these, so the order between them is kept as a single unit.
```
SocketError(reason: String)
```
The socket failed below the WebSocket protocol.

Frame

</>

One frame of the gateway’s, as it came.

pub type Frame {
  TextFrame(String)
  BinaryFrame(BitArray)
  CloseFrame(code: Int, reason: String)
  SocketClosed
  Ping
  Pong
}

Constructors

```
TextFrame(String)
```
A text frame: every event the gateway sends is one of these, as JSON.
```
BinaryFrame(BitArray)
```
A binary frame, which the gateway doesn’t send today.
```
CloseFrame(code: Int, reason: String)
```
The gateway closed the socket, saying why.
```
SocketClosed
```
The socket closed without a close frame.
```
Ping
```
```
Pong
```

Socket

opaque </>

A WebSocket socket to the gateway, owned by a process of its own that forwards what it reads to [events]. The owner stops, closing the socket, when the process that created the socket exits.

pub opaque type Socket

Tagged

</>

An event with the socket it came from, so that one reader can follow several sockets in turn and ignore a socket it has given up on.

pub type Tagged {
  Tagged(pid: process.Pid, event: Event)
}

Constructors

```
Tagged(pid: process.Pid, event: Event)
```

Values

close

</>

pub fn close(socket: Socket) -> Nil

Closes the socket, as the protocol asks.

events

</>

pub fn events(socket: Socket) -> process.Subject(Tagged)

kill

</>

pub fn kill(socket: Socket) -> Nil

Drops the socket at once: what a connect timeout does to an attempt that hasn’t opened yet.

next_event

</>

pub fn next_event(
  socket: Socket,
  timeout_ms: Int,
) -> Result(Event, Nil)

The next event of this socket, if one comes within [timeout_ms], dropping the events of any other socket that share [events].

pid

</>

pub fn pid(socket: Socket) -> process.Pid

send

</>

pub fn send(socket: Socket, text: String) -> Bool

Sends one text frame: whether it went out.

start

</>

pub fn start(
  url: String,
  headers: List(#(String, String)),
  timeout_ms: Int,
  events: process.Subject(Tagged),
) -> Socket

Starts opening a socket; what happens comes on [events]. [timeout_ms] bounds each wait at the socket level; the caller bounds the whole upgrade itself with [kill].