Phoenix v0.11.0 → Overview → Phoenix → Channel → Transport

Phoenix.Channel.Transport

Summary
Functions

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 through Phoenix.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’s Phoenix.Transport.dispatch/6.
Handle receiving outgoing {:socket_push, %Phoenix.Socket.Message{}} 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 from Transport.chan_close_message/1
- for abnormal exits, send a reply to the remote client of a message from Transport.chan_error_message/1

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.

Source

Summary↑

chan_close_message(topic)	Returns the `%Phoenix.Message{}` for a channel close event
chan_error_message(topic)	Returns the `%Phoenix.Message{}` for a channel error event
check_origin(conn, opts \\ [])	Checks the Origin request header against the list of allowed origins configured on the `Phoenix.Endpoint` `:transports` 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
dispatch(msg, sockets, transport_pid, router, endpoint, transport)	Dispatches `%Phoenix.Socket.Message{}` in response to a heartbeat message sent from the client

Functions

chan_close_message(topic)

(function) # ↑

Returns the %Phoenix.Message{} for a channel close event

Source

chan_error_message(topic)

(function) # ↑

Returns the %Phoenix.Message{} for a channel error event

Source

check_origin(conn, opts \\ [])

(function) # ↑

Checks the Origin request header against the list of allowed origins configured on the Phoenix.Endpoint :transports 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.

Source

dispatch(msg, sockets, transport_pid, router, endpoint, transport)

(function) # ↑

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

Source