README.md

WebSockAdapter

WebSockAdapter is a library of adapters from common Web Servers to the WebSock specification. WebSockAdapter currently supports Bandit and Cowboy.

For details on the WebSock specification, consult the WebSock documentation.

Usage

WebSockAdapter makes it easy to upgrade Plug connections to WebSock connections. Here's a simple example:

defmodule EchoServer do
  def init(args) do
    {:ok, []}
  end

  def handle_in({"ping", [opcode: :text]}, state) do
    {:reply, :ok, {:text, "pong"}, state}
  end
end

defmodule MyPlug do
  use Plug.Router

  plug Plug.Logger
  plug :match
  plug :dispatch

  get "/" do
    # Provide the user with some useful instructions to copy & paste into their inspector
    send_resp(conn, 200, """
    Use the JavaScript console to interact using websockets

    sock  = new WebSocket("ws://localhost:4000/websocket")
    sock.addEventListener("message", console.log)
    sock.addEventListener("open", () => sock.send("ping"))
    """)
  end

  get "/websocket" do
    conn
    |> WebSockAdapter.upgrade(EchoServer, [], timeout: 60_000)
    |> halt()
  end

  match _ do
    send_resp(conn, 404, "not found")
  end
end

This simple example illustrates many of the useful features of WebSock / WebSockAdapters:

• Implementing a WebSocket server is a single module, and looks & acts much like a GenServer does
• It's easy to pass state from the WebSockAdapter.upgrade/3 call & have it show up in your WebSock callbacks
• Upgrades are handled as a plain Plug call. You are able to route requests to your upgrade endpoint using all of the power of the Plug API

If you're looking for more detail, Benjamin Milde has a great blog post that goes a bit deeper than the simple example above.

Upgrade Validation

Since 0.5.5, WebSockAdapter validates requests made via WebSockAdapter.upgrade/3 (this was and continues to also be done by the underlying web server, but since the server's validation occurs after the Plug.call/2 lifecycle completes it's difficult to meaningfully handle such errors). This validation examines the request for conformance to the clauses laid out in RFC6455§4.2, as well as RFC8441§5 for HTTP/2 connections. Requests which do not satisfy the requirements laid out in those specifications will result in a WebSockAdapter.UpgradeError being raised, containing details of the reason for the failure

Installation

The websock_adapter package can be installed by adding websock_adapter to your list of dependencies in mix.exs:

def deps do
  [
    {:websock_adapter, "~> 0.5"}
  ]
end

Documentation can be found at https://hexdocs.pm/websock_adapter.

License

MIT