ChannelClient.Socket (channel_client v0.2.0)

Copy Markdown

A GenServer holding the WebSocket connection to a Phoenix endpoint.

The socket owns the wire protocol: it assigns refs, tracks each joined topic's join_ref (as required by Phoenix Channels protocol v2), serializes outbound frames and routes decoded inbound frames to the matching ChannelClient.Channel process.

Lifecycle

The socket connects asynchronously after start_link/2. Joining blocks until the connection is up, so callers do not need to poll connected?/1.

Unless reconnect?: false is given, the socket keeps reconnecting forever when the connection drops, and joined channels are automatically re-joined on the next successful connection (opt out with rejoin?: false). With rejoining enabled, owners stay subscribed across reconnects and receive no notification for transient drops; failed rejoins surface as a %ChannelClient.Message{} with event "phx_error". With rejoin?: false, channels are unregistered on disconnect and their owners receive "phx_error" (or "phx_close" for clean closes); callers are expected to join again themselves.

While connected the socket sends a protocol-level heartbeat event every heartbeat_interval ms — this is what Phoenix servers require to keep the connection open.

Options

  • :url - (required) WebSocket URL, ws:// or wss://.
  • :format - wire format: :json (default), :etf, :toon, :btoon, a module implementing the ChannelClient.Format behaviour, or {module, opts}. See ChannelClient.Format.
  • :json_library - JSON module implementing encode!/1 and decode!/1. Defaults to Jason. :serializer is accepted as an alias. Only used by the JSON format.
  • :vsn - Phoenix Channels protocol version, "1.0.0" or "2.0.0". Defaults to "2.0.0". Only used by the JSON format.
  • :transport - module implementing the ChannelClient.Transport behaviour. Defaults to ChannelClient.Transports.Websocket.
  • :transport_opts - options passed through to the transport.
  • :headers - extra headers for the WebSocket upgrade request.
  • :params - map of query params merged into the connect URL.
  • :heartbeat_interval - ms between protocol-level heartbeat events sent while connected (default 30_000). Set to :infinity to disable heartbeats.
  • :reconnect_interval - ms between reconnect attempts (default 60_000).
  • :reconnect? - whether to automatically reconnect (default true).
  • :rejoin? - whether channels are re-joined automatically after a reconnect (default true).
  • :inbound_plugs - plug specs run on every decoded server frame before routing; halting a frame drops it. See ChannelClient.Plug.
  • :outbound_plugs - plug specs run on every outgoing frame before encoding; halting returns {:error, {:halted, reason}} to sync callers and drops async pushes. See ChannelClient.Plug.

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

connected?(pid_or_name)

Returns whether the underlying transport is currently connected.

start_link(opts, genserver_opts \\ [])
stop(pid)

Stops the socket process.

Types

t()

@type t() :: %ChannelClient.Socket{
  channels: term(),
  flush_pending: term(),
  format: term(),
  format_opts: term(),
  heartbeat_interval: term(),
  heartbeat_timer: term(),
  inbound_plugs: term(),
  outbound_plugs: term(),
  reconnect: term(),
  reconnect_interval: term(),
  reconnect_timer: term(),
  ref: term(),
  rejoin: term(),
  status: term(),
  to_send: term(),
  transport: term(),
  transport_opts: term(),
  transport_pid: term(),
  url: term()
}

Functions

child_spec(init_arg)

@spec child_spec(keyword() | {keyword(), keyword()}) :: Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

See Supervisor.

connected?(pid_or_name)

@spec connected?(pid() | atom()) :: boolean()

Returns whether the underlying transport is currently connected.

Returns false for dead or missing sockets instead of crashing.

start_link(opts, genserver_opts \\ [])

@spec start_link(keyword(), keyword()) :: {:ok, pid()} | {:error, any()}

stop(pid)

@spec stop(pid() | atom()) :: :ok

Stops the socket process.