Layr8.Channel (layr8 v0.2.5)

Phoenix Channel transport over WebSocket.

Implements the Phoenix Channel V2 wire protocol:

[join_ref, ref, topic, event, payload]

Connection Flow

Connects to {node_url}?api_key={key}&vsn=2.0.0
Sends phx_join with registered protocols and DID spec
Fires heartbeat every 30 seconds
Auto-reconnects with exponential backoff (1s → 30s) on disconnect

Callbacks

on_message/1 — called with the decoded payload of inbound "message" events
on_disconnect/1 — called with the error reason on disconnect
on_reconnect/0 — called after successful reconnection

Not meant to be used directly; interact through Layr8.Client.

Summary

Types

callbacks()

on_disconnect_fn()

on_message_fn()

on_reconnect_fn()

start_opts()

Functions

assigned_did(pid)

Returns the DID assigned by the cloud-node (for ephemeral identities).

capabilities(pid)

Returns the capabilities advertised by the cloud-node on join.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

close(pid)

Closes the WebSocket connection.

connect(pid, protocols)

Connects to the cloud-node WebSocket and joins the Phoenix channel.

send_ack(pid, ids)

Sends an acknowledgment for a list of message IDs.

send_fire_and_forget(pid, event, payload)

Sends a message event fire-and-forget (no reply tracking).

send_msg(pid, event, payload)

Sends a message event and waits for a server acknowledgment.

start_link(opts)

Starts the Channel GenServer.

Types

callbacks()

@type callbacks() :: %{
  on_message: on_message_fn(),
  on_disconnect: on_disconnect_fn() | nil,
  on_reconnect: on_reconnect_fn() | nil
}

on_disconnect_fn()

@type on_disconnect_fn() :: (term() -> any())

on_message_fn()

@type on_message_fn() :: (map() -> any())

on_reconnect_fn()

@type on_reconnect_fn() :: (-> any())

start_opts()

@type start_opts() :: %{
  :ws_url => String.t(),
  :api_key => String.t(),
  :agent_did => String.t(),
  :callbacks => callbacks(),
  optional(:did_spec) => map()
}

Functions

assigned_did(pid)

@spec assigned_did(pid()) :: String.t()

Returns the DID assigned by the cloud-node (for ephemeral identities).

capabilities(pid)

@spec capabilities(pid()) :: [String.t()]

Returns the capabilities advertised by the cloud-node on join.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

close(pid)

@spec close(pid()) :: :ok

Closes the WebSocket connection.

connect(pid, protocols)

@spec connect(pid(), [String.t()]) :: :ok | {:error, term()}

Connects to the cloud-node WebSocket and joins the Phoenix channel.

Blocks until the join is acknowledged or returns {:error, reason}.

send_ack(pid, ids)

@spec send_ack(pid(), [String.t()]) :: :ok

Sends an acknowledgment for a list of message IDs.

Used in legacy mode (cloud nodes without reply protocol).

send_fire_and_forget(pid, event, payload)

@spec send_fire_and_forget(pid(), String.t(), map()) :: :ok

Sends a message event fire-and-forget (no reply tracking).

send_msg(pid, event, payload)

@spec send_msg(pid(), String.t(), map()) :: {:ok, map()} | {:error, term()}

Sends a message event and waits for a server acknowledgment.

Returns {:ok, reply} where reply is %{status: String.t(), reason: String.t()}, or {:error, reason} on timeout or disconnect.

start_link(opts)

@spec start_link(start_opts()) :: GenServer.on_start()

Starts the Channel GenServer.

Options

:ws_url — WebSocket URL
:api_key — API key for the ?api_key= query parameter
:agent_did — agent DID (used as the Phoenix topic plugins:{did})
:callbacks — map of callback functions (see module doc)