ChannelClient.Channel (channel_client v0.2.0)

A client process bound to one channel topic on a ChannelClient.Socket.

Joining blocks until the socket is connected and the server accepted the join, so it can be called right after ChannelClient.Socket.start_link/2. The caller is linked to the channel process; broadcasts and pushes from the server are forwarded to the caller as %ChannelClient.Message{} structs (or delivered to a handler/1 fun when given).

With sockets started using the default rejoin?: true, topics survive reconnects — the socket re-joins them automatically and delivery resumes without any action from the caller.

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

join(socket_pid_or_name, topic, params \\ %{}, timeout \\ 5000, handler \\ nil)

Join a channel topic through a socket with optional params.

leave(pid)

Leave the channel topic and stop the channel.

push(pid, event, payload, timeout \\ 5000)

Push a message to the server and wait for a reply or until timeout.

push_async(pid, event, payload)

Push a message to the server and do not wait for a response.

Functions

child_spec(init_arg)

@spec child_spec({pid() | atom(), String.t(), map(), term()}) ::
  Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

See Supervisor.

join(socket_pid_or_name, topic, params \\ %{}, timeout \\ 5000, handler \\ nil)

@spec join(pid() | atom(), String.t(), map(), non_neg_integer(), term()) ::
  {:ok, map(), pid()}
  | {:error, :socket_not_started}
  | {:error, :timeout}
  | {:error, any()}

Join a channel topic through a socket with optional params.

Blocks until the underlying socket is connected (up to timeout ms), so it is safe to call immediately after starting a socket. A socket can only join a topic once. If the socket you pass already has a channel connection for the supplied topic, you will receive an error {:error, {:already_joined, pid}} with the channel pid of the process joined to that topic through that socket. If you require to join the same topic with multiple processes, you will need to start a new socket process for each channel.

Calling join will link the caller to the channel process.

Options

params - join payload sent to the server.
timeout - ms to wait for the connection and for the server's join reply (default 5000).
handler - optional fun/1 receiving every %Message{} delivered for this topic. Called in the channel process; exceptions and exits are logged instead of crashing the channel. When omitted, messages are sent to the joining process's mailbox.

leave(pid)

@spec leave(pid()) :: :ok

Leave the channel topic and stop the channel.

Always returns :ok, even when the channel process is already gone.

push(pid, event, payload, timeout \\ 5000)

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

Push a message to the server and wait for a reply or until timeout.

Returns {:ok, response} when the server replies with an ok status. Any other outcome returns {:error, reason}:

{:error, response} - the server replied with an error status; the response is the server's reply payload
{:error, {:timeout, response}} - the server replied with a timeout status
{:error, :timeout} - no reply arrived within timeout ms

Payloads must be encodable by the configured wire format; unencodable payloads return {:error, reason} immediately.

push_async(pid, event, payload)

@spec push_async(pid(), String.t(), term()) :: :ok

Push a message to the server and do not wait for a response.

Replies from the server are delivered to the caller's mailbox as a %ChannelClient.Message{} with event "phx_reply".