View Source MintWebsocketClient behaviour (MintWebsocketClient v0.1.1)

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, the MintWebsocketClient module will set @behaviour MintWebsocketClient and define a child_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

Link to this callback

handle_cast(request, state)

View Source
@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}.

Link to this callback

handle_connect(status_map, state)

View Source
@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.

Link to this callback

handle_disconnect(reason, state)

View Source
@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.

Link to this callback

handle_frame(frame, state)

View Source
@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.

Link to this callback

handle_info(message, state)

View Source
@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}.

@callback init(opts :: term()) :: {:ok, state :: term()}

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}.

Link to this callback

terminate(reason, state)

View Source
@callback terminate(reason :: term(), state :: term()) :: any()

Invoked when the server is about to exit. It should do any cleanup required.

This callback is optional.

Link to this section Functions

Link to this function

cast(server \\ __MODULE__, request)

View Source
@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.

Link to this function

send_frame(server \\ __MODULE__, frame)

View Source
@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.

Link to this function

start_link(url, handler, opts \\ [])

View Source
@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.