donut

Donut helps you talk to websockets from your Lustre application. Connection events become messages you already know how to respond to. It’s designed to integrate seamlessly with Lustre’s simulate module, so you can test that logic without a real connection.

Types

CloseCode

</>

Emitted with the Closed event indicating the reason the connection was closed.

pub type CloseCode {
  Normal
  GoingAway
  ProtocolError
  UnexpectedTypeOfData
  NoCodeFromServer
  AbnormalClose
  IncomprehensibleFrame
  PolicyViolated
  MessageTooBig
  UnexpectedFailure
  ServiceRestart
  TryAgainLater
  BadGateway
  FailedTLSHandshake
  ApplicationCode(code: Int)
  UnrecognizedCode(code: Int)
}

Constructors

```
Normal
```
Code 1000: The purpose of the connection was fulfilled.
```
GoingAway
```
Code 1001: The endpoint is going away because the server is shutting down.
```
ProtocolError
```
Code 1002: The server received a message that violates its protocol. Invalid frame, bad data format, etc.
```
UnexpectedTypeOfData
```
Code 1003: The server received a type of data it cannot accept.
```
NoCodeFromServer
```
Code 1005: Synthesized by the browser when no close code was sent.
```
AbnormalClose
```
Code 1006: Synthesized by the browser when the connection was abruptly severed without the server sending a close frame.
```
IncomprehensibleFrame
```
Code 1007: Received data within a message that was not consistent with the type of the message (e.g. non-UTF8 data within a text message).
```
PolicyViolated
```
Code 1008: The server received a message that violates its policy.
```
MessageTooBig
```
Code 1009: The server received a message that is too big for it to process.
```
UnexpectedFailure
```
Code 1011: The server encountered an unexpected condition that prevented it from fulfilling the request.
```
ServiceRestart
```
Code 1012: The server is restarting and clients may reconnect shortly.
```
TryAgainLater
```
Code 1013: The server is overloaded and clients should retry later.
```
BadGateway
```
Code 1014: The server acting as a gateway received an invalid response from the upstream server.
```
FailedTLSHandshake
```
Code 1015: Synthesized by the browser when the connection was closed due to a failure to perform a TLS handshake.
```
ApplicationCode(code: Int)
```
Code 3000-4999: Application specific code.
```
UnrecognizedCode(code: Int)
```
Any close code not recognized by this package. Could be invalid, new code added by the spec, etc.

Event

</>

The lifecycle events a websocket connection can produce.

pub type Event {
  FailedToInitialize
  Opened(handle: Handle)
  ReceivedMessage(handle: Handle, message: WebsocketMessage)
  Errored(handle: Handle)
  Closed(handle: Handle, code: CloseCode)
}

Constructors

```
FailedToInitialize
```
The connection failed to open. Malformed url, browser-blocked port, etc.
```
Opened(handle: Handle)
```
The connection was successfully opened.

ReceivedMessage(handle: Handle, message: WebsocketMessage)

The connection received a message from the server.

```
Errored(handle: Handle)
```
The connection errored out.
```
Closed(handle: Handle, code: CloseCode)
```
The connection was closed.

Handle

opaque </>

An opaque handle that maps to a websocket connection.

Storing a handle on your model instead of the connection directly keeps your model pure and testable.

pub opaque type Handle

WebsocketMessage

</>

The message type that can be sent or received on a websocket connection.

pub type WebsocketMessage {
  Text(data: String)
  Binary(data: BitArray)
}

Constructors

```
Text(data: String)
```
A UTF-8 text message.
```
Binary(data: BitArray)
```
A binary message.

Values

close

</>

pub fn close(handle: Handle) -> effect.Effect(msg)

Close the websocket connection identified by handle.

Does nothing if the connection doesn’t exist.

init

</>

pub fn init(
  url url: String,
  to_message to_message: fn(Event) -> msg,
) -> effect.Effect(msg)

Initialize a websocket connection.

send

</>

pub fn send(
  using handle: Handle,
  send message: WebsocketMessage,
) -> effect.Effect(msg)

Send a message over the websocket connection identified by handle.

Does nothing if the connection doesn’t exist or the connection’s ready state isn’t OPEN.

test_handle

</>

pub fn test_handle(
  for simulation: simulate.Simulation(model, message),
  using id: Int,
) -> Handle

Constructs a Handle for use in a simulation, letting tests simulate events from the server.

Takes a Simulation so this can’t accidentally be called outside a test context. Takes an id because there’s no id allocator in tests, it’s the caller’s responsibility to keep ids unique.