Aquamarine

v0.1.0 Pre-1.0 package, not yet published to Hex. See the API overview or read the source on GitHub when you need exact signatures.

Aquamarine is the client runtime for Beryl-style WebSocket channels in Gleam. The socket lives in an OTP actor that owns the connection, so reconnect and reply correlation are the library's problem rather than yours — and the wire protocol stays behind a pluggable Codec.

Use the bundled aquamarine/phoenix codec for Phoenix Channels and Beryl, or provide your own codec without changing the channel runtime.

One actor, five moving parts

The public API stays small because the socket actor handles the recurring channel work after the connection opens.

1. connectOpen and joinStart the WebSocket, send the join frame, and wait for the matching reply.
2. refsCount in orderRefs are minted inside the actor, in the handler that sends the frame carrying them.
3. heartbeatKeep the connection aliveA timed self-message, running for the life of the socket rather than per channel.
4. push / receiveMove application framesInbound frames route by topic; replies correlate back to the push that asked.
5. reconnectCome back on its ownA dropped connection retries on a backoff and rejoins every topic. Your handles stay valid.

One typed error surface

Connect to a Phoenix-compatible endpoint and handle failures through the same AquamarineError variants returned by every fallible operation.

import aquamarine
import aquamarine/phoenix
import aquamarine/transport
import gleam/json

case aquamarine.connect(
  scheme: transport.Ws,
  host: "localhost",
  port: 4000,
  path: "/socket/websocket",
  topic: "room:lobby",
  payload: json.object([]),
  codec: phoenix.codec(),
) {
  Ok(channel) -> {
    // Push, receive, and close with the same Channel handle.
    use_channel(channel)
    Nil
  }

  Error(error) -> handle_connect_error(error)
}

See Error handling for the AquamarineError variants returned by connect, push, receive, and close.

Choose your next path

First connectionInstall Aquamarine, open a channel, push, receive, and close.Start here →

Runtime modelSockets, channels, ownership, routing, and cleanup.Read the lifecycle →

Phoenix and BerylUse the bundled codec with Phoenix Channels-compatible servers.Wire the codec →

Errors and APIHandle each failure variant and browse the public surface.Handle failures →

Recommended start

Error handling