phoenix-channels-essentials

Phoenix Channels Essentials

For non-LiveView real-time features: mobile clients, SPAs, external APIs, inter-service communication.

RULES — Follow these with no exceptions

1. Always authenticate in connect/3 — channels bypass the Plug pipeline; tokens must be verified in the socket
2. Authorize in join/3 — verify the user can access the requested topic before allowing the connection
3. Use handle_in for client-to-server, push for server-to-client, broadcast for server-to-all — never confuse the direction
4. Keep channel modules thin — delegate business logic to context modules; channels are the transport layer
5. Use Presence for tracking connected users — don't roll your own presence tracking; Phoenix.Presence handles node distribution
6. Return {:reply, :ok, socket} or {:reply, {:error, reason}, socket} from handle_in — don't silently drop messages

---

Socket Authentication

Channels bypass the Plug pipeline, so session-based auth doesn't work. Use token-based authentication.

Generating Tokens (Server Side)

# In a controller or LiveView — generate a token for the current user
defmodule MyAppWeb.UserAuth do
  def generate_socket_token(conn) do
    Phoenix.Token.sign(conn, "user socket", conn.assigns.current_scope.user.id)
  end
end

# In your layout or root template
<script>
  window.userToken = "<%= Phoenix.Token.sign(@conn, "user socket", @current_scope.user.id) %>"
</script>

Verifying Tokens (Socket)

defmodule MyAppWeb.UserSocket do
  use Phoenix.Socket

  channel "room:*", MyAppWeb.RoomChannel
  channel "notifications:*", MyAppWeb.NotificationChannel

  @impl true
  def connect(%{"token" => token}, socket, _connect_info) do
    # Phoenix.Token.verify/4 defaults max_age to 86_400 (1 day); this example
    # passes max_age: 1_209_600 to extend it to 2 weeks.
    case Phoenix.Token.verify(socket, "user socket", token, max_age: 1_209_600) do
      {:ok, user_id} ->
        {:ok, assign(socket, :user_id, user_id)}

      {:error, _reason} ->
        :error
    end
  end

  def connect(_params, _socket, _connect_info), do: :error

  @impl true
  def id(socket), do: "users_socket:#{socket.assigns.user_id}"
end