Specification of the protocol used by Phoenix channels

LostKobrakai · August 22, 2018, 9:46am

I’m certainly with you, that some more detailed specification would be nice.

What you can find in the js file are the handful of channel-specific events you could receive besides the custom user-land events:

const CHANNEL_EVENTS = {
  close: "phx_close",
  error: "phx_error",
  join: "phx_join",
  reply: "phx_reply",
  leave: "phx_leave"
}

The other part a client needs to be aware of is in which format messages are sent by the used transport.

https://hexdocs.pm/phoenix/Phoenix.Socket.Transport.html#content

E.g. the built in transports use basically a simple json blob for messages:

github.com

phoenixframework/phoenix/blob/master/lib/phoenix/socket/serializers/v2_json_serializer.ex

defmodule Phoenix.Socket.V2.JSONSerializer do
  @moduledoc false
  @behaviour Phoenix.Socket.Serializer

  alias Phoenix.Socket.{Broadcast, Message, Reply}

  def fastlane!(%Broadcast{} = msg) do
    data = Phoenix.json_library().encode_to_iodata!([nil, nil, msg.topic, msg.event, msg.payload])
    {:socket_push, :text, data}
  end

  def encode!(%Reply{} = reply) do
    data = [
      reply.join_ref,
      reply.ref,
      reply.topic,
      "phx_reply",
      %{status: reply.status, response: reply.payload}
    ]

This file has been truncated. show original

So the channel -> transport interface is documented and the websocket/longpolling transport -> client is using json in a particular format.

So what I miss the most is some descriptions for the above listed channel events and when they’re sent/shall be sent, some description about how to handle the different refs in messages and how to handle presence lists/diffs.