View Source MintWebsocketClient behaviour (MintWebsocketClient v0.1.0)
A behaviour module for implementing websocket clients.
example
Example
defmodule WS do
use MintWebsocketClient
def start_link(url, opts \ []) do
opts =
opts
|> Keyword.put_new(:name, __MODULE__)
|> Keyword.put_new(:protocols, [:http1])
MintWebsocketClient.start_link(url, __MODULE__, opts)
end
@impl true
def handle_connect(status_map, state) do
# subscribe
message = ~s|{"action": "subscribe"}|
{:reply, {:text, message}, state}
end
@impl true
def handle_disconnect(reason, state) do
# notify about disconnect
{:reconnect, state}
end
@impl true
def handle_frame(frame, state) do
# do handle frame
{:ok, state}
end
@impl true
def terminate(reason, _state) do
# do some cleanup if necessary
end
end
We leave all the hussle of opening/closing/reconnecting details to the MintWebsocketClient behaviour and focus only on the callback implementation. We can now use the MintWebsocketClient API to interact with the remote websocket service.
# Start the process
{:ok, pid} = WS.start_link("wss://feed.exchange.com/")
# Sends :ping frame to the server
MintWebsocketClient.send_frame(pid, :ping)
#=> :ok
# Casts request to the WS process
MintWebsocketClient.cast(pid, {:send_message, "elixir"})
#=> :ok
use Websocket
When you
use MintWebsocketClient
, theMintWebsocketClient
module will set@behaviour MintWebsocketClient
and define achild_spec/1
function, so your module can be used as a child in a supervision tree.
Link to this section Summary
Callbacks
Invoked to handle asynchronous cast/2
messages.
Invoked once the new ws connection established.
Invoked once the ws connection lost.
Invoked once the new websocket frame received.
Invoked to handle all other messages.
Invoked in process init.
Invoked when the server is about to exit. It should do any cleanup required.
Functions
Casts request to the underlying process.
Returns a specification to start this module under a supervisor.
Sends frame to the websocket server.
Starts the MintWebsocketClient
process linked to the current process.
Link to this section Callbacks
@callback handle_cast(request :: term(), state :: term()) :: {:ok, new_state :: term()} | {:reply, frame :: Mint.WebSocket.frame(), new_state :: term()} | {:close, frame :: Mint.WebSocket.frame(), new_state :: term()} | {:close, new_state :: term()}
Invoked to handle asynchronous cast/2
messages.
Returning {:ok, new_state}
continues the loop with new state new_state
.
Returning {:reply, frame, new_state}
sends the websocket frame
to the
server and continues the loop with new state new_state
.
Returning {:close, frame, new_state}
tries to close the connection gracefully
sending websocket frame
and waiting 5 seconds before actually close connection
and continues the loop with new state new_state
.
Returning {:close, new_state}
close the connection immediately
and continues the loop with new state new_state
.
This callback is optional. If one is not implemented, the default implementation
will return {:ok, new_state}
.
@callback handle_connect(status_map :: map(), state :: term()) :: {:ok, new_state :: term()} | {:reply, frame :: Mint.WebSocket.frame(), new_state :: term()}
Invoked once the new ws connection established.
Returning {:ok, new_state}
continues the loop with new state new_state
.
Returning {:reply, frame, new_state}
sends the websocket frame
to the
server and continues the loop with new state new_state
.
@callback handle_disconnect(reason :: term(), state :: term()) :: {:ok, new_state :: term()} | {:reconnect, timeout :: timeout(), new_state :: term()} | {:reconnect, new_state :: term()}
Invoked once the ws connection lost.
Returning {:ok, new_state}
continues the loop with new state new_state
.
Returning {:reconnect, timeout, new_state}
does reconnect to the server after specific timeout and
continues the loop with new state new_state
.
Returning {:reconnect, new_state}
does reconnect to the server immediately and
continues the loop with new state new_state
.
@callback handle_frame(frame :: Mint.WebSocket.frame(), state :: term()) :: {:ok, new_state :: term()} | {:reply, frame :: Mint.WebSocket.frame(), new_state :: term()}
Invoked once the new websocket frame received.
Returning {:ok, new_state}
continues the loop with new state new_state
.
Returning {:reply, frame, new_state}
sends the websocket frame
to the
server and continues the loop with new state new_state
.
@callback handle_info(message :: term(), state :: term()) :: {:ok, new_state :: term()} | {:reply, frame :: Mint.WebSocket.frame(), new_state :: term()} | {:close, frame :: Mint.WebSocket.frame(), new_state :: term()} | {:close, new_state :: term()}
Invoked to handle all other messages.
Return values are the same as handle_cast/2
.
This callback is optional. If one is not implemented, the default implementation
will return {:ok, new_state}
.
Invoked in process init.
Good place to initialize state and setup process flags.
This callback is optional. If one is not implemented, the default implementation
will return {:ok, nil}
.
Invoked when the server is about to exit. It should do any cleanup required.
This callback is optional.
Link to this section Functions
@spec cast(server :: GenServer.server(), request :: term()) :: :ok
Casts request to the underlying process.
Returns a specification to start this module under a supervisor.
See Supervisor
.
@spec send_frame(server :: GenServer.server(), frame :: Mint.WebSocket.frame()) :: :ok | {:error, :disconnected} | {:error, Mint.WebSocket.t(), any()} | {:error, Mint.HTTP.t(), Mint.WebSocket.error()}
Sends frame to the websocket server.
@spec start_link( url :: String.t() | URI.t(), handler :: module(), opts :: [{:name, atom()} | Keyword.t()] ) :: GenServer.on_start()
Starts the MintWebsocketClient
process linked to the current process.
options
Options
:name
- used for name registration
All available options see Mint.HTTP.connect/4
.