A WebSocket client built on gen_statem and Mint WebSocket.

Parley provides a callback-based API similar to GenServer. You define a module with use Parley, implement the callbacks you need, and interact with the connection through the functions in this module.

Usage

defmodule MyClient do
  use Parley

  @impl true
  def handle_connect(state) do
    IO.puts("Connected!")
    {:ok, state}
  end

  @impl true
  def handle_frame({:text, msg}, state) do
    IO.puts("Received: #{msg}")
    {:ok, state}
  end

  @impl true
  def handle_disconnect(_reason, state) do
    IO.puts("Disconnected")
    {:ok, state}
  end
end

Starting with a pid

{:ok, pid} = MyClient.start_link(%{}, url: "wss://example.com/ws")
Parley.send_frame(pid, {:text, "hello"})
Parley.disconnect(pid)

Starting with a registered name

{:ok, _pid} = MyClient.start_link(%{}, url: "wss://example.com/ws", name: MyClient)
Parley.send_frame(MyClient, {:text, "hello"})
Parley.disconnect(MyClient)

Starting under a supervisor

children = [
  {MyClient, {%{}, url: "wss://example.com/ws", name: MyClient}}
]

Supervisor.start_link(children, strategy: :one_for_one)

Options

• :url (required) — the WebSocket URL to connect to (e.g. "wss://example.com/ws")
• :name — used for name registration, see the "Name registration" section below
• :headers — custom headers sent with the WebSocket upgrade request (e.g. [{"authorization", "Bearer token"}]). Default: []
• :connect_timeout — timeout in milliseconds for the WebSocket upgrade handshake (default: 10_000)
• :transport_opts — options passed to the transport layer (:gen_tcp for ws://, :ssl for wss://). Use this for TLS configuration such as certificate pinning, custom CAs, or TCP-level timeouts (e.g. [timeout: 5_000, cacertfile: "path/to/ca.pem"])
• :protocols — Mint HTTP protocols to use for the connection (default: [:http1])
• :reconnect — controls automatic reconnection with exponential backoff. Accepts false (default, no reconnection), true (enable with defaults: base_delay: 1_000, max_delay: 30_000, max_retries: :infinity), or a keyword list with custom values for :base_delay, :max_delay, and :max_retries

Name registration

The :name option supports the same values as GenServer:

• an atom — registered locally with {:local, atom}
• {:global, term} — registered with :global
• {:via, module, term} — registered with a custom registry

Connection lifecycle

The connection is managed as a state machine with three states:

stateDiagram-v2
    [*] --> init: start_link/3
    init --> disconnected: {:ok, state}
    init --> [*]: {:stop, reason}

    disconnected --> connecting: TCP connect + WS upgrade
    disconnected --> [*]: connect / upgrade failure (reconnect: false)

    connecting --> connected: upgrade success
    connecting --> disconnected: error / timeout

    connected --> disconnected: error / close / disconnect/1 / {:disconnect, ...}
    connected --> [*]: callback {:stop, ...}

    state disconnected {
        [*] --> handle_disconnect
        handle_disconnect --> reconnecting: {:ok, state} / {:reconnect, state}
        handle_disconnect --> stay_disconnected: {:disconnect, state}
    }

    state connected {
        [*] --> handle_connect
        handle_connect --> waiting
        waiting --> handle_frame: frame received
        handle_frame --> waiting
        waiting --> handle_ping: ping received
        handle_ping --> waiting
        waiting --> handle_info: process message
        handle_info --> waiting
    }

    note right of connecting
        send_frame/2 calls are queued
        and replayed on connect
    end note

    note right of connected
        Pings auto-ponged before
        handle_ping/2 is called
    end note

    note left of disconnected
        handle_info/2 runs in all states.
        {:disconnect, ...} transitions to
        disconnected from any callback.
        {:stop, ...} terminates the process
        from any state.
    end note

• disconnected — initial state. On process start, immediately attempts to connect. Calls handle_disconnect/2 when entering from another state. If reconnection is enabled, schedules a reconnect attempt with exponential backoff.
• connecting — TCP connection established, waiting for the WebSocket upgrade handshake to complete. Frames sent via send_frame/2 during this state are automatically queued and delivered once connected.
• connected — WebSocket upgrade complete. Calls handle_connect/1 on entry, then handle_frame/2 for each frame received from the server. Resets the reconnect attempt counter to 0.

Callbacks

All callbacks are optional and have default implementations. Override only the ones you need.

• init/1 — called when the process starts, before connecting. Transforms the init_arg into user state (default: passes it through)
• handle_connect/1 — called when the WebSocket handshake completes
• handle_frame/2 — called when a frame is received from the server
• handle_ping/2 — called when a ping frame is received (pong is sent automatically)
• handle_info/2 — called when the process receives a non-WebSocket message
• handle_disconnect/2 — called when the connection is lost or closed

handle_connect/1, handle_frame/2, handle_ping/2, and handle_info/2 also support {:push, frame, state} to send a frame from within the callback, {:disconnect, reason, state} to gracefully close the connection while keeping the process alive, and {:stop, reason, state} to stop the process. See the callback docs for details.