WebSockex v0.4.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 error returned when a connection fails to be established
The frame sent when the negotiating a connection closure
The reason a connection was closed
A map that contains information about the failure to connect
Debug options to be parsed by :sys.debug_options/1
Options values for start_link
Functions
Asynchronously sends a message to a client that is handled by handle_cast/2
Sends a frame through the WebSocket
Starts a WebSockex
process
Starts a WebSockex
process linked to the current process
Callbacks
Invoked when a new version the module is loaded during runtime
Invoked to to retrieve a formatted status of the state in a WebSockex process
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
An integer between 1000 and 4999 that specifies the reason for closing the connection.
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.
The frame sent when the negotiating a connection closure.
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() :: %{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() :: [: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.
option :: WebSockex.Conn.connection_option | {:async, boolean} | {:debug, debug_opts} | {:name, atom} | {: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 totrue
a connection failure while establishing the initial connection won’t immediately return an error and instead will invoke thehandle_disconnect/2
callback. This option only matters during process initialization. Thehandle_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.
Other possible option values include: WebSockex.Conn.connection_option/0
Functions
Asynchronously sends a message to a client that is handled by handle_cast/2
.
handle_terminate_close(any, pid, any, any) :: no_return
init(pid, atom, WebSockex.Conn.t, module, term, options) :: {:ok, pid} | {:error, term}
send_frame(pid | atom, 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}}
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(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(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 :: 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(:normal, [process_dictionary | state]) :: status :: term when process_dictionary: [{key :: term, val :: term}], state: term
Invoked to 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 :: 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 :: 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 :: 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 inconn
.conn
is expected to be aWebSockex.Conn.t/0
.
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 :: 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 :: :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 :: :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.
Invoked when the process is terminating.