WebSockex

v0.4.2

WebSockex v0.4.2 WebSockex behaviour

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

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.

Summary

Types

client()
close_code()

An integer between 1000 and 4999 that specifies the reason for closing the connection

close_error()

The error returned when a connection fails to be established

close_frame()

The frame sent when the negotiating a connection closure

close_reason()

The reason a connection was closed

connection_status_map()

A map that contains information about the failure to connect

debug_opts()

Debug options to be parsed by :sys.debug_options/1

frame()
option()

Options values for start_link

options()

Functions

cast(client, message)

Asynchronously sends a message to a client that is handled by handle_cast/2

handle_terminate_close(reason, parent, debug, state)
init(parent, name, conn, module, module_state, opts)
send_frame(client, frame)

Sends a frame through the WebSocket

start(conn_info, module, state, opts \\ [])

Starts a WebSockex process

start_link(conn_info, module, state, opts \\ [])

Starts a WebSockex process linked to the current process

Callbacks

code_change(old_vsn, state, extra)

Invoked when a new version the module is loaded during runtime

format_status(atom, list)

Invoked to retrieve a formatted status of the state in a WebSockex process

handle_cast(msg, state)

Invoked to handle asynchronous cast/2 messages

handle_connect(conn, state)

Invoked after a connection is established

handle_disconnect(connection_status_map, state)

Invoked when the WebSocket disconnects from the server

handle_frame(frame, state)

Invoked on the reception of a frame on the socket

handle_info(msg, state)

Invoked to handle all other non-WebSocket messages

handle_ping(ping_frame, state)

Invoked when the Websocket receives a ping frame

handle_pong(pong_frame, state)

Invoked when the Websocket receives a pong frame

terminate(close_reason, state)

Invoked when the process is terminating

Types

client() 
client ::
  pid |
  atom |
  {:via, module, term} |
  {:global, term}
close_code() 
close_code() :: integer

An integer between 1000 and 4999 that specifies the reason for closing the connection.

close_error() 
close_error ::
  %WebSockex.RequestError{__exception__: term, code: term, message: term} |
  %WebSockex.ConnError{__exception__: term, original: term} |
  %WebSockex.InvalidFrameError{__exception__: term, frame: term} |
  %WebSockex.FrameEncodeError{__exception__: term, close_code: term, frame_payload: term, frame_type: term, reason: term}

The error returned when a connection fails to be established.

close_frame() 
close_frame() :: {close_code, message :: binary}

The frame sent when the negotiating a connection closure.

close_reason() 
close_reason ::
  {:remote | :local, :normal} |
  {:remote | :local, close_code, message :: binary} |
  {:remote, :closed} |
  {:error, term}

The reason a connection was closed.

A :normal reason is the same as a 1000 reason with no payload.

If the peer closes the connection abruptly without a close frame then the close reason is {:remote, :closed}.

connection_status_map() 
connection_status_map() :: %{reason: close_reason | close_error, attempt_number: integer, conn: WebSockex.Conn.t}

A map that contains information about the failure to connect.

This map contains the error, attempt number, and the WebSockex.Conn.t/0 that was used to attempt the connection.

debug_opts() 
debug_opts() :: [:trace | :log | {:log, log_depth :: pos_integer} | :statistics | {:log_to_file, Path.t}]

Debug options to be parsed by :sys.debug_options/1.

These options can also be set after the process is running using the functions in the Erlang :sys module.

frame() 
frame ::
  :ping |
  :pong |
  {:ping | :pong, nil | message :: binary} |
  {:text | :binary, message :: binary}
option() 
option ::
  WebSockex.Conn.connection_option |
  {:async, boolean} |
  {:debug, debug_opts} |
  {:name, atom | {:global, term} | {:via, module, term}} |
  {:handle_initial_conn_failure, boolean}

Options values for start_link.

  • :async - Replies with {:ok, pid} before establishing the connection. This is useful for when attempting to connect indefinitely, this way the process doesn’t block trying to establish a connection.
  • :handle_initial_conn_failure - When set to true a connection failure while establishing the initial connection won’t immediately return an error and instead will invoke the handle_disconnect/2 callback. This option only matters during process initialization. The handle_disconnect callback is always invoked if an established connection is lost.
  • :debug - Options to set the debug options for :sys.handle_debug.
  • :name - An atom that the registers the process with name locally. Can also be a {:via, module, term} or {:global, term} tuple.

Other possible option values include: WebSockex.Conn.connection_option/0

options() 
options() :: [option]

Functions

cast(client, message) 
cast(client, term) :: :ok

Asynchronously sends a message to a client that is handled by handle_cast/2.

handle_terminate_close(reason, parent, debug, state) 
handle_terminate_close(any, pid, any, any) :: no_return
init(parent, name, conn, module, module_state, opts) 
init(pid, atom, WebSockex.Conn.t, module, term, options) ::
  {:ok, pid} |
  {:error, term}
send_frame(client, frame) 
send_frame(client, frame) ::
  :ok |
  {:error, %WebSockex.FrameEncodeError{__exception__: term, close_code: term, frame_payload: term, frame_type: term, reason: term} | %WebSockex.ConnError{__exception__: term, original: term} | %WebSockex.NotConnectedError{__exception__: term, connection_state: term} | %WebSockex.InvalidFrameError{__exception__: term, frame: term}} |
  none

Sends a frame through the WebSocket.

If the connection is either connecting or closing then this will return an error tuple with a WebSockex.NotConnectedError exception struct as the second element.

If a connection failure is discovered while sending then it will return an error tuple with a WebSockex.ConnError exception struct as the second element.

start(conn_info, module, state, opts \\ []) 
start(url :: String.t | WebSockex.Conn.t, module, term, options) ::
  {:ok, pid} |
  {:error, term}

Starts a WebSockex process.

Acts like start_link/4, except doesn’t link the current process.

See start_link/4 for more information.

start_link(conn_info, module, state, opts \\ []) 
start_link(url :: String.t | WebSockex.Conn.t, module, term, options) ::
  {:ok, pid} |
  {:error, term}

Starts a WebSockex process linked to the current process.

For available option values see option/0.

If a WebSockex.Conn.t is used in place of a url string, then the options available in WebSockex.Conn.connection_option/0 have effect.

The callback handle_connect/2 is invoked after the connection is established.

Callbacks

code_change(old_vsn, state, extra) 
code_change(old_vsn :: term | {:down, term}, state :: term, extra :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term}

Invoked when a new version the module is loaded during runtime.

format_status(atom, list) (optional) 
format_status(:normal, [process_dictionary | state]) :: status :: term when process_dictionary: [{key :: term, val :: term}], state: term

Invoked to retrieve a formatted status of the state in a WebSockex process.

This optional callback is used when you want to edit the values returned when invoking :sys.get_status.

The second argument is a two-element list with the order of [pdict, state].

handle_cast(msg, state) 
handle_cast(msg :: term, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked to handle asynchronous cast/2 messages.

handle_connect(conn, state) 
handle_connect(conn :: WebSockex.Conn.t, state :: term) :: {:ok, new_state :: term}

Invoked after a connection is established.

This is invoked after both the initial connection and a reconnect.

handle_disconnect(connection_status_map, state) 
handle_disconnect(connection_status_map, state :: term) ::
  {:ok, new_state} |
  {:reconnect, new_state} |
  {:reconnect, new_conn :: WebSockex.Conn.t, new_state} when new_state: term

Invoked when the WebSocket disconnects from the server.

This callback is only invoked in the event of a connection failure. In cases of crashes or other errors the process will terminate immediately skipping this callback.

If the handle_initial_conn_failure: true option is provided during process startup, then this callback will be invoked if the process fails to establish an initial connection.

If a connection is established by reconnecting, the handle_connect/2 callback will be invoked.

The possible returns for this callback are:

  • {:ok, state} will continue the process termination.
  • {:reconnect, state} will attempt to reconnect instead of terminating.
  • {:reconnect, conn, state} will attempt to reconnect with the connection data in conn. conn is expected to be a WebSockex.Conn.t/0.
handle_frame(frame, state) 
handle_frame(frame, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked on the reception of a frame on the socket.

The control frames have possible payloads, when they don’t have a payload then the frame will have nil as the payload. e.g. {:ping, nil}

handle_info(msg, state) 
handle_info(msg :: term, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked to handle all other non-WebSocket messages.

handle_ping(ping_frame, state) 
handle_ping(ping_frame :: :ping | {:ping, binary}, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked when the Websocket receives a ping frame

handle_pong(pong_frame, state) 
handle_pong(pong_frame :: :pong | {:pong, binary}, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked when the Websocket receives a pong frame.

terminate(close_reason, state) 
terminate(close_reason, state :: term) :: any

Invoked when the process is terminating.