API overview

Aquamarine's public surface is deliberately tiny. The top-level aquamarine module re-exports four functions from aquamarine/channel; everything else is internal.

For the full type signatures, browse the generated documentation on HexDocs. The summaries below are meant to be a quick map.

connect

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

Open a WebSocket, join topic with payload, wait for the join reply, and start the heartbeat. See Channel lifecycle for the exact sequence and cleanup guarantees.

push

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

Encode event and payload with a fresh ref and hand the frame to the transport. Does not wait for a reply.

receive

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

Block until the next application-level inbound frame arrives. Skips binary frames and heartbeat replies, and translates protocol close/error events into Error(ChannelClosed). Only the process that called connect should call this — see process ownership.

close

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

Stop the heartbeat and ref actors, then close the transport.

Types you'll see

• Channel — opaque handle returned by connect.
• Codec — supplied to connect; the bundled aquamarine/phoenix.codec() covers Phoenix Channels and Beryl.
• Incoming — record returned from receive.
• AquamarineError — the unified error type used by all four operations.