API overview

Aquamarine's surface is small and splits in two: aquamarine/socket owns a connection, aquamarine/channel owns a topic on it. The top-level aquamarine module re-exports the single-topic path for callers who want one call.

For full type signatures, read the source on GitHub. Aquamarine isn't published to Hex yet (pre-1.0). The summaries below are a quick map.

aquamarine/socket

pub fn connect(
  scheme scheme: transport.Scheme,
  host host: String,
  port port: Int,
  path path: String,
  codec codec: Codec,
) -> Result(Socket, AquamarineError)

Open a connection. It carries no topics until something joins one. scheme is transport.Ws or transport.Wss.

pub fn config(scheme:, host:, port:, path:, codec:) -> Config
pub fn with_heartbeat_ms(config: Config, ms: Int) -> Config
pub fn with_backoff(config: Config, backoff: Backoff) -> Config
pub fn start(config: Config) -> Result(Socket, AquamarineError)

The same, with the heartbeat interval and reconnect schedule under your control.

pub fn close(socket: Socket) -> Result(Nil, AquamarineError)

Close the connection and stop the actor, taking every channel with it.

pub fn watch(socket: Socket, watcher: Subject(Status)) -> Nil
pub fn unwatch(socket: Socket, watcher: Subject(Status)) -> Nil

Subscribe to connection lifecycle Status events.

pub fn new_name(prefix prefix: String) -> Name
pub fn named(name: Name) -> Socket
pub fn supervised(config: Config, name: Name) -> ChildSpecification(Socket)

Supervision and named sockets.

aquamarine/channel

pub fn join(
  socket socket: Socket,
  topic topic: String,
  payload payload: json.Json,
  timeout timeout: Int,
) -> Result(Channel, AquamarineError)

Join a topic on an existing socket and block for the reply. The channel does not own the socket.

pub fn connect(
  scheme scheme: transport.Scheme,
  host host: String,
  port port: Int,
  path path: String,
  topic topic: String,
  payload payload: json.Json,
  codec codec: Codec,
) -> Result(Channel, AquamarineError)

Connection plus join in one call, for the single-topic case. The channel owns its socket.

pub fn push(channel: Channel, event: String, payload: json.Json) -> Nil

Encode event and payload with a fresh ref and hand the frame to the socket actor. Fire-and-forget: it does not wait for a reply and cannot report a delivery failure.

pub fn push_and_await_reply(
  channel: Channel,
  event: String,
  payload: json.Json,
  timeout: Int,
) -> Result(Incoming, AquamarineError)

The same, but block for the reply carrying that ref. Correlated, so concurrent pushes each get their own.

pub fn receive(channel: Channel, timeout: Int) -> Result(Incoming, AquamarineError)

Block until the next frame for this topic arrives. Only the process that called connect or join may call this — see process ownership.

pub fn events(channel: Channel) -> Subject(socket.Event)

The subject frames are delivered on, for callers who want to select on it alongside their own messages. See Choosing your model.

pub fn leave(channel: Channel) -> Result(Nil, AquamarineError)
pub fn close(channel: Channel) -> Result(Nil, AquamarineError)

leave is always leave-only. close also closes the connection if this channel owns it — see who closes the connection.

pub fn join_reply(channel: Channel) -> Incoming
pub fn topic(channel: Channel) -> String
pub fn socket(channel: Channel) -> Socket

Accessors. join_reply is what the server actually answered the join with.

aquamarine

The facade re-exports the single-topic path: connect, push, push_and_await_reply, receive, join_reply, leave, and close. Multi-topic callers use aquamarine/socket and aquamarine/channel directly.

Types you'll see

• Socket — opaque handle to a connection.
• Channel — opaque handle to a joined topic.
• Codec — supplied to the socket; the bundled aquamarine/phoenix.codec() covers Phoenix Channels and Beryl.
• Incoming — record returned from receive.
• Status — connection lifecycle events.
• Backoff — the reconnect schedule.
• AquamarineError — the unified error type.