Phoenix.Channel.Transport behaviour
Handles dispatching incoming and outgoing Channel messages
The Transport Adapter Contract
The Transport layer dispatches %Phoenix.Socket.Message{}
‘s from remote clients,
backed by different Channel transport implementations and serializations.
Server
To implement a Transport adapter, the Server must broker the following actions:
- Handle receiving incoming, encoded
%Phoenix.Socket.Message{}
‘s from remote clients, then deserialing and fowarding message throughPhoenix.Transport.dispatch/6
. Message keys must be deserialized as strings. - Handle receiving
{:ok, socket_pid}
results from Transport dispatch and storing a HashDict of a string topics to Pid matches, and Pid to String topic matches. The HashDict of topic => pids is dispatched through the transport layer’sPhoenix.Transport.dispatch/6
. - Handle receiving outgoing
%Phoenix.Socket.Message{}
and%Phoenix.Socket.Reply{}
as Elixir process messages, then encoding and fowarding to remote client. Trap exits and handle receiving
{:EXIT, socket_pid, reason}
messages and delete the entries from the kept HashDict of socket processes. When exits are received, the adapter transport must reply to their client with one of two messages:- for
:normal
exits and shutdowns, send a reply to the remote client of a message fromTransport.chan_close_message/1
- for abnormal exits, send a reply to the remote client of a message
from
Transport.chan_error_message/1
- for
- Call the
socket_connect/3
passing along socket params from client and keep the state of the returned%Socket{}
to pass into dispatch. - Subscribe to the socket’s
:id
on init and handle%Phoenix.Socket.Broadcast{}
messages with the"disconnect"
event and gracefully shutdown.
See Phoenix.Transports.WebSocket
for an example transport server implementation.
Remote Client
Synchronouse Replies and ref
‘s:
Channels can reply, synchronously, to any handle_in/3
event. To match pushes
with replies, clients must include a unique ref
with every message and the
channel server will reply with a matching ref where the client and pick up the
callback for the matching reply.
Phoenix includes a JavaScript client for WebSocket and Longpolling support using JSON encodings.
However, a client can be implemented for other protocols and encodings by
abiding by the Phoenix.Socket.Message
format
See web/static/js/phoenix.js
for an example transport client implementation.
Summary↑
chan_close_message(topic) | Returns the |
chan_error_message(topic) | Returns the |
check_origin(conn, allowed_origins, opts \\ []) | Checks the Origin request header against the list of allowed origins
configured on the socket’s transport config. If the Origin
header matches the allowed origins, no Origin header was sent or no origins
configured it will return the given |
dispatch(msg, sockets, transport_pid, socket_handler, socket, endpoint, transport) | Dispatches |
socket_connect(transport_mod, handler, params) | Calls the socket handler’s |
Functions
Returns the %Phoenix.Message{}
for a channel close event
Returns the %Phoenix.Message{}
for a channel error event
Checks the Origin request header against the list of allowed origins
configured on the socket’s transport config. If the Origin
header matches the allowed origins, no Origin header was sent or no origins
configured it will return the given Plug.Conn
. Otherwise a 403 Forbidden
response will be send and the connection halted.
Dispatches %Phoenix.Socket.Message{}
in response to a heartbeat message sent from the client.
The Message format sent to phoenix requires the following key / values:
topic
- The String value “phoenix”event
- The String value “heartbeat”payload
- An empty JSON message payload, ie {}
The server will respond to heartbeats with the same message
Calls the socket handler’s connect/2
callback and returns the result.
If the connection was successful, generates Phoenix.PubSub
topic
from the id/1
callback.
Callbacks
Specs:
- default_config :: list
Provides a keyword list of default configuration for socket transports