WebSockex v0.2.0 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
end

Summary

Types

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

The frame sent when the negotiating a connection closure

The reason a connection was closed

The error returned when a connection fails to be established

A map that contains information about the failure to connect

Options values for start_link

Functions

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

Queue a frame to be sent asynchronously

Starts a WebSockex process linked to the current process

Callbacks

Invoked when a new version the module is loaded during runtime

Invoked to handle asynchronous cast/2 messages

Invoked after a connection is established

Invoked when the WebSocket disconnects from the server

Invoked on the reception of a frame on the socket

Invoked to handle all other non-WebSocket messages

Invoked when the Websocket receives a ping frame

Invoked when the Websocket receives a pong frame

Invoked when the process is terminating

Types

close_code()
close_code() :: integer

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

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_error()
connection_error ::
  %WebSockex.RequestError{__exception__: term, code: term, message: term} |
  %WebSockex.ConnError{__exception__: term, original: term}

The error returned when a connection fails to be established.

connection_status_map()
connection_status_map() :: %{reason: close_reason | connection_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.

frame()
frame ::
  {:ping | :ping, nil | message :: binary} |
  {:text | :binary, message :: binary}
option()
option ::
  WebSockex.Conn.connection_option |
  {:async, boolean} |
  {: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.

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

options()
options() :: [option]

Functions

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

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

send_frame(pid, frame)
send_frame(pid, frame) ::
  :ok |
  {:error, WebSockex.FrameEncodeError.t}

Queue a frame to be sent asynchronously.

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

Starts a WebSockex process.

For available option values see option/0.

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

Starts a WebSockex process linked to the current process.

For available option values see option/0.

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

Callbacks

code_change(old_vsn, state, extra) (optional)
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.

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(state, conn)
handle_connect(state :: term, conn :: WebSockex.Conn.t) :: {: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) (optional)
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 even of a connection failure. In cases of crashes or other errors then 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) (optional)
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) (optional)
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) (optional)
terminate(close_reason, state :: term) :: any

Invoked when the process is terminating.