websockex

# WebSockex

![Build](https://github.com/dominicletz/websockex/actions/workflows/ci.yml/badge.svg)

An Elixir Websocket Client.

A simple implementation could be

```elixir
defmodule WebSocketExample do
  use WebSockex

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

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

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

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`:

```elixir
def deps do
  [{:websockex, "~> 0.5.1"}]
end
```

## TLS verification

`wss://` connections verify the server certificate and hostname by default, using
the OS trust store on OTP 25+ or `:castore` when available. Add `:castore` to your
dependencies if your OTP version has no OS trust store support.

Pass `cacerts:` to supply custom CA certificates, or `ssl_options:` to control the
TLS options directly. Pass `insecure: true` to disable verification.

## IPv6

Hostnames are dialed with IPv4. Pass `inet_family: :inet6` to dial them with IPv6:

```elixir
WebSockex.start_link("wss://ipv6.example/ws", MyClient, %{}, inet_family: :inet6)
```

An IPv4 or IPv6 literal selects its own family, so `ws://[::1]:8080/ws` does not
need the option. With an HTTP CONNECT proxy, the family is the one used to reach
the proxy. An IPv6 target reached through an IPv4 proxy keeps the default.

## 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.

[gun_hex]: https://hex.pm/packages/gun

## 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:

```elixir
defmodule MyApp.Client do
  use WebSockex

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