# WebSockex

[![Build Status](](
[![Build status](](

An Elixir Websocket Client.

A simple implementation could be

defmodule WebSocketExample do
  use WebSockex

  def start_link(url, state) do
    WebSockex.start_link(url, __MODULE__, state)

  def handle_frame({type, msg}, state) do
    IO.puts "Received Message - Type: #{inspect type} -- Message: #{inspect msg}"
    {:ok, state}

  def handle_cast({:send, {type, msg} = frame}, state) do
    IO.puts "Sending #{type} frame with payload: #{msg}"
    {:reply, frame, state}

See the `examples/` directory for other examples or take a look at the [documentation][docs].

## Installation

Add `websockex` to your list of dependencies in `mix.exs`:

def deps do
  [{:websockex, "~> 0.4.3"}]

### With Elixir releases prior to version  1.4

Ensure `websockex` is started before your application:

def application do
  [applications: [:websockex]]

## Why WebSockex?

WebSockex was conceived after trying other libraries and realizing that I needed something tested, that actually
implemented the spec, provided information about the connection, and could fit into a supervision tree. There was
nothing that really fit into all those categories, so WebSockex was created.

There are other libraries out there can fit into some of the categories, but I consider WebSockex the best option if
you want a callback inspired approach where most of the protocol workings are abstracted out of your way.

If you are afraid that WebSockex isn't stable enough or have some other problem with it that you don't feel like
telling me about, then I would suggest the excellent [`gun` library][gun_hex]. It's a bit harder to use, and requires
some knowledge of the spec. However it is an excellent library.


## Supervision and Linking

A WebSockex based process is a easily able to fit into any supervision tree. It supports all the necessary capabilites
to do so. In addition, it supports the `Supervisor` children format introduced in Elixir 1.5. So in any version of
Elixir after 1.5, you can simply do:

defmodule MyApp.Client do
  use WebSockex

  def start_link(state) do
    WebSockex.start_link("ws://", __MODULE__, state)

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      {MyApp.Client, ["WebSockex is Great"]}

    Supervisor.start_link(children, strategy: :one_for_one)

See the Supervision section in the `WebSockex` module documentation for more details on how this works.

WebSockex also supports both linked(`start_link/3`) and unlinked(`start/3`) processes.

iex> {:ok, pid} = WebSockex.start_link(url, __MODULE__, state)
iex> {:ok, pid} = WebSockex.start(url, __MODULE__, state)

However, the recommendation is to always use `start_link/3` and if necessary trap exits.

This is because `start/3` creates a detached process and has the capability to produce zombie processes outside of any
application tree. This is generally a good piece of advice for any process, however since a module using WebSockex
bevhaviour can be written as a self-sustaining tcp connection. I feel like it is even more important to express this
particular piece of advice here.

## Tips
### Terminating with :normal after an Exceptional Close or Error

Usually you'll want to negotiate and handle any abnormal close event or error leading to it, as per WS Spec, but there might be cases where you simply want the socket to exit as if it was a normal event, even if it was abruptly closed or another exception was raised. In those cases you can define the terminate callback and return `exit(:normal)` from it.
def terminate(reason, state) do
    IO.puts(\nSocket Terminating:\n#{inspect reason}\n\n#{inspect state}\n")

## Debugging

WebSockex supports the debugging mechanism for [OTP Special Processes][special_process] provided through the `:sys` module.

Since WebSockex rolls its own Special Process implementation, it's able to provide a lot more information than a regular

If, for example, I enable tracing with `EchoClient` from the examples (with `Logger` off), I would get this:

iex> {:ok, pid} = EchoClient.start_link(debug: [:trace])
*DBG* #PID<0.371.0> attempting to connect
*DBG* #PID<0.371.0> sucessfully connected
{:ok, #PID<0.371.0>}
iex> EchoClient.echo(pid, "Hello")
*DBG* #PID<0.371.0> sending frame: {:text, "Hello"}
*DBG* #PID<0.371.0> received frame: {:text, "Hello"}
*DBG* #PID<0.371.0> received frame: :ping
*DBG* #PID<0.371.0> replying from :handle_ping with :pong
iex> EchoClient.echo(pid, "Close the things!")
*DBG* #PID<0.371.0> sending frame: {:text, "Close the things!"}
*DBG* #PID<0.371.0> received frame: {:text, "Close the things!"}
*DBG* #PID<0.371.0> closing with local reason: {:local, :normal}
*DBG* #PID<0.371.0> sending close frame: {:local, :normal}
*DBG* #PID<0.371.0> forcefully closed the connection because the server was taking too long close

You could also enable tracing after a process has started like this:

iex> {:ok, pid} = EchoClient.start_link()
iex> :sys.trace(pid, true)
iex> EchoClient.echo(pid, "Hi")
*DBG* #PID<0.379.0> sending frame: {:text, "Hi"}
*DBG* #PID<0.379.0> received frame: {:text, "Hi"}