A client handles negotiating the connection, then sending frames, receiving frames, closing, and reconnecting that connection.

A simple client implementation would be:

defmodule WsClient do
  use WebSockex

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

  def handle_frame({:text, msg}, state) do
    IO.puts "Received a message: #{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

Closing Connections

WebSockex connections can be closed gracefully by returning close tuples from callback functions. The following callbacks support close returns:

• handle_frame/2
• handle_cast/2
• handle_info/2
• handle_ping/2
• handle_pong/2

Basic Close

Return {:close, state} to close with the default close code (1000):

def handle_frame({:text, "quit"}, state) do
  {:close, state}
end

Close with Custom Code

Return {:close, {close_code, message}, state} to specify a close code and reason:

def handle_frame({:text, "error"}, state) do
  {:close, {4000, "Application error"}, state}
end

Close codes are integers in specific ranges:

• 1000-1015 - Standard protocol codes (e.g., 1000 = normal, 1001 = going away, 1002 = protocol error, 1003 = unsupported data)
• 3000-3999 - Reserved for use by libraries, frameworks, and applications (registered with IANA)
• 4000-4999 - Private use for applications

Common standard codes include:

• 1000 - Normal closure
• 1001 - Going away
• 1002 - Protocol error
• 1003 - Unsupported data

Supervision

WebSockex is implemented as an OTP Special Process and as a result will fit into supervision trees.

WebSockex also supports the Supervisor children format introduced in Elixir 1.5. Meaning that a child specification could be {ClientModule, [state]}.

However, since there is a possibility that you would like to provide a t:WebSockex.Conn/0 or a url as well as the state, there are two versions of the child_spec function. If you need functionality beyond that it is recommended that you override the function or define your own.

Just remember to use the version that corresponds with your start_link's arity.