PhoenixWS - Websockets over Phoenix Channels

Source code on Github here: https://github.com/tmbb/phoenix_ws

Phoenix channels are a great way of adding real-time features to your web applications. They are implemented over websockets, which are essentially raw TCP sockets with extra steps (like an HTTP request to initialize the connection). Phoenix channels have a lot of advantages over normal websockets, like a reconnection mechanism and authorization features, but they require a specialized client.

Often you would like to use an existing Javascript client which expects a “normal” websocket connection. There is certainly demand for a way of using raw websockets with Phoenix, which seems to be completely impossible. The recommended advice is to drop down to Cowboy, but that is extremely unergonomic and integrates poorly with the rest of your app.

I’ve hit that problem when trying to write a ShareDB backend in Elixir, with communication between server and client happening over Phoenix Channels. The ShareDB client expectes a raw websocket connection or at least a Javascript object that talks like a websocket connection, and Phoenix expects a Phoenix Channel (and by design it can’t handle anything else).

So I’ve decided to implement Websocket-like communication on top of Phoenix Channels (which are themselves implemented on top of websockets). This is a little bit wasteful, in terms of data transmission, but if at your scale this overhead is significant you probably want to reimplement the client yourself.

This library has two parts:

• A javascript part which defines a Javascript object that implements (most of the?) Websocket API

• An elixir part which defines a custom Phoenix Channel that talks to said Javascript object

This allows you to do things like this:

// client
import socket from "./socket"
// Import the Javascript class
import PhoenixWS from "./phoenix_ws"

function initializeChat() {
  // Build a new PhoenixWS from the phoenix socket
  const connection = new PhoenixWS(socket, "room:lobby", {});
  // Write the rest of the code as if it were a websocket
}

initializeChat();

Then, define a special channel in your app:

defmodule MyAppWeb.RoomWSChannel do
  # Note that this is not a normal Phoenix channel
  # but a PhoenixWS.Channel, which can talk to a `PhownixWS` JS object.
  use PhoenixWS.Channel

  # Join the channel as if it were a Phoenix Channel
  def join("room:" <> _, _payload, socket) do
    {:ok, socket}
  end

  # Handle messages from the Client
  def phoenix_ws_in(data, socket) do
    # This is just an echo server, so we just broadcast the same message
    # back into all the clients connected to this topic.
    #
    # Not that we broadcast with PhoenixWS.broadcast!/2 because
    # we are talking to PhoenixWS
    PhoenixWS.broadcast!(socket, data)
    {:noreply, socket}
  end
end

And now you can add this special Channel to your socket:

defmodule MyAppWeb.UserSocket do
  use Phoenix.Socket

  ## Channels
  # Add a the (special) channel you've just defined
  channel "room:*", MyAppWeb.RoomWSChannel

  def connect(_params, socket, _connect_info) do
    {:ok, socket}
  end

  def id(_socket), do: nil
end

You can find a demo here: https://github.com/tmbb/phwocket_example

Because I haven’t published PhoenixWS on hex yet, it’s a little hard to add PhoenixWS's javascript as a dependency (you can’t get it from /deps/.../phoenix_ws) as phoenix does to get its own javascript. In the project above I’ve just copied the relevant file into the JS directory.

I haven’t published anything on hex yet, because everything is still untested (I’ve only done some basic manual tests). I welcome help on how to setup some integration tests that test compatibility between PhoenixWS and raw Websockets, especially on the client.