Dependency-Free, Compliant Websocket Server written in Elixir.

Kitchen sink not included. Every mandatory Autobahn Testsuite case is passing. (Three fragmented UTF-8 are flagged as non-strict and as compression is not implemented, these are all flagged as "Unimplemented")

If you're looking for a channel/room implementation, check out ExWsChannels.

Example

defmodule YourApp.YourWSHandler do
  # This is the only function you HAVE to define.
  # Note that WebSocket messages are just bytes that could represent
  # anything. ExWs exposes these bytes as-is (as an iodata). In most
  # cases, you'll probably want to decode that using JSON and process
  # the resulting payload, but exposing the raw bytes allows for 
  # a lot more possibilities.
  def message(data, state) do
    # be careful, data is an iodata
    case Jason.decode(data) do
      {:ok, data} -> process(data)
      _ -> close(3000, "invalid payload")
    end
  end

  defp process(%{"join" => channel}) do
    #...
  end
end

Usage

Include the dependency in your project:

{:exms, "~> 0.0.1"}

Define your handler:

defmodule YourApp.YourWSHandler do
  use ExWs.Handler

  def message(_data, state) do
    # do something with data
    state
  end
end

And start the server in your supervisor tree:

children = [
  # ...
  {ExWs.Supervisor, [port: 4545, handler: YourApp.YourWSHandler]}
]

Writing

From within your handler, you can use the write/1 function to send a message to the user:

def message(data, state) do
  # data is an iolist
  write(data) # echo the message back to the user
  state
end

Handshake

The handshake/3 callback lets you handle the initial handshake:

# this is the default implementation
def handshake(_path, _headers, state) do
  {:ok, state}
end

Where path is the requested URL path as a string, and headers is a map with lowercase string keys.

If you want to reject the handshake, say because the path/headers does not contain the correct authentication, return a {:close, ExWs.invalid_handshake/1}:

def handshake(_path, headers, state) do
  case lookup_one_time_token(headers["token"]) do
    {:ok, user_id} -> {:ok, %{user_id: user_id}} # set a new state
    _ -> {:close, ExWs.invalid_handshake("invalid_token")}
  end
end

Note that the value given to ExWs.invalid_handshale/1 (in the above case, we're talking about "invalid_token") is placed in the Error header of the handshake response (for troubleshooting purpose)

init

You can set the initial state by providing an init/0 callback:

# this is the default implementation
def init(), do: nil
````

### Closed
The `closed/2` callback is called whenever the socket is closed:

default closed/2 implementation

defp closed(_reason, state) do shutdown() state end

If you overwrite `closed/2`, you almost certainly want to call `shutdown/0` (it both closes the socket and shuts down the underlying GenServer).

## Handler Functions
Within your handler, the following functions are available:

- `ping/0` send a ping message to the client
- `write/1` writes the message to the client
- `close/0` close the connection
- `close2/` close the connection specifying a `code` and `message`. As per the specs, your `code` should be 3000-4999. Your message must be < 123 bytes.
- `get_socket/0` gets the underlying socket

Note that `get_socket/0` will return the socket during `init/0` and `closed/2` (but the socket can be closed by the other side at any point).

Note that if you call `close/0` directly, the `closed/2` callback will be executed.

## Write Optimizations
All WebSocket messages are framed and there's some overhead in creating this framing. When you call `write/1` with a binary value, the handler will frame your payload and write the framed message to the socket.

For static messages, you can opt to pre-frame the message using the `ExWs.bin/1` and `ExWs.txt/1` functions. `write/1` will detect these pre-framed messages and send them directly as-is.

defmodule YourApp.YourWSHandler do use ExWs.Handler

@message_over_9000 ExWs.txt(" 9000!!") def message("it's over", state) do

write(@message_over_9000)
state

end end

## txt vs bin
WebSocket has a separate message type for binary data and text data. Implementations must reject any message declared as txt which is not valid UTF8. 

This library does not do this validation. The `message/2` callback receives both text and binary messages.

If you want to differentiate between the two, implement `message/3` instead of `message/2`:

def message(op, data, state) do # op will be :txt or :bin end

The default `write/1` function uses the text type. You can override `write/1` to change this behavior:

defp write(data) do ExWs.write(get_socket(), ExWs.bin(data)) end

Or you can do it on a case-by-case basis:

write(ExWs.bin(some_data))

write(data)

as as

write(ExBin.txt(data))

## Direct Socket Usage
For performance reason, you may want to write directly to the socket, without going through the handler. For example, you might implement room/channel logic by storing the socket directly into the ETS table (writing to sockets from concurrent elixir processes is fine).

As we already saw, the `get_socket/0` helper will return the socket. But you cannot write to the socket directly using `gen_tcp.send/2` since weboscket messages must be framed.

You have two options, either use the `ExWs.bin/1` and `ExWs.txt/1` helpers to frame data:

:gen_tcp.send(socket, ExWs.txt("leto atreides"))

Or use the `ExWs.write/2` helper:

ExWs.write(socket, "leto atreides")

Note that `ExWs` also exposes `ping/1` and `close/1`.