ConvergerClient.Socket (converger_client v0.1.0)

Copy Markdown View Source

Protocol v1 WebSocket client for the native endpoint (/socket/converger/v1), built on Mint.WebSocket.

{:ok, sock} =
  ConvergerClient.Socket.start_link(
    client: client,                 # or url: "wss://host/socket/converger/v1"
    token: conversation_token,      # or a 0-arity function returning one
    conversation_id: conversation_id,
    watermark: stored_watermark
  )

{:ok, %ConvergerClient.Ack{seq: seq}} = ConvergerClient.Socket.send_text(sock, "Hello")

receive do
  {:converger, ^sock, %{"type" => "text", "data" => %{"text" => text}}} -> text
end

Frames for the application are sent to the owner (the caller of start_link/1, or :owner) as {:converger, socket, frame}: persistent frames in seq order, exactly once, plus transient frames (typing, presence, receipts, errors) and every welcome. When the socket ends for good the owner receives {:converger_closed, socket, %{code: code, reason: reason}} and the process stops.

The socket reconnects with jittered exponential backoff, resumes from the watermark, answers gaps with sync, and re-sends unacknowledged sends with their original clientId (exactly-once persistence on the server).

Summary

Functions

Returns a specification to start this module under a supervisor.

Closes the socket.

Marks everything up to watermark as read.

Sends a message frame of any type and waits for its ack ({:error, %{"code" => ...}} when refused).

Sends a text turn and waits for its ack. Options: :client_id, :metadata, :reply_to, :timeout.

Starts the socket.

Sends a typing indicator.

The native endpoint URL for a REST base URL.

The current watermark.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

close(sock)

Closes the socket.

read(sock, watermark)

Marks everything up to watermark as read.

send_message(sock, type, data, opts \\ [])

@spec send_message(GenServer.server(), String.t(), map(), keyword()) ::
  {:ok, ConvergerClient.Ack.t()} | {:error, term()}

Sends a message frame of any type and waits for its ack ({:error, %{"code" => ...}} when refused).

send_text(sock, text, opts \\ [])

@spec send_text(GenServer.server(), String.t(), keyword()) ::
  {:ok, ConvergerClient.Ack.t()} | {:error, term()}

Sends a text turn and waits for its ack. Options: :client_id, :metadata, :reply_to, :timeout.

start_link(opts)

Starts the socket.

Options: :client or :url, :token (string or 0-arity function, called on every connect), :conversation_id, :watermark, :owner (default the caller), :reconnect (default true), :max_retries (default unlimited), :backoff ({initial_ms, max_ms}, default {500, 30_000}), :connect_timeout (ms, default 10_000).

typing(sock, typing?)

Sends a typing indicator.

url(base_url)

@spec url(String.t()) :: String.t()

The native endpoint URL for a REST base URL.

watermark(sock)

The current watermark.