Phoenix.Socket
Phoenix.Socket behaviour
Defines a socket and its state.
Phoenix.Socket
is used as a module for establishing and maintaining the socket state via the Phoenix.Socket
struct.
Once connected to a socket, incoming and outgoing events are routed to channels. The incoming client data is routed to channels via transports. It is the responsibility of the socket to tie transports and channels together.
By default, Phoenix supports both websockets and longpoll transports. For example:
transport :websocket, Phoenix.Transports.WebSocket
The command above means incoming socket connections can be done via the WebSocket transport. Events are routed by topic to channels:
channel "room:lobby", MyApp.LobbyChannel
See Phoenix.Channel
for more information on channels. Check each transport module to check the options specific to each transport.
Socket Behaviour
Socket handlers are mounted in Endpoints and must define two callbacks:
-
connect/2
- receives the socket params and authenticates the connection. Must return aPhoenix.Socket
struct, often with custom assigns. -
id/1
- receives the socket returned byconnect/2
and returns the id of this connection as a string. Theid
is used to identify socket connections, often to a particular user, allowing us to force disconnections. For sockets requiring no authentication,nil
can be returned.
Examples
defmodule MyApp.UserSocket do
use Phoenix.Socket
transport :websocket, Phoenix.Transports.WebSocket
channel "room:*", 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", %{})
Socket Fields
-
id
- The string id of the socket -
assigns
- The map of socket assigns, default:%{}
-
channel
- The current channel module -
channel_pid
- The channel pid -
endpoint
- The endpoint module where this socket originated, for example:MyApp.Endpoint
-
handler
- The socket module where this socket originated, for example:MyApp.UserSocket
-
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"room:123"
-
transport
- The socket’s transport, for example:Phoenix.Transports.WebSocket
-
transport_pid
- The pid of the socket’s transport process -
transport_name
- The socket’s transport, for example::websocket
-
serializer
- The serializer for socket messages, for example:Phoenix.Transports.WebSocketSerializer
Custom transports
See the Phoenix.Socket.Transport
documentation for more information on writing your own transports.
Summary
Types
Functions
- assign(socket, key, value)
-
Adds key/value pair to socket assigns
Macros
- channel(topic_pattern, module, opts \\ [])
-
Defines a channel matching the given topic and transports
- transport(name, module, config \\ [])
-
Defines a transport with configuration
Callbacks
- connect(params, arg1)
-
Receives the socket params and authenticates the connection
- id(arg0)
-
Identifies the socket connection
Types
t :: %Phoenix.Socket{assigns: %{}, channel: atom, channel_pid: pid, endpoint: atom, handler: atom, id: nil, joined: boolean, pubsub_server: atom, ref: term, serializer: atom, topic: String.t, transport: atom, transport_name: atom, transport_pid: pid}
Functions
assign(socket, key, value)
Adds key/value pair to socket assigns.
Examples
iex> socket.assigns[:token]
nil
iex> socket = assign(socket, :token, "bar")
iex> socket.assigns[:token]
"bar"
Macros
channel(topic_pattern, module, opts \\ [])
Defines a channel matching the given topic and transports.
-
topic_pattern
- The string pattern, for example “room:”, “users:”, “system” -
module
- The channel module handler, for exampleMyApp.RoomChannel
-
opts
- The optional list of options, see below
Options
-
:via
- the transport adapters to accept on this channel. Defaults[:websocket, :longpoll]
Examples
channel "topic1:*", MyChannel
channel "topic2:*", MyChannel, via: [:websocket]
channel "topic", MyChannel, via: [:longpoll]
Topic Patterns
The channel
macro accepts topic patterns in two flavors. A splat argument can be provided as the last character to indicate a “topic:subtopic” match. If a plain string is provied, only that topic will match the channel handler. Most use-cases will use the “topic:*” pattern to allow more versatile topic scoping.
See Phoenix.Channel
for more information
transport(name, module, config \\ [])
Defines a transport with configuration.
Examples
# customize default `:websocket` transport options
transport :websocket, Phoenix.Transports.WebSocket,
timeout: 10_000
# define separate transport, using websocket handler
transport :websocket_slow_clients, Phoenix.Transports.WebSocket,
timeout: 60_000
Callbacks
connect(params, arg1)
Specs
connect(params :: map, Phoenix.Socket.t) ::
{:ok, Phoenix.Socket.t} |
:error
Receives the socket params and authenticates the connection.
Socket params and assigns
Socket params are passed from the client and can be used to verify and authenticate a user. After verification, you can put default assigns into the socket that will be set for all channels, ie
{:ok, assign(socket, :user_id, verified_user_id)}
To deny connection, return :error
.
See Phoenix.Token
documentation for examples in performing token verification on connect.
id(arg0)
Specs
id(Phoenix.Socket.t) :: String.t | nil
Identifies the socket connection.
Socket id’s are topics that allow you to identify all sockets for a given user:
def id(socket), do: "users_socket:#{socket.assigns.user_id}"
Would allow you to broadcast a “disconnect” event and terminate all active sockets and channels for a given user:
MyApp.Endpoint.broadcast("users_socket:" <> user.id, "disconnect", %{})
Returning nil
makes this socket anonymous.
© 2014 Chris McCord
Licensed under the MIT License.
https://hexdocs.pm/phoenix/Phoenix.Socket.html