Phoenix.Socket

Holds state for every channel, pointing to its transport, pubsub server and more.

Socket Fields

• id - The string id of the socket
• assigns - The map of socket assigns, default: %{}
• channel - The channel module where this socket originated
• channel_pid - The channel pid
• endpoint - The endpoint module where this socket originated
• joined - If the socket has effectively joined the channel
• pubsub_server - The registered name of the socket’s PubSub server
• ref - The latest ref sent by the client
• topic - The string topic, for example "rooms:123"
• transport - The socket’s transport, for example: Phoenix.Transports.WebSocket
• transport_pid - The pid of the socket’s transport process
• serializer - The Phoenix.Socket.Message serializer, for example: Phoenix.Transports.WebSocketSerializer

Channels

Channels allow you to route pubsub events to channel handlers in your application. By default, Phoenix supports both :websocket and :longpoll transports. See the Phoenix.Channel.Transport documentation for more information on writing your own transports. Channels are defined within a socket handler, using the channel/2 macro, as seen below.

Socket Behaviour

Socket handlers are mounted in Endpoints and must define two callbacks:

• connect/2 - receives the socket params and authenticates the connection. Often used to wire up default %Phoenix.Socket{} assigns for all channels.
• id/1 - receives the socket returned by connect/2, and returns the string id of this connection. Used for forcing a disconnect for connection and all child channels. For sockets requiring no authentication, nil can be returned.

Callback examples:

defmodule MyApp.UserSocket do
  use Phoenix.Socket

  channel "rooms:*", MyApp.RoomChannel

  def connect(params, socket) do
    {:ok, assign(socket, :user_id, params["user_id"])}
  end

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

...
# disconnect all user's socket connections and their multiplexed channels
MyApp.Endpoint.broadcast("users_socket:" <> user.id, "disconnect")

Transport Configuration

Transports are defined and configured within socket handlers. By default, Phoenix defines the :websocket, and :longpoll transports automaticaly with overridable options. Check the transport modules for transport specific options. A list of allowed origins can be specified in the :origins key for the :websocket and :longpoll transports. This will restrict clients based on the given Origin header.

transport :longpoll, Phoenix.Transports.LongPoll,
  origins: ["//example.com", "http://example.com", "https://example.com"]

transport :websocket, Phoenix.Transports.WebSocket,
  origins: ["//example.com", "http://example.com", "https://example.com"]

If no such header is sent no verification will be performed. If the Origin header does not match the list of allowed origins a 403 Forbidden response will be sent to the client. See transport/3 for more information.