Phoenix v0.9.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/2. Finish by keeping state of returned HashDict of %Phoenix.Socket{}s. Message keys must be deserialized as strings.
Handle receiving outgoing {:socket_reply, %Phoenix.Socket.Message{}} as Elixir process messages, then encoding and fowarding to remote client.
Handle receiving outgoing {:socket_broadcast, %Phoenix.Socket.Message{}} as Elixir process messages, then forwarding message through Phoenix.Transport.dispatch_broadcast/2. Finish by keeping state of returned HashDict of %Phoenix.Socket{}s.
Handle remote client disconnects and relaying event through Phoenix.Transport.dispatch_leave/2

See Phoenix.Transports.WebSocket for an example transport server implementation.

Remote Client

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 assets/cs/phoenix.coffee for an example transport client implementation.

Source

Summary↑

dispatch(socket, topic, event, msg)	Dispatches `%Phoenix.Socket.Message{}` in response to a heartbeat message sent from the client
dispatch(message, sockets, adapter_pid, router, pubsub_server, transport)	Dispatches `%Phoenix.Socket.Message{}` to Channel. All serialized, remote client messages should be deserialized and forwarded through this function by adapters
dispatch_broadcast(sockets, msg)	When an Adapter receives `{:socket_broadcast, %Message{}}`, it dispatches to this function with its socket state
dispatch_leave(sockets, reason)	Whenever a remote client disconnects, the adapter must forward the event through this function to be dispatched as `"leave"` events on each socket channel

Functions

dispatch(socket, topic, event, msg)

(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

dispatch(message, sockets, adapter_pid, router, pubsub_server, transport)

(function) # ↑

Dispatches %Phoenix.Socket.Message{} to Channel. All serialized, remote client messages should be deserialized and forwarded through this function by adapters.

The following return signatures must be handled by transport adapters:

{:ok, sockets} - Successful dispatch, with updated HashDict of sockets
{:error, reason, sockets} - Failed dispatched with updatd HashDict of sockets

The returned HashDict of %Phoenix.Socket{}s must be held by the adapter

Source

dispatch_broadcast(sockets, msg)

(function) # ↑

When an Adapter receives {:socket_broadcast, %Message{}}, it dispatches to this function with its socket state.

The message is routed to the intended channel’s outgoing/3 callback.

Source

dispatch_leave(sockets, reason)

(function) # ↑

Whenever a remote client disconnects, the adapter must forward the event through this function to be dispatched as "leave" events on each socket channel.

Most adapters shutdown after this dispatch as they client has disconnected

Source