An exploration into a stand-alone library for Plug applications to easily adopt WebSockets.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
config initial echo server May 1, 2015
example convert to library. move example code to example/ May 4, 2015
priv/static created external js class to wrap functionality May 3, 2015
test use credo Feb 7, 2017
.gitignore v0.1.0 Oct 8, 2016
.travis.yml use credo Feb 7, 2017
LICENSE initial echo server May 1, 2015
mix.exs use credo Feb 7, 2017
mix.lock use credo Feb 7, 2017
run_examples.exs Replace run/1 with dispatch_table/1 Aug 7, 2015


Build Status Coverage Status Version

An exploration into a stand-alone library for Plug applications to easily adopt WebSockets.

Viewing the examples

Run these:

$ git clone
$ cd plug-web-socket
$ mix deps.get
$ iex -S mix run run_examples.exs

Go here: http://localhost:4000.

You will be presented with a list of possible examples/tests that use a WebSocket connection.

Integrating with Plug

If you're looking to try this in your own test application, do something like this:

defmodule MyApp.Router do
  use Plug.Router
  use WebSocket

  # WebSocket routes
  #      route     controller/handler     function & name
  socket "/topic", MyApp.TopicController, :handle
  socket "/echo",  MyApp.EchoController,  :echo

  # Rest of your router's plugs and routes
  # ...

  def run(opts \\ []) do
    dispatch = dispatch_table(opts)
    Plug.Adapters.Cowboy.http __MODULE__, opts, [dispatch: dispatch]

For the time being, there is a run/1 function generated for your router that starts a HTTP/WS listener. Not sure if this will stay or get reduced to helper functions that aid in the creation of a similar function. Most likely the latter will win out to help compose functionality. The big part that it plays is the building of a dispatch table to pass as an option to Cowboy that has an entry for each of your socket routes and a catch all for HTTP requests.

Add the necessary bits to a module

From the topic example:

defmodule MyApp.TopicController do
  def handle(:init, state) do
    {:ok, state}
  def handle(:terminate, _state) do
  def handle("topic:" <> letter, state, data) do
    payload = %{awesome: "blah #{letter}",
                orig: data}
    {:reply, {:text, payload}, state}

Currently, the function name needs to be unique across all controllers/handlers as its used for the Events layer.

Broadcast from elsewhere

Need to send data out from elsewhere in your app?

# Build your message
topic = "my_event"
data  = %{foo: "awesome"}
mes   =, data)
json  = Poison.encode!(mes)

# Pick your destination (from your routes)
name = :handle

# Send away!
WebSockets.broadcast!(name, json)

This needs to be nicer, but this is still in progress.


WebSocket is released under the MIT License.

See LICENSE for details.