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
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
An integer between 1000 and 4999 that specifies the reason for closing the connection.
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_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() :: %{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.
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 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.
Other possible option values include: t:WebSockex.connection_option/0
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.
For available option values see option/0
.
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 :: 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 :: 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 :: 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 :: 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.